Doc improvements.

Author: anthony-tuininga

doc/src/api_manual/async_cursor.rst

@@ -206,25 +206,25 @@ AsyncCursor Methods
 .. method:: AsyncCursor.fetchall()
 
     Fetches all (remaining) rows of a query result, returning them as a list of
-    tuples. An empty list is returned if no more rows are available. Note that
-    the cursor's ``arraysize`` attribute can affect the performance of this
-    operation, as internally reads from the database are done in batches
-    corresponding to ``arraysize``.
+    tuples. An empty list is returned if no more rows are available. An
+    exception is raised if the previous call to :meth:`AsyncCursor.execute()`
+    did not produce any result set or no call was issued yet.
 
-    An exception is raised if the previous call to
-    :meth:`AsyncCursor.execute()` did not produce any result set or no call
-    was issued yet.
+    Note that the cursor's :attr:`~AsyncCursor.arraysize` attribute can affect
+    the performance of this operation, as internally data is fetched in batches
+    of that size from the database.
 
 .. method:: AsyncCursor.fetchmany(size=cursor.arraysize)
 
     Fetches the next set of rows of a query result, returning a list of tuples.
     An empty list is returned if no more rows are available. Note that the
-    cursor's arraysize attribute can affect the performance of this operation.
+    cursor's :attr:`~AsyncCursor.arraysize` attribute can affect the
+    performance of this operation.
 
     The number of rows to fetch is specified by the parameter. If it is not
-    given, the cursor's arraysize attribute determines the number of rows to be
-    fetched. If the number of rows available to be fetched is fewer than the
-    amount requested, fewer rows will be returned.
+    given, the cursor's :attr:`~AsyncCursor.arraysize` attribute determines the
+    number of rows to be fetched. If the number of rows available to be fetched
+    is fewer than the amount requested, fewer rows will be returned.
 
     An exception is raised if the previous call to
     :meth:`AsyncCursor.execute()` did not produce any result set or no call
@@ -457,14 +457,15 @@ AsyncCursor Attributes
     the performance of a query since it directly affects the number of network
     round trips between Python and the database.  For methods like
     :meth:`AsyncCursor.fetchone()` and :meth:`AsyncCursor.fetchall()` it
-    does not change how many rows are returned to the application. For
-    :meth:`AsyncCursor.fetchmany()` it is the default number of rows to fetch.
+    affects internal behavior but does not change how many rows are returned to
+    the application. For :meth:`AsyncCursor.fetchmany()` it is the default
+    number of rows to fetch.
 
     The attribute is only used for tuning row and SODA document fetches from
     the database.  It does not affect data inserts.
 
-    Due to the performance benefits, the default ``Cursor.arraysize`` is *100*
-    instead of the *1* that the Python DB API recommends.
+    Due to the performance benefits, the default ``arraysize`` is *100* instead
+    of the *1* that the Python DB API recommends.
 
     See :ref:`Tuning Fetch Performance <tuningfetch>` for more information.
 

doc/src/api_manual/cursor.rst

@@ -212,26 +212,28 @@ Cursor Methods
 .. method:: Cursor.fetchall()
 
     Fetches all (remaining) rows of a query result, returning them as a list of
-    tuples. An empty list is returned if no more rows are available. Note that
-    the cursor's arraysize attribute can affect the performance of this
-    operation, as internally reads from the database are done in batches
-    corresponding to the arraysize.
+    tuples. An empty list is returned if no more rows are available. An
+    exception is raised if the previous call to :meth:`Cursor.execute()` did
+    not produce any result set or no call was issued yet.
 
-    An exception is raised if the previous call to :meth:`Cursor.execute()`
-    did not produce any result set or no call was issued yet.
+    Note that the cursor's :attr:`~Cursor.arraysize` attribute can affect the
+    performance of this operation, as internally data is fetched in batches of
+    that size from the database. See :ref:`Tuning Fetch Performance
+    <tuningfetch>`.
 
     See :ref:`fetching` for an example.
 
 .. method:: Cursor.fetchmany(size=cursor.arraysize)
 
     Fetches the next set of rows of a query result, returning a list of tuples.
     An empty list is returned if no more rows are available. Note that the
