HackBase/python-cx_Oracle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation improvements.

Browse Source
This commit is contained in:
Anthony Tuininga 2020-04-06 13:52:58 -06:00
parent 3a4ee32022
commit 9377a9a0ef
11 changed files with 125 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
doc/src/api_manual/cursor.rst
View File

@ -25,14 +25,19 @@ Cursor Object
.. attribute:: Cursor.arraysize
This read-write attribute specifies the number of rows to fetch at a time
internally and is the default number of rows to fetch with the
:meth:`~Cursor.fetchmany()` call. It defaults to 100 meaning to fetch 100
rows at a time. Note that this attribute can drastically affect the
performance of a query since it directly affects the number of network
round trips that need to be performed. This is the reason for setting it to
100 instead of the 1 that the DB API recommends.
This read-write attribute can be used to tune the number of rows internally
fetched and buffered by internal calls to the database. The value can
drastically affect the performance of a query since it directly affects the
number of network round trips between Python and the database. For methods
like :meth:`~Cursor.fetchone()` and :meth:`~Cursor.fetchall()` it does not
change how many rows are returned to the application. For
:meth:`~Cursor.fetchmany()` it is the default number of rows to fetch.
Due to the performance benefits, the default ``Cursor.arraysize`` is 100
instead of the 1 that the DB API recommends. This value means that 100 rows
are fetched by each internal call to the database.
See :ref:`Tuning Fetch Performance <tuningfetch>`.
.. attribute:: Cursor.bindarraysize

4
doc/src/api_manual/module.rst
View File

@ -1441,8 +1441,8 @@ Exception handling
.. attribute:: _Error.isrecoverable
Boolean attribute representing whether the error is recoverable or not.
This is False in all cases unless Oracle Database 12.1 is being used on
both the server and the client.
This is False in all cases unless both Oracle Database 12.1 (or later) and
Oracle Client 12.1 (or later) are being used.
.. versionadded:: 5.3

8
doc/src/api_manual/soda.rst
View File

@ -416,9 +416,11 @@ SODA Operation Object
.. method:: SodaOperation.fetchArraySize(value)
Specifies the numnber of documents that are fetched at a single time from
the SODA collection. A value of 0 will use the default value (100). This
method is only available in Oracle Client 19.5 and higher.
This is a tuning method to specify the number of documents that are
internally fetched in batches by calls to :meth:`~SodaOperation.getCursor()`
and :meth:`~SodaOperation.getDocuments()`. It does not affect how many
documents are returned to the application. A value of 0 will use the default
value (100). This method is only available in Oracle Client 19.5 and higher.
As a convenience, the SodaOperation object is returned so that further
criteria can be specified by chaining methods together.

2
doc/src/api_manual/variable.rst
View File

@ -51,7 +51,7 @@ Variable Objects
.. attribute:: Variable.outconverter
This read-write attribute specifies the method used to convert data from
from the Oracle to Python. The method signature is converter(value)
the Oracle database to Python. The method signature is converter(value)
and the expected return value is the value to return to Python. If this
attribute is None, the value is returned directly without any conversion.

1
doc/src/index.rst
View File

@ -35,6 +35,7 @@ User Guide
user_guide/cqn.rst
user_guide/txn_management.rst
user_guide/globalization.rst
user_guide/startup.rst
user_guide/ha.rst
user_guide/tracing_sql.rst

45
doc/src/user_guide/connection_handling.rst
View File

@ -1243,51 +1243,6 @@ This is equivalent to executing the following in SQL*Plus:
GRANT SYSOPER TO hr;
Starting and Stopping Oracle Database
=====================================
cx_Oracle has the capability of starting up the database using a privileged
connection. This example shows a script that could be run as the 'oracle'
operating system user who administers a local database installation on Linux.
It assumes that the environment variable ``ORACLE_SID`` has been set to the SID
of the database that should be started:
.. code-block:: python
# the connection must be in PRELIM_AUTH mode to perform startup
connection = cx_Oracle.connect("/",
mode = cx_Oracle.SYSDBA | cx_Oracle.PRELIM_AUTH)
connection.startup()
# the following statements must be issued in normal SYSDBA mode
connection = cx_Oracle.connect("/", mode = cx_Oracle.SYSDBA, encoding="UTF-8")
cursor = connection.cursor()
cursor.execute("alter database mount")
cursor.execute("alter database open")
Similarly, cx_Oracle has the ability to shutdown the database using a
privileged connection. This example also assumes that the environment variable
``ORACLE_SID`` has been set:
.. code-block:: python
# need to connect as SYSDBA or SYSOPER
connection = cx_Oracle.connect("/", mode = cx_Oracle.SYSDBA)
# first shutdown() call must specify the mode, if DBSHUTDOWN_ABORT is used,
# there is no need for any of the other steps
connection.shutdown(mode = cx_Oracle.DBSHUTDOWN_IMMEDIATE)
# now close and dismount the database
cursor = connection.cursor()
cursor.execute("alter database close normal")
cursor.execute("alter database dismount")
# perform the final shutdown call
connection.shutdown(mode = cx_Oracle.DBSHUTDOWN_FINAL)
.. _netencrypt:
Securely Encrypting Network Traffic to Oracle Database

