Doc updates.

Author: anthony-tuininga

doc/src/api_manual/async_connection_pool.rst

@@ -119,14 +119,14 @@ AsyncConnectionPool Attributes
 
 .. attribute:: AsyncConnectionPool.max_lifetime_session
 
-    This read-write attribute returns the maximum length of time (in seconds)
-    that a pooled connection may exist. Connections that are in use will not be
-    closed. They become candidates for termination only when they are released
-    back to the pool and have existed for longer than max_lifetime_session
-    seconds. Note that termination only occurs when the pool is accessed. A
-    value of *0* means that there is no maximum length of time that a pooled
-    connection may exist. This attribute is only available in Oracle Database
-    12.1 or later.
+    This read-write attribute is the maximum length of time (in seconds) that a
+    pooled connection may exist since first being created. A value of *0* means
+    there is no limit. Connections become candidates for termination when they
+    are acquired or released back to the pool, and have existed for longer than
+    ``max_lifetime_session`` seconds. Connections that are in active use will
+    not be closed. In python-oracledb Thick mode, Oracle Client libraries 12.1
+    or later must be used and, prior to Oracle Client 21, cleanup only occurs
+    when the pool is accessed.
 
 .. attribute:: AsyncConnectionPool.max_sessions_per_shard
 
@@ -189,10 +189,12 @@ AsyncConnectionPool Attributes
 
 .. attribute:: AsyncConnectionPool.timeout
 
-    This read-write attribute specifies the time (in seconds) after which idle
-    connections will be terminated in order to maintain an optimum number of
-    open connections. A value of *0* means that no idle connections are
-    terminated.
+    This read-only attribute is an integer that specifies the length of time
+    (in seconds) that a 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. The
+    default value is *0* seconds. A value of *0* means that there is no maximum
+    time.
 
 .. attribute:: AsyncConnectionPool.username
 

doc/src/api_manual/connection_pool.rst

@@ -216,14 +216,14 @@ ConnectionPool Attributes
 
 .. attribute:: ConnectionPool.max_lifetime_session
 
-    This read-write attribute returns the maximum length of time (in seconds)
-    that a pooled connection may exist. Connections that are in use will not be
-    closed. They become candidates for termination only when they are released
-    back to the pool and have existed for longer than max_lifetime_session
-    seconds. Note that termination only occurs when the pool is accessed. A
-    value of *0* means that there is no maximum length of time that a pooled
-    connection may exist. This attribute is only available in Oracle Database
-    12.1 or later.
+    This read-write attribute is the maximum length of time (in seconds) that a
+    pooled connection may exist since first being created. A value of *0* means
+    there is no limit. Connections become candidates for termination when they
+    are acquired or released back to the pool, and have existed for longer than
+    ``max_lifetime_session`` seconds. Connections that are in active use will
+    not be closed. In python-oracledb Thick mode, Oracle Client libraries 12.1
+    or later must be used and, prior to Oracle Client 21, cleanup only occurs
+    when the pool is accessed.
 
 .. attribute:: ConnectionPool.max_sessions_per_shard
 

doc/src/api_manual/module.rst

@@ -1229,21 +1229,24 @@ 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.  This
+    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*
-    seconds.
+    it to shrink to the specified minimum size. The default value is *0*
+    seconds. A value of *0* means there is no limit.
 
     The ``wait_timeout`` parameter is the length of time (in milliseconds) that
     a caller should wait when acquiring a connection from the pool with
     ``getmode`` set to :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default
     value is *0* milliseconds.
 
     The ``max_lifetime_session`` parameter is the length of time (in seconds)
-    that connections can remain in the pool. If the value of this parameter is
-    0, then the connections may remain in the pool indefinitely. The default
-    value is *0* seconds.
+    that a pooled connection may exist since first being created. The default
+    value is *0*. A value of *0* means that there is no limit. Connections
+    become candidates for termination when they are acquired or released back
+    to the pool and have existed for longer than ``max_lifetime_session``
+    seconds. In python-oracledb Thick mode, Oracle Client libraries 12.1 or
+    later must be used and, prior to Oracle Client 21, cleanup only occurs when
+    the pool is accessed.
 
     The ``session_callback`` parameter is a callable that is invoked when a
     connection is returned from the pool for the first time, or when the
@@ -1687,21 +1690,24 @@ 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.  This
+    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*
-    seconds.
+    it to shrink to the specified minimum size. The default value is *0*
+    seconds. A value of *0* means there is no limit.
 
     The ``wait_timeout`` parameter is the length of time (in milliseconds) that
     a caller should wait when acquiring a connection from the pool with
     ``getmode`` set to :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default
     value is *0* milliseconds.
 
     The ``max_lifetime_session`` parameter is the length of time (in seconds)
