Documentation updates

Author: sharadraju

doc/src/api_manual/oracledb.rst

@@ -2265,6 +2265,20 @@ Oracledb Methods
             This optional property overrides the :attr:`oracledb.machine` property.
 
             .. versionadded:: 6.7
+        * - ``maxLifetimeSession``
+          - Number
+          - Both
+          - .. _createpoolpoolattrsmaxlifetimesession:
+
+            The number of seconds that a pooled connection can exist in a pool after first being created. A value of *0* means there is no limit defined for the connection in a pool and no connections will be terminated. Connections become candidates for termination when they are acquired or released back to the pool, and have existed for longer than ``maxLifetimeSession`` seconds. Connections that are in active use will not be closed.
+
+            In node-oracledb Thick mode, Oracle Client libraries 12.1 or later must be used. Note that when using node-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.
+
+            The default value is *0*.
+
+            See :ref:`conpoolsizing`.
+
+            .. versionadded:: 6.9
         * - ``networkCompression``
           - Boolean
           - Thin
@@ -2791,11 +2805,11 @@ Oracledb Methods
         * - ``authType``
           - The authentication type. The value should be the string *configFileBasedAuthentication*, *simpleAuthentication*, or *instancePrincipal*.
 
-            In Configuration File Based Authentication, the location of the configuration file containing the necessary information must be provided.
+            With Configuration File Based Authentication, the location of the configuration file containing the necessary information must be provided.
 
-            In Simple Authentication, the configuration parameters can be provided at runtime.
+            With Simple Authentication, the configuration parameters can be provided at runtime.
 
-            In Instance Principal Authentication, an instance can be authorized to make API calls on OCI services without credentials. The authentication method will only work on compute instances where internal network endpoints are reachable.
+            With Instance Principal Authentication, OCI compute instances can be authorized to access services on Oracle Cloud such as Oracle Autonomous Database. Node.js applications running on such a compute instance are automatically authenticated, eliminating the need to provide database user credentials. This authentication method will only work on compute instances where internal network endpoints are reachable. For more information on OCI compute instances, see `OCI Compute Instances <https://docs.oracle.com/en-us/iaas/compute-cloud-at-customer/topics/compute/compute-instances.htm>`__, `Creating a Compute Instance <https://docs.oracle.com/en-us/iaas/Content/Compute/Tasks/launchinginstance.htm>`__, and `Calling Services from a Compute Instance <https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm>`__.
 
             See `OCI SDK Authentication Methods <https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm>`__ for more information.
           - Required

doc/src/api_manual/pool.rst

@@ -113,6 +113,29 @@ values.
     See :ref:`homogeneous <createpoolpoolattrshomogeneous>` parameter of
     :meth:`oracledb.createPool()`.
 
+.. attribute:: pool.maxLifetimeSession
+
+    This read-only property is the number of seconds that a pooled connection
+    can exist in a pool after first being created.
+
+    A value of *0* means there is no limit defined for the connection in a
+    pool and no connections will be terminated. Connections become candidates
+    for termination when they are acquired or released back to the pool, and
+    have existed for longer than ``maxLifetimeSession`` seconds. Connections
+    that are in active use will not be closed.
+
+    In node-oracledb Thick mode, Oracle Client libraries 12.1 or later must
+    be used. Note that when using node-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.
+
+    The default value is *0*.
+
+    See :ref:`conpoolsizing`.
+
+    .. versionadded:: 6.9
+
 .. attribute:: pool.poolAlias
 
     This read-only property is a number which specifies the alias of this
@@ -603,12 +626,17 @@ Pool Methods
             - :ref:`queueRequests <createpoolpoolattrsqueuerequests>`
             - :ref:`queueTimeout <createpoolpoolattrsqueuetimeout>`
             - :ref:`sodaMetaDataCache <createpoolpoolattrssodamdcache>` in only Thick mode
