Improvements to documentation and samples.

Author: anthony-tuininga

doc/src/api_manual/module.rst

@@ -590,9 +590,10 @@ Oracledb Methods
     users). The default value is True.
 
     The ``timeout`` parameter is the length of time (in seconds) that a
-    connection may remain idle in the pool before it is terminated. If the
-    value of this parameter is 0, then the connections are never terminated.
-    The default value is 0.
+    connection may remain idle in the pool before it is terminated.  This
+    applies only when the pool has more than ``min`` connections open, allowing
+    it to shrink to the specified minimum size.  If the value of this parameter
+    is 0, then the connections are never terminated.  The default value is 0.
 
     The ``wait_timeout`` parameter is the length of time (in milliseconds) that
     a caller should wait when acquiring a connection from the pool with
@@ -970,9 +971,10 @@ Oracledb Methods
     The default value is True.
 
     The ``timeout`` parameter is the length of time (in seconds) that a
-    connection may remain idle in the pool before it is terminated. If the
-    value of this parameter is 0, then the connections are never terminated.
-    The default value is 0.
+    connection may remain idle in the pool before it is terminated.  This
+    applies only when the pool has more than ``min`` connections open, allowing
+    it to shrink to the specified minimim size.  If the value of this parameter
+    is 0, then the connections are never terminated.  The default value is 0.
 
     The ``wait_timeout`` parameter is the length of time (in milliseconds) that
     a caller should wait when acquiring a connection from the pool with

doc/src/release_notes.rst

@@ -16,16 +16,12 @@ Thin Mode Changes
 #)  Added internal support for prefetching the LOB size and chunk size, thereby
     eliminating a :ref:`round-trip<roundtrips>` when calling
     :meth:`LOB.size()` and :meth:`LOB.getchunksize()`.
-#)  Added implementation for :data:`ConnectionPool.timeout`.
-#)  Connections returned to the pool are now the first to be returned when
-    calling :meth:`ConnectionPool.acquire()` afterwards. This helps reduce the
-    number of times the session callback must be invoked, if one is used.
+#)  Added implementation for :data:`ConnectionPool.timeout` to allow pools to
+    shrink to ``min`` connections.
 #)  Added check to prevent adding too many elements to bounded database
     collections.
 #)  Removed internally set fixed size for database collections. Collections of
     any size supported by the database can now be created.
-#)  Removed packet for negotiating network services which are not supported in
-    thin mode.
 #)  Fixed bug when calling :meth:`Cursor.executemany()` with PL/SQL when the
     size of the bound data increases on subsequent calls
     (`issue 132 <https://github.com/oracle/python-oracledb/issues/132>`__).
@@ -37,6 +33,14 @@ Thin Mode Changes
 #)  Fixed bug with SQL containing multibyte characters with certain database
     character sets
     (`issue 133 <https://github.com/oracle/python-oracledb/issues/133>`__).
+#)  Implementation changes:
+
+    - Made the pool implementation LIFO to improve locality, reduce the number
+      of times any session callback must be invoked, and allow connections to
+      be timed out.
+    - Removed packet for negotiating network services which are not supported
+      in thin mode.
+
 
 Thick Mode Changes
 ++++++++++++++++++

doc/src/user_guide/batch_statement.rst

@@ -306,3 +306,42 @@ be beneficial.
 
 See `load_csv.py <https://github.com/oracle/python-oracledb/tree/main/
 samples/load_csv.py>`__ for a runnable example.
+
+
+Copying Data between Databases
+==============================
+
+The :meth:`Cursor.executemany()` function is useful for efficiently copying
+data from one database to another:
+
+.. code-block:: python
+
+    # Connect to both databases
+    source_connection = oracledb.connect(user=un1, password=pw1, dsn=cs1)
+    target_connection = oracledb.connect(user=un2, password=pw2, dsn=cs2)
+
+    # Setup cursors
+    source_cursor = source_connection.cursor()
+    source_cursor.arraysize = 1000              # tune this for query performance
+
+    target_cursor = target_connection.cursor()
+    target_cursor.setinputsizes(None, 25)       # set according to column types
+
+    # Perform bulk fetch and insertion
+    source_cursor.execute("select c1, c2 from MySrcTable")
+    while True:
+        rows = source_cursor.fetchmany()
+        if not rows:
+            break
+        target_cursor.executemany("insert into MyDestTable values (:1, :2)", rows)
+
+    target_connection.commit()
+
+Tune the :attr:`~Cursor.arraysize` value according to notes in
+:ref:`tuningfetch`.  Use ``setinputsizes()`` according to `Predefining Memory
+Areas`_.
+
+Note that it may be preferable to create a `database link
+<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-D966642A-B19E-449D-9968-1121AF06D793>`__
+between the databases and use an INSERT INTO SELECT statement so that data is
+not copied to, and back from, the Python process.

doc/src/user_guide/connection_handling.rst

@@ -666,22 +666,23 @@ re-establish connections in a background thread.
 
 A connection pool can shrink back to its minimum size when connections opened
 by the pool are not used by the application.  This frees up database resources
-while allowing pools to retain connections for active users.  Note this is
-currently applicable to Thick mode only.  If connections are idle in the pool
-(i.e. not currently acquired by the application) and are unused for longer than
-the pool creation attribute ``timeout`` value , then they will be closed.  The
-default ``timeout`` is 0 seconds signifying an infinite time and meaning idle
-connections will never be closed.  The pool creation parameter
-``max_lifetime_session`` also allows pools to shrink.  This parameter bounds
-the total length of time that a connection can exist starting from the time the
-pool created it.  If a connection was created ``max_lifetime_session`` or
-longer seconds ago, then it will be closed when it is idle in the pool.  In the
-case when ``timeout`` and ``max_lifetime_session`` are both set, the connection
-will be terminated if either the idle timeout happens or the max lifetime
-setting is exceeded.  Note that when using python-oracledb in Thick mode with
-Oracle Client libraries prior to 21c, pool shrinkage is only initiated when the
-pool is accessed so pools in fully dormant applications will not shrink until
-the application is next used.
+while allowing pools to retain connections for active users.  If connections
+are idle in the pool (i.e. not currently acquired by the application) and are
+unused for longer than the pool creation attribute ``timeout`` value, then they
+will be closed.  The default ``timeout`` is 0 seconds signifying an infinite
+time and meaning idle connections will never be closed.  In python-oracledb
+Thick mode, the pool creation parameter ``max_lifetime_session`` also allows
+pools to shrink.  This parameter bounds the total length of time that a
+connection can exist starting from the time the pool created it.  If a
+connection was created ``max_lifetime_session`` or longer seconds ago, then it
+will be closed when it is idle in the pool.  In the case when ``timeout`` and
+``max_lifetime_session`` are both set, the connection will be terminated if
+either the idle timeout happens or the max lifetime setting is exceeded.  Note
+that when using python-oracledb in Thick mode with Oracle Client libraries
+prior to 21c, pool shrinkage is only initiated when the pool is accessed so
+pools in fully dormant applications will not shrink until the application is
+next used.  When using python-oracledb in Thin mode, connection timeout checks
+only occur when :meth:`~ConnectionPool.acquire()` is called.
 
 For pools created with :ref:`external authentication <extauth>`, with
 :ref:`homogeneous <connpooltypes>` set to False, or when using :ref:`drcp`,
@@ -802,7 +803,7 @@ can be set directly, for example:
 
 .. _sessioncallback:
 
-Session CallBacks for Setting Pooled Connection State
+Session Callbacks for Setting Pooled Connection State
 -----------------------------------------------------
 
 Applications can set "session" state in each connection.  Examples of session