4
doc/src/user_guide/ha.rst
View File

@ -35,8 +35,8 @@ Network Configuration
The operating system TCP and :ref:`Oracle Net configuration <optnetfiles>`
should be configured for performance and availability.
Options such as `SQLNET.CONNECT_TIMEOUT
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-F20C5DC5-C2FC-4145-9E4E-345CCB8148C7>`__,
Options such as `SQLNET.OUTBOUND_CONNECT_TIMEOUT
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-0857C817-675F-4CF0-BFBB-C3667F119176>`__,
`SQLNET.RECV_TIMEOUT
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-4A19D81A-75F0-448E-B271-24E5187B5909>`__
and `SQLNET.SEND_TIMEOUT

49
doc/src/user_guide/installation.rst
View File

@ -440,15 +440,28 @@ To use cx_Oracle with Oracle Instant Client zip files:
Restart any open command prompt windows.
To avoid interfering with existing tools that require other Oracle
Client versions, instead of updating the system-wide ``PATH`` variable, you
may prefer to write a batch file that sets ``PATH``, for example::
To avoid interfering with existing tools that require other Oracle Client
versions, instead of updating the system-wide ``PATH`` variable you can set
the value for each script.
One way is to set it inside the application before cx_Oracle is used for the
first time:
.. code-block:: python
import os
os.environ['PATH'] = r'C:\instantclient_19_3' + os.pathsep + os.environ['PATH]
Note this only works on Windows.
Another alternative way to set ``PATH`` is to use a batch file that sets it
before Python is executed, for example::
REM mypy.bat
SET PATH=C:\oracle\instantclient_19_3;%PATH%
python %*
Invoke this batch file every time you want to run python.
Invoke this batch file every time you want to run Python.
Alternatively use ``SET`` to change your ``PATH`` in each command
prompt window before you run python.
@ -527,6 +540,9 @@ If you are behind a proxy, specify your proxy server::
python -m pip install cx_Oracle --proxy=http://proxy.example.com:80 --upgrade
The ``--user`` option may also be useful, if you don't have permission to write
to ``/usr``.
The source will be downloaded, compiled, and the resulting binary
installed.
@ -537,7 +553,7 @@ Install Oracle Instant Client
cx_Oracle requires Oracle Client libraries, which are found in Oracle
Instant Client for macOS. These provide the necessary network
connectivity allowing cx_Oracle to access an Oracle Database
instance. Oracle Client versions 18, 12 and 11.2 are supported.
instance. Oracle Client versions 19, 18, 12 and 11.2 are supported.
To use cx_Oracle with Oracle Instant Client zip files:
@ -547,33 +563,40 @@ To use cx_Oracle with Oracle Instant Client zip files:
Python architecture.
2. Unzip the package into a single directory that is accessible to your
application. For example::
application. For example, in Terminal you could unzip in your home directory::
mkdir -p /opt/oracle
cd ~
unzip instantclient-basic-macos.x64-19.3.0.0.0dbru.zip
3. Add links to ``$HOME/lib`` or ``/usr/local/lib`` to enable
applications to find the library. For example::
This will create a directory ``/Users/yourname/instantclient_19_3``.
3. Add a link to ``$HOME/lib`` or ``/usr/local/lib`` to enable applications to
find Instant Client. If the ``lib`` sub-directory does not exist, you can
create it. For example::
mkdir ~/lib
ln -s /opt/oracle/instantclient_19_3/libclntsh.dylib ~/lib/
ln -s ~/instantclient_19_3/libclntsh.dylib ~/lib/
If you now run ``ls -l ~/lib/libclntsh.dylib`` you will see something like::
lrwxr-xr-x 1 yourname staff 48 12 Nov 15:04 /Users/yourname/lib/libclntsh.dylib -> /Users/yourname/instantclient_19_3/libclntsh.dylib
Alternatively, copy the required OCI libraries. For example::
mkdir ~/lib
cp /opt/oracle/instantclient_19_3/{libclntsh.dylib.19.1,libclntshcore.dylib.19.1,libnnz19.dylib,libociei.dylib} ~/lib/
cp ~/instantclient_19_3/{libclntsh.dylib.19.1,libclntshcore.dylib.19.1,libnnz19.dylib,libociei.dylib} ~/lib/
For Instant Client 11.2, the OCI libraries must be copied. For example::
mkdir ~/lib
cp /opt/oracle/instantclient_11_2/{libclntsh.dylib.11.1,libnnz11.dylib,libociei.dylib} ~/lib/
cp ~/instantclient_11_2/{libclntsh.dylib.11.1,libnnz11.dylib,libociei.dylib} ~/lib/
4. If you intend to co-locate optional Oracle configuration files such
as ``tnsnames.ora``, ``sqlnet.ora`` or ``oraaccess.xml`` with
Instant Client, then create a ``network/admin`` subdirectory, if it
does not already exist. For example::
mkdir -p /opt/oracle/instantclient_12_2/network/admin
mkdir -p ~/instantclient_12_2/network/admin
This is the default Oracle configuration directory for executables
linked with this Instant Client.

3
doc/src/user_guide/introduction.rst
View File

@ -13,7 +13,8 @@ Architecture
------------
Python programs call cx_Oracle functions. Internally cx_Oracle dynamically
loads Oracle Client libraries to access Oracle Database.
loads Oracle Client libraries to access Oracle Database. The database can be on
the same machine as Python, or it can be remote.
.. _archfig:
.. figure:: /images/cx_Oracle_arch.png

1
doc/src/user_guide/sql_execution.rst
View File

@ -127,6 +127,7 @@ This code ensures that, once the block is completed, the cursor is closed and
resources have been reclaimed by the database. In addition, any attempt to use
the variable ``cursor`` outside of the block will simply fail.
.. _tuningfetch:
Tuning Fetch Performance
------------------------

63
doc/src/user_guide/startup.rst Normal file
View File

@ -0,0 +1,63 @@
.. _startup:
*************************************
Starting and Stopping Oracle Database
*************************************
This chapter covers how to start up and shutdown Oracle Database using
cx_Oracle.
===========================
Starting Oracle Database Up
===========================
cx_Oracle can start up a database instance. A privileged connection is
required. This example shows a script that could be run as the 'oracle'
operating system user who administers a local database installation on Linux.
It assumes that the environment variable ``ORACLE_SID`` has been set to the SID
of the database that should be started:
.. code-block:: python
# the connection must be in PRELIM_AUTH mode to perform startup
connection = cx_Oracle.connect("/",
mode = cx_Oracle.SYSDBA | cx_Oracle.PRELIM_AUTH)
connection.startup()
# the following statements must be issued in normal SYSDBA mode
connection = cx_Oracle.connect("/", mode = cx_Oracle.SYSDBA, encoding="UTF-8")
cursor = connection.cursor()
cursor.execute("alter database mount")
cursor.execute("alter database open")
To start up a remote database, you may need to configure the Oracle Net
listener to use `static service registration
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
id=GUID-0203C8FA-A4BE-44A5-9A25-3D1E578E879F>`_
by adding a ``SID_LIST_LISTENER`` entry to the database `listener.ora` file.
=============================
Shutting Oracle Database Down
=============================
cx_Oracle has the ability to shutdown the database using a privileged
connection. This example also assumes that the environment variable
``ORACLE_SID`` has been set:
.. code-block:: python
# need to connect as SYSDBA or SYSOPER
connection = cx_Oracle.connect("/", mode = cx_Oracle.SYSDBA)
# first shutdown() call must specify the mode, if DBSHUTDOWN_ABORT is used,
# there is no need for any of the other steps
connection.shutdown(mode = cx_Oracle.DBSHUTDOWN_IMMEDIATE)
# now close and dismount the database
cursor = connection.cursor()
cursor.execute("alter database close normal")
cursor.execute("alter database dismount")
# perform the final shutdown call
connection.shutdown(mode = cx_Oracle.DBSHUTDOWN_FINAL)