+            - :ref:`maxLifetimeSession <createpoolpoolattrsmaxlifetimesession>`
             - :ref:`stmtCacheSize <createpoolpoolattrsstmtcachesize>`
 
             A ``resetStatistics`` property can also be set to *true*. This zeros the current pool statistics, with the exception of ``queueMax`` which is set to the current queue length. Statistics are also reset when statistics recording is turned on with the ``enableStatistics`` property.
 
             Changing ``queueMax``, ``queueTimeout``, or resetting statistics does not affect any currently queued connection requests. If connections are not made available to currently queued requests, those queued requests will timeout based on the ``queueTimeout`` value in effect when they were originally added to the connection pool queue. If pool statistics are enabled, then these failed requests will be counted in :ref:`requestTimeouts <poolstats>` and included in the queue time statistics.
 
+            .. versionchanged:: 6.9
+
+                The ``maxLifetimeSession`` property was added.
+
     **Callback**:
 
     If you are using the callback programming style::

doc/src/user_guide/connection_handling.rst

@@ -1472,6 +1472,32 @@ been created, so there is an initial time cost. However it can allow subsequent
 connection requests to be immediately satisfied. In this growth scenario, a
 ``poolIncrement`` of 0 is treated as 1.
 
+The optional pool creation property
+:ref:`maxLifetimeSession <createpoolpoolattrsmaxlifetimesession>` also allows
+pools to shrink. This property bounds the total length of time that a
+connection can exist in a pool after first being created. It is mostly used
+for defensive programming to mitigate against unforeseeable problems that may
+occur with connections. If a connection was created ``maxLifetimeSession`` or
+longer seconds ago, then it will be a candidate for being closed.
+
+In node-oracledb Thick mode, Oracle Client libraries 12.1, or later, are
+needed to use
+:ref:`maxLifetimeSession <createpoolpoolattrsmaxlifetimesession>`. Note that
+when using node-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.
+
+If both :ref:`poolTimeout <createpoolpoolattrspooltimeout>` and
+:ref:`maxLifetimeSession <createpoolpoolattrsmaxlifetimesession>` properties
+are set on a pooled connection, the connection will be terminated if either
+the idle timeout happens or the ``maxLifeTimeSession`` setting is exceeded.
+In this case, if connections are idle for more than
+:ref:`poolTimeout <createpoolpoolattrspooltimeout>`, they are dropped only
+when doing so will ensure that :attr:`pool.connectionsOpen` is more than or
+equal to the :attr:`~pool.poolMin` setting. If the connection lifetime
+exceeds :ref:`maxLifetimeSession <createpoolpoolattrsmaxlifetimesession>`
+seconds, it is dropped and a new connection is created in the pool.
+
 Connection pool health can be impacted by firewalls, `resource manager <https:
 //www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-2BEF5482-CF97-4A85-BD90
 -9195E41E74EF>`__, or user profile `IDLE_TIME <https://www.oracle.com/pls/
@@ -1888,6 +1914,7 @@ function record the following:
     :header-rows: 1
     :class: wy-table-responsive
     :align: center
+    :widths: 10 10 30
     :summary: The first column displays the pool statistics attribute. The second column displays the logStatistics() label. The third column displays the description of the attribute.
 
     * - :ref:`Pool Statistics Class <poolstatisticsclass>` Attribute
@@ -1986,6 +2013,9 @@ function record the following:
     * - ``poolTimeout``
       - :attr:`poolTimeout (seconds) <pool.poolTimeout>`
       - The time (in seconds) after which the pool terminates idle connections (unused in the pool).
+    * - ``maxLifetimeSession``
+      - :attr:`maxLifetimeSession (seconds) <pool.maxLifetimeSession>`
+      - The time (in seconds) that a pooled connection can exist in a pool after first being created.
     * - ``queueMax``
       - :attr:`~pool.queueMax`
       - The maximum number of pending :meth:`pool.getConnection()` calls that can be queued.