Documentation improvements.

doc/src/api_manual/cursor.rst

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

doc/src/api_manual/module.rst

@@ -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
+    This is False in all cases unless both Oracle Database 12.1 (or later) and
-    both the server and the client.
+    Oracle Client 12.1 (or later) are being used.
 
     .. versionadded:: 5.3
 

doc/src/api_manual/soda.rst

@@ -416,9 +416,11 @@ SODA Operation Object
 
 .. method:: SodaOperation.fetchArraySize(value)
 
-    Specifies the numnber of documents that are fetched at a single time from
+    This is a tuning method to specify the number of documents that are
-    the SODA collection. A value of 0 will use the default value (100). This
+    internally fetched in batches by calls to :meth:`~SodaOperation.getCursor()`
-    method is only available in Oracle Client 19.5 and higher.
+    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.

doc/src/api_manual/variable.rst

@@ -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.
 

doc/src/index.rst

@@ -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
 

doc/src/user_guide/connection_handling.rst

@@ -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

doc/src/user_guide/ha.rst

@@ -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
+Options such as `SQLNET.OUTBOUND_CONNECT_TIMEOUT
-<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-F20C5DC5-C2FC-4145-9E4E-345CCB8148C7>`__,
+<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

doc/src/user_guide/installation.rst

@@ -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
+   To avoid interfering with existing tools that require other Oracle Client
-   Client versions, instead of updating the system-wide ``PATH`` variable, you
+   versions, instead of updating the system-wide ``PATH`` variable you can set
-   may prefer to write a batch file that sets ``PATH``, for example::
+   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
+   This will create a directory ``/Users/yourname/instantclient_19_3``.
-   applications to find the library. For example::
+
+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.

doc/src/user_guide/introduction.rst

@@ -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

doc/src/user_guide/sql_execution.rst

@@ -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
 ------------------------

doc/src/user_guide/startup.rst

@@ -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)