-    that connections can remain in the pool. If the value of this parameter is
-    0, then the connections may remain in the pool indefinitely. The default
-    value is *0* seconds.
+    that a pooled connection may exist since first being created. The default
+    value is *0*. A value of *0* means that there is no limit. Connections
+    become candidates for termination when they are acquired or released back
+    to the pool and have existed for longer than ``max_lifetime_session``
+    seconds. In python-oracledb Thick mode, Oracle Client libraries 12.1 or
+    later must be used and, prior to Oracle Client 21, cleanup only occurs when
+    the pool is accessed.
 
     The ``session_callback`` parameter is a callable that is invoked when a
     connection is returned from the pool for the first time, or when the
@@ -2202,21 +2208,24 @@ 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.  This
+    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*
-    seconds.
+    it to shrink to the specified minimum size. The default value is *0*
+    seconds. A value of *0* means there is no limit.
 
     The ``wait_timeout`` parameter is the length of time (in milliseconds) that
     a caller should wait when acquiring a connection from the pool with
     ``getmode`` set to :data:`oracledb.POOL_GETMODE_TIMEDWAIT`. The default
     value is *0* milliseconds.
 
     The ``max_lifetime_session`` parameter is the length of time (in seconds)
-    that connections can remain in the pool. If the value of this parameter is
-    0, then the connections may remain in the pool indefinitely. The default
-    value is *0* seconds.
+    that a pooled connection may exist since first being created. The default
+    value is *0*. A value of *0* means that there is no limit. Connections
+    become candidates for termination when they are acquired or released back
+    to the pool and have existed for longer than ``max_lifetime_session``
+    seconds. In python-oracledb Thick mode, Oracle Client libraries 12.1 or
+    later must be used and, prior to Oracle Client 21, cleanup only occurs when
+    the pool is accessed.
 
     The ``session_callback`` parameter is a callable that is invoked when a
     connection is returned from the pool for the first time, or when the

doc/src/api_manual/pool_params.rst

@@ -131,10 +131,14 @@ PoolParams Attributes
 
 .. attribute:: PoolParams.max_lifetime_session
 
-    This read-only attribute is an integer that determines the length of time
-    (in seconds) that connections can remain in the pool. If the value of this
-    attribute is *0*, then the connections may remain in the pool indefinitely.
-    The default value is *0* seconds.
+    This read-only attribute is the maximum length of time (in seconds) that a
+    pooled connection may exist since first being created. A value of *0* means
+    there is no limit. Connections become candidates for termination when they
+    are acquired or released back to the pool, and have existed for longer than
+    ``max_lifetime_session`` seconds. Connections that are in active use will
+    not be closed. In python-oracledb Thick mode, Oracle Client libraries 12.1
+    or later must be used and, prior to Oracle Client 21, cleanup only occurs
+    when the pool is accessed.
 
 .. attribute:: PoolParams.max_sessions_per_shard
 
@@ -189,10 +193,12 @@ PoolParams Attributes
 
     This read-only attribute is an integer that specifies the length of time
     (in seconds) that a connection may remain idle in the pool before it is
-    terminated. If the value of this attribute is *0*, then the connections
-    are never terminated. The default value is *0* seconds.
+    terminated. This applies only when the pool has more than ``min``
+    connections open, allowing it to shrink to the specified minimum size. The
+    default value is *0* seconds. A value of *0* means that there is no maximum
+    time.
 
-    This attribute is only supported in python-oracledb Thick mode.
+    This attribute is supported in both python-oracledb Thin and Thick modes.
 
 .. attribute:: PoolParams.wait_timeout
 

doc/src/user_guide/connection_handling.rst

@@ -2069,26 +2069,29 @@ regardless of how big ``increment`` is.  The pool will then continue to
 re-establish connections in a background thread.
 
 A connection pool can shrink back to its minimum size ``min`` 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.  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 check occurs every
-``timeout`` interval and hence in the worst case it may take twice the
-``timeout`` time to close the idle connections.  The default ``timeout`` is 0
-seconds signifying an infinite time and meaning idle connections will never be
-closed.
+opened by the pool are not used by the application. This frees up database
+resources while allowing pools to retain open connections for active users. If
+there are more than ``min`` connections open, and connections are idle in the
+pool (i.e. not currently acquired by the application) and unused for longer
+than the pool creation attribute ``timeout`` value, then they will be closed.
+The check occurs every ``timeout`` interval and hence in the worst case it may
+take twice the ``timeout`` time to close the idle connections. 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.
+shrink. This parameter bounds the total length of time that a connection can
+exist starting from the time that it was created in the pool. It is mostly used
+for defensive programming to mitigate against unforeseeable problems that may
+occur with connections. If a connection was created ``max_lifetime_session`` or
+longer seconds ago, then it will be a candidate for being closed. 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 maximum 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. In Thick mode, Oracle Client libraries 12.1, or
+later, are needed to use ``max_lifetime_session``.
 
 For pools created with :ref:`external authentication <extauth>`, with
 :ref:`homogeneous <connpooltypes>` set to False, or when using :ref:`drcp` (in