-    cursor's arraysize attribute can affect the performance of this operation.
+    cursor's :attr:`~Cursor.arraysize` attribute can affect the performance of
+    this operation.
 
     The number of rows to fetch is specified by the parameter. If it is not
-    given, the cursor's ``arraysize`` attribute determines the number of rows
-    to be fetched. If the number of rows available to be fetched is fewer than
-    the amount requested, fewer rows will be returned.
+    given, the cursor's :attr:`~Cursor.arraysize` attribute determines the
+    number of rows to be fetched. If the number of rows available to be fetched
+    is fewer than the amount requested, fewer rows will be returned.
 
     An exception is raised if the previous call to :meth:`Cursor.execute()`
     did not produce any result set or no call was issued yet.
@@ -480,15 +482,16 @@ Cursor Attributes
     from SELECT statements and REF CURSORS.  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.
+    :meth:`Cursor.fetchone()` and :meth:`Cursor.fetchall()` it affects internal
+    behavior but does not change how many rows are returned to the
+    application. For :meth:`Cursor.fetchmany()` it is the default number of
+    rows to fetch.
 
     The attribute is only used for tuning row and SODA document fetches from
     the database.  It does not affect data inserts.
 
-    Due to the performance benefits, the default ``Cursor.arraysize`` is *100*
-    instead of the *1* that the Python DB API recommends.
+    Due to the performance benefits, the default ``arraysize`` is *100* instead
+    of the *1* that the Python DB API recommends.
 
     See :ref:`Tuning Fetch Performance <tuningfetch>` for more information.
 

doc/src/api_manual/module.rst

@@ -412,8 +412,15 @@ Oracledb Methods
 
     The ``pool_name`` parameter is expected to be a string which specifies the
     name of the pool when using multiple DRCP pools with Oracle Database 23.4
