Added attribute cursor.prefetchrows to control the number of rows that the

Oracle Client library fetches into internal buffers when a query is
executed (#355).

Author: anthony-tuininga

doc/src/api_manual/connection.rst

@@ -552,6 +552,10 @@ Connection Object
     value can make a significant difference in performance (up to 100x) if you
     have a small number of statements that you execute repeatedly.
 
+    The default value is 20.
+
+    See :ref:`Statement Caching <stmtcache>` for more information.
+
     .. note::
 
         This attribute is an extension to the DB API definition.

doc/src/api_manual/cursor.rst

@@ -37,7 +37,7 @@ Cursor Object
     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>`.
+    See :ref:`Tuning Fetch Performance <tuningfetch>` for more information.
 
 .. attribute:: Cursor.bindarraysize
 
@@ -442,6 +442,21 @@ Cursor Object
         immediately and an implied commit takes place.
 
 
+.. attribute:: Cursor.prefetchrows
+
+    This read-write attribute can be used to tune the number of rows that the
+    Oracle Client library fetches when a query is executed. This value can
+    reduce the number of round-trips to the database that are required to
+    fetch rows but at the cost of additional memory. Setting this value to 0
+    can be useful when the timing of fetches must be explicitly controlled.
+
+    See :ref:`Tuning Fetch Performance <tuningfetch>` for more information.
+
+    .. note::
+
+        The DB API definition does not define this method.
+
+
 .. method:: Cursor.prepare(statement, [tag])
 
     This can be used before a call to :meth:`~Cursor.execute()` to define the
@@ -451,6 +466,8 @@ Cursor Object
     statement will be returned to the statement cache with the given tag. See
     the Oracle documentation for more information about the statement cache.
 
+    See :ref:`Statement Caching <stmtcache>` for more information.
+
     .. note::
 
         The DB API definition does not define this method.

doc/src/index.rst

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

doc/src/release_notes.rst

@@ -51,6 +51,9 @@ Version 8.0 (TBD)
     available in Oracle Client 20 and higher.
 #)  Added function :meth:`SodaOperation.fetchArraySize()` available in Oracle
     Client 19.5 and higher.
+#)  Added attribute :attr:`Cursor.prefetchrows` to control the number of rows
+    that the Oracle Client library fetches into internal buffers when a query
+    is executed.
 #)  Internally make use of new mode available in Oracle Client 20 and higher in
     order to avoid a round-trip when accessing :attr:`Connection.version` for
     the first time.

doc/src/user_guide/sql_execution.rst

@@ -130,93 +130,6 @@ 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
-------------------------
-
-For best performance, the cx_Oracle :attr:`Cursor.arraysize` value should be set
-before calling :meth:`Cursor.execute()`.  The default value is 100.  For queries
-that return a large number of rows, increasing ``arraysize`` can improve
-performance because it reduces the number of :ref:`round-trips <roundtrips>` to
-the database.  However increasing this value increases the amount of memory
-required.  The best value for your system depends on factors like your network
-speed, the query row size, and available memory.  An appropriate value can be
-found by experimenting with your application.
-
-Regardless of which fetch method is used to get rows, internally all rows are
-fetched in batches corresponding to the value of ``arraysize``.  The size does
-not affect how, or when, rows are returned to your application (other than being
-used as the default size for :meth:`Cursor.fetchmany()`).  It does not limit the
-minimum or maximum number of rows returned by a query.
-
-Along with tuning ``arraysize``, make sure your `SQL statements are optimal
-<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=TGSQL>`_ and avoid
-selecting columns that are not required by the application. For queries that do
-not need to fetch all data, use appropriate ``WHERE`` clauses such as a
-:ref:`row limiting clause <rowlimit>` to reduce the number of rows processed by
-the database. For small, mostly static, lookup tables enable :ref:`Client Result
-Caching <crc>` to avoid round-trips between cx_Oracle and the database. For
-queries that return large data or a large number of rows, or when using a slow
-network, tune the network `Session Data Unit (SDU) and socket buffer sizes
-<https://static.rainfocus.com/oracle/oow19/sess/1553616880266001WLIh/PF/OOW19_Net_CON4641_1569022126580001esUl.pdf>`__.
-
-An example of setting ``arraysize`` is:
-
-.. code-block:: python
-
-    cur = connection.cursor()
-    cur.arraysize = 500
-    for row in cur.execute("select * from MyTable"):
-        print(row)
-
-One place where increasing ``arraysize`` is particularly useful is in copying
-data from one database to another:
-
-.. code-block:: python
-
-    # setup cursors
-    sourceCursor = sourceConnection.cursor()
-    sourceCursor.arraysize = 1000
-    targetCursor = targetConnection.cursor()
-    targetCursor.arraysize = 1000
-
-    # perform fetch and bulk insertion
-    sourceCursor.execute("select * from MyTable")
-    while True:
-        rows = sourceCursor.fetchmany()
-        if not rows:
-            break
-        targetCursor.executemany("insert into MyTable values (:1, :2)", rows)
-        targetConnection.commit()
-
-If you know that a query returns a small number of rows then you should reduce
-the value of ``arraysize``.  For example if you are fetching only one row, then
-set ``arraysize`` to 1:
-
-.. code-block:: python
-
-    cur = connection.cursor()
-    cur.arraysize = 1
-    cur.execute("select * from MyTable where id = 1"):
-    row = cur.fetchone()
-    print(row)
-
-In cx_Oracle, the ``arraysize`` value is only examined when a statement is
-executed the first time.  To change the ``arraysize`` for a repeated statement,
-create a new cursor:
-
-.. code-block:: python
-
-    array_sizes = (10, 100, 1000)
-    for size in array_sizes:
-        cursor = connection.cursor()
-        cursor.arraysize = size
-        start = time.time()
-        cursor.execute(sql).fetchall()
-        elapsed = time.time() - start
-        print("Time for", size, elapsed, "seconds")
-
 .. _querymetadata:
 
 Query Column Metadata
@@ -808,72 +721,3 @@ SDO_GEOMETRY <spatial>` object:
     cur = connection.cursor()
     cur.setinputsizes(typeObj)
     cur.execute("insert into sometable values (:1)", [None])
-
-.. _roundtrips:
-
-Database Round-trips
-====================
-
-A round-trip is defined as the trip from the Oracle Client libraries (:ref:`used by
-cx_Oracle <archfig>`) to the database and back.  Along with tuning an application's
-architecture and tuning its SQL statements, a general performance and
-scalability goal is to minimize `round-trips
-<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-9B2F05F9-D841-4493-A42D-A7D89694A2D1>`__.
-
-Some general tips for reducing round-trips are:
-
-- Tune :attr:`Cursor.arraysize`, see :ref:`Tuning Fetch Performance <tuningfetch>`.
-- Use :meth:`Cursor.executemany()` for optimal DML execution, see :ref:`Batch Statement Execution and Bulk Loading <batchstmnt>`.
-- Only commit when necessary.  Use :attr:`Connection.autocommit` on the last statement of a transaction.
-- For connection pools, use a callback to set connection state, see :ref:`Session CallBacks for Setting Pooled Connection State <sessioncallback>`.
-- Make use of PL/SQL procedures which execute multiple SQL statements instead of executing them individually from cx_Oracle.
-- Use scalar types instead of :ref:`Oracle named object types <fetchobjects>`
-- Avoid overuse of :meth:`Connection.ping()`.
-
-Oracle's `Automatic Workload Repository (AWR)
-<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-56AEF38E-9400-427B-A818-EDEC145F7ACD>`__
-reports show 'SQL*Net roundtrips to/from client' and are useful for finding the
-overall behavior of a system.
-
-Sometimes you may wish to find the number of round-trips used for a
-specific application.  Snapshots of the ``V$SESSTAT`` view taken before
-and after doing some work can be used for this.
-
-First, find the session id of the current connection:
-
-.. code-block:: python
-
-    cursor.execute("select sys_context('userenv','sid') from dual")
-    sid, = cursor.fetchone();
-
-This can be used with ``V$SESSTAT`` to find the current number of round-trips.
-A second connection should be used to avoid affecting the count.  If your user
-does not have access to the V$ views, then use a SYSTEM connection:
-
-.. code-block:: python
-
-    def getRT(conn, sid):
-        cursor = conn.cursor()
-        cursor.execute(
-            """SELECT ss.value
-               FROM v$sesstat ss, v$statname sn
-               WHERE ss.sid = :sid
-               AND ss.statistic# = sn.statistic#
-               AND sn.name LIKE '%roundtrip%client%'""", sid = sid)
-        rt, = cursor.fetchone();
-        return rt
-
-The main part of a benchmark application can perform "work" and use ``getRT()``
-to calculate the number of round-trips the work required:
-
-.. code-block:: python
-
-    rt = getRT(systemconn, sid)
-
-    cursor = conn.cursor()
-    cursor.execute("select * from dual")
-    row = cursor.fetchone()
-
-    rt = getRT(systemconn, sid) - rt
-
-    print("Round-trips", rt)