-    or later. This value is used in both python-oracledb Thin and Thick modes.
-    See :ref:`DRCP Pool Names <poolnames>`.
+    or later. This parameter can be used in both python-oracledb Thin and Thick
+    modes. However, in Thick mode, when the ``thick_mode_dsn_passthrough``
+    value in effect is *True*, it can only be used if the ``dsn`` parameter is
+    not specified. For Thick mode, you may prefer to set the Oracle Net
+    Services parameter `POOL_NAME <https://www.oracle.com/pls/topic/lookup?ctx=
+    dblatest&id=GUID-C2DA6A42-C30A-4E4C-9833-51CB383FE08B>`__ parameter in the
+    :ref:`easy connect string <easyconnect>` or
+    :ref:`connect descriptor <conndescriptor>`. See
+    :ref:`DRCP Pool Names <poolnames>`.
 
     If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
     and is only of use when embedding Python in an application (like
@@ -771,8 +778,15 @@ Oracledb Methods
 
     The ``pool_name`` parameter is expected to be a string which specifies the
     name of the pool when using multiple DRCP pools with Oracle Database 23.4
-    or later. This value is used in both python-oracledb Thin and Thick modes.
-    See :ref:`DRCP Pool Names <poolnames>`.
+    or later. This parameter can be used in both python-oracledb Thin and Thick
+    modes. However, in Thick mode, when the ``thick_mode_dsn_passthrough``
+    value in effect is *True*, it can only be used if the ``dsn`` parameter is
+    not specified. For Thick mode, you may prefer to set the Oracle Net
+    Services parameter `POOL_NAME <https://www.oracle.com/pls/topic/lookup?ctx=
+    dblatest&id=GUID-C2DA6A42-C30A-4E4C-9833-51CB383FE08B>`__ parameter in the
+    :ref:`easy connect string <easyconnect>` or
+    :ref:`connect descriptor <conndescriptor>`. See
+    :ref:`DRCP Pool Names <poolnames>`.
 
     The ``thick_mode_dsn_passthrough`` and ``handle`` parameters are ignored in
     python-oracledb Thin mode.
@@ -1663,8 +1677,15 @@ Oracledb Methods
 
     The ``pool_name`` parameter is expected to be a string which specifies the
     name of the pool when using multiple DRCP pools with Oracle Database 23.4
-    or later. This value is used in both python-oracledb Thin and Thick modes.
-    See :ref:`DRCP Pool Names <poolnames>`.
+    or later. This parameter can be used in both python-oracledb Thin and Thick
+    modes. However, in Thick mode, when the ``thick_mode_dsn_passthrough``
+    value in effect is *True*, it can only be used if the ``dsn`` parameter is
+    not specified. For Thick mode, you may prefer to set the Oracle Net
+    Services parameter `POOL_NAME <https://www.oracle.com/pls/topic/lookup?ctx=
+    dblatest&id=GUID-C2DA6A42-C30A-4E4C-9833-51CB383FE08B>`__ parameter in the
+    :ref:`easy connect string <easyconnect>` or
+    :ref:`connect descriptor <conndescriptor>`. See
+    :ref:`DRCP Pool Names <poolnames>`.
 
     If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
     and is only of use when embedding Python in an application (like
@@ -2085,8 +2106,15 @@ Oracledb Methods
 
     The ``pool_name`` parameter is expected to be a string which specifies the
     name of the pool when using multiple DRCP pools with Oracle Database 23.4
-    or later. This value is used in both python-oracledb Thin and Thick modes.
-    See :ref:`DRCP Pool Names <poolnames>`.
+    or later. This parameter can be used in both python-oracledb Thin and Thick
+    modes. However, in Thick mode, when the ``thick_mode_dsn_passthrough``
+    value in effect is *True*, it can only be used if the ``dsn`` parameter is
+    not specified. For Thick mode, you may prefer to set the Oracle Net
+    Services parameter `POOL_NAME <https://www.oracle.com/pls/topic/lookup?ctx=
+    dblatest&id=GUID-C2DA6A42-C30A-4E4C-9833-51CB383FE08B>`__ parameter in the
+    :ref:`easy connect string <easyconnect>` or
+    :ref:`connect descriptor <conndescriptor>`. See
+    :ref:`DRCP Pool Names <poolnames>`.
 
     The ``handle`` and ``thick_mode_dsn_passthrough`` parameters are ignored in
     python-oracledb Thin mode.

doc/src/user_guide/appendix_b.rst

@@ -188,6 +188,13 @@ differs from the python-oracledb Thick mode in the following ways:
 * In python-oracledb Thin mode, the connection pool supports all the :ref:`connection
   mode privileges <connection-authorization-modes>`.
 
+* In python-oracledb Thick mode, when the ``thick_mode_dsn_passthrough`` value
+  in effect is *True*, the ``pool_name`` parameter can be used to specify a
+  DRCP pool name only if the ``dsn`` parameter is not set. If both of these
+  parameters are specified, then the ``pool_name`` parameter is ignored. In
+  python-oracledb Thin mode, both of these parameters can be set and the value
+  defined in the ``pool_name`` parameter will be used as the DRCP pool name.
+
 Supported Database Data Types in Thin and Thick Modes
 =====================================================
 

doc/src/user_guide/connection_handling.rst

@@ -3115,9 +3115,9 @@ The overheads can impact ultimate scalability.
 **DRCP Pool Names**
 
 From Oracle Database 23ai, multiple DRCP pools can be created by setting a pool
-name at DRCP pool creation time. Applications can then specifiy which DRCP pool
-to use by passing the ``pool_name`` parameter during connection, or connection
-pool, creation, for example:
+name at DRCP pool creation time. Applications using python-oracledb Thin mode
+can specify which DRCP pool to use by passing the ``pool_name`` parameter
+during connection or connection pool creation, for example:
 
 .. code-block:: python
 
@@ -3129,6 +3129,43 @@ pool, creation, for example:
 When specifying a pool name, you should still set a connection class name to
 allow efficient use of the pool's resources.
 
+If you are using python-oracledb Thick mode and the
+``thick_mode_dsn_passthrough`` value in effect is *True*, you can use the
+``pool_name`` parameter only if the ``dsn`` parameter is not specified when
+creating a standalone or pooled connection, for example:
+
+.. code-block:: python
+
+    oracledb.init_oracle_client()
+
+    pool = oracledb.create_pool(user="hr", password=userpwd,
+                                host="localhost", service_name="orclpdb",
+                                server_type="pooled", min=2, max=5,
+                                increment=1, cclass="MYAPP",
+                                pool_name="MYPOOL")
+
+If both the ``pool_name`` and ``dsn`` parameters are set when using Thick mode,
+the ``pool_name`` parameter is ignored.
+
+For Thick mode, you may prefer to set the Oracle Net
+Services parameter `POOL_NAME <https://www.oracle.com/pls/topic/lookup?ctx=
+dblatest&id=GUID-C2DA6A42-C30A-4E4C-9833-51CB383FE08B>`__ parameter in the
+:ref:`easy connect string <easyconnect>` or
+:ref:`connect descriptor <conndescriptor>`, for example:
+
+.. code-block:: python
+
+    oracledb.init_oracle_client()
+
+    pool = oracledb.create_pool(user="hr", password=userpwd,
+                                dsn="dbhost.example.com/orclpdb:pooled?pool_name=mypool",
+                                min=2, max=5, increment=1,
+                                cclass="MYAPP")
+
+You can also define the DRCP pool name with the
+:ref:`ConnectParams class <connparam>` when using python-oracledb Thin or Thick
+mode. See :ref:`usingconnparams`.
+
 **Acquiring a DRCP Connection**
 
 Once DRCP has been enabled and the driver connection pool has been created with

doc/src/user_guide/tuning.rst

@@ -79,10 +79,15 @@ Some general tuning tips are:
 Tuning Fetch Performance
 ========================
 
-To tune queries, you can adjust python-oracledb's internal buffer sizes to
-improve the speed of fetching rows across the network from the database, and to
-optimize memory usage.  This can reduce :ref:`round-trips <roundtrips>` which
-helps performance and scalability.  Tune "array fetching" with
+To improve application performance and scalability you can adjust the sizes of
+python-oracledb's internal query result buffers. Increasing the buffers can
+reduce :ref:`round-trips <roundtrips>` to improve the overall speed of fetching
+rows across the network from the database. The buffer sizes can be used to tune
+the behavior of all python-oracledb :ref:`row fetching methods <fetching>` but
+do not affect how many rows are returned to your application by those methods.
+You should tune the buffers for optimal performance and memory usage.
+
+Tune "array fetching" with
 :attr:`Cursor.arraysize` and tune "row prefetching" with
 :attr:`Cursor.prefetchrows`.  Set these before calling
 :meth:`Cursor.execute()`.  The value used for prefetching can also be set in an
@@ -92,11 +97,6 @@ separate, so increasing both settings will require more Python process memory.
 Queries that return LOBs and similar types will never prefetch rows, so the
 ``prefetchrows`` value is ignored in those cases.
 
-The internal buffer sizes do not affect how or when rows are returned to your
-application regardless of which :ref:`python-oracledb method <fetching>` is
-used to fetch query results.  They do not affect the minimum or maximum number
-of rows returned by a query.
-
 The difference between row prefetching and array fetching is when the internal
 buffering occurs.  Internally python-oracledb performs separate "execute SQL
 statement" and "fetch data" steps.  Prefetching allows query results to be