Implemented support for max_lifetime_session in thin mode (#410).

Author: anthony-tuininga

doc/src/api_manual/pool_params.rst

@@ -136,8 +136,6 @@ PoolParams Attributes
     attribute is *0*, then the connections may remain in the pool indefinitely.
     The default value is *0* seconds.
 
-    This attribute is only supported in python-oracledb Thick mode.
-
 .. attribute:: PoolParams.max_sessions_per_shard
 
     This read-only attribute is an integer that determines the maximum number

doc/src/release_notes.rst

@@ -19,6 +19,8 @@ Thin Mode Changes
 
 #)  Added namespace package :ref:`oracledb.plugins <plugins>` for plugins that
     can be used to extend the capability of python-oracledb.
+#)  Added support for property :attr:`ConnectionPool.max_lifetime_session`
+    (`issue 410 <https://github.com/oracle/python-oracledb/issues/410>`__).
 #)  Perform TLS server matching in python-oracledb instead of the Python SSL
     library to allow alternate names to be checked
     (`issue 415 <https://github.com/oracle/python-oracledb/issues/415>`__).

doc/src/user_guide/connection_handling.rst

@@ -2079,17 +2079,16 @@ application) and are unused for longer than the pool creation attribute
 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.
+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.
 
 For pools created with :ref:`external authentication <extauth>`, with
 :ref:`homogeneous <connpooltypes>` set to False, or when using :ref:`drcp`,

src/oracledb/impl/thin/connection.pyx

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2020, 2024, Oracle and/or its affiliates.
+# Copyright (c) 2020, 2025, Oracle and/or its affiliates.
 #
 # This software is dual-licensed to you under the Universal Permissive License
 # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
@@ -61,7 +61,8 @@ cdef class BaseThinConnImpl(BaseConnImpl):
         str _service_name
         bint _drcp_enabled
         bint _drcp_establish_session
-        double _time_in_pool
+        double _time_created
+        double _time_returned
         list _temp_lobs_to_close
         uint32_t _temp_lobs_total_size
         uint32_t _call_timeout

src/oracledb/impl/thin/pool.pyx

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2020, 2024, Oracle and/or its affiliates.
+# Copyright (c) 2020, 2025, Oracle and/or its affiliates.
 #
 # This software is dual-licensed to you under the Universal Permissive License
 # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
@@ -70,6 +70,7 @@ cdef class BaseThinPoolImpl(BasePoolImpl):
         self.set_wait_timeout(params.wait_timeout)
         self.set_timeout(params.timeout)
         self._stmt_cache_size = params.stmtcachesize
+        self._max_lifetime_session = params.max_lifetime_session
         self._ping_interval = params.ping_interval
         self._ping_timeout = params.ping_timeout
         self._free_new_conn_impls = []
@@ -154,6 +155,7 @@ cdef class BaseThinPoolImpl(BasePoolImpl):
         if conn_impl._protocol._transport is not None:
             self._conn_impls_to_drop.append(conn_impl)
             self._notify_bg_task()
+        self._ensure_min_connections()
 
     cdef int _drop_conn_impls_helper(self, list conn_impls_to_drop) except -1:
         """
@@ -167,6 +169,16 @@ cdef class BaseThinPoolImpl(BasePoolImpl):
             except:
                 pass
 
+    cdef int _ensure_min_connections(self) except -1:
+        """
+        Ensure that the minimum number of connections in the pool is
+        maintained.
+        """
+        if self._open_count < self.min:
+            self._num_to_create = max(self._num_to_create,
+                                      self.min - self._open_count)
+            self._notify_bg_task()
+
     cdef PooledConnRequest _get_next_request(self):
         """
         Get the next request to process.
@@ -246,13 +258,15 @@ cdef class BaseThinPoolImpl(BasePoolImpl):
         """
         Called before the connection is connected. The connection class and
         pool attributes are updated and the TLS session is stored on the
-        transport for reuse.
+        transport for reuse. The timestamps are also retained for later use.
         """
         if params is not None:
             conn_impl._cclass = params._default_description.cclass
         else:
             conn_impl._cclass = self.connect_params._default_description.cclass
         conn_impl._pool = self
+        conn_impl._time_created = time.monotonic()
+        conn_impl._time_returned = conn_impl._time_created
 
     def _process_timeout(self):
         """
@@ -280,25 +294,35 @@ cdef class BaseThinPoolImpl(BasePoolImpl):
             bint is_open = conn_impl._protocol._transport is not None
             BaseThinDbObjectTypeCache type_cache
             PooledConnRequest request
+            double tstamp
             int cache_num
         self._busy_conn_impls.remove(conn_impl)
         if conn_impl._dbobject_type_cache_num > 0:
             cache_num = conn_impl._dbobject_type_cache_num
             type_cache = get_dbobject_type_cache(cache_num)
             type_cache._clear_cursors()
+        if not is_open:
+            self._open_count -= 1
+            self._ensure_min_connections()
         if conn_impl._is_pool_extra:
             conn_impl._is_pool_extra = False
             if is_open and self._open_count >= self.max:
                 if self._free_new_conn_impls and self._open_count == self.max:
                     self._drop_conn_impl(self._free_new_conn_impls.pop(0))
                 else:
+                    self._open_count -= 1
                     self._drop_conn_impl(conn_impl)
                     is_open = False
-        if not is_open:
-            self._open_count -= 1
-        else:
+        if is_open:
             conn_impl.warning = None
-            conn_impl._time_in_pool = time.monotonic()
+            conn_impl._time_returned = time.monotonic()
+            if self._max_lifetime_session != 0:
+                tstamp = conn_impl._time_created + self._max_lifetime_session
+                if conn_impl._time_returned > tstamp:
+                    self._open_count -= 1
+                    self._drop_conn_impl(conn_impl)
+                    is_open = False
+        if is_open:
             for request in self._requests:
                 if request.in_progress or request.wants_new \
                         or request.conn_impl is not None \
@@ -349,7 +373,7 @@ cdef class BaseThinPoolImpl(BasePoolImpl):
         current_time = time.monotonic()
         while conn_impls_to_check and self._open_count > self.min:
             conn_impl = conn_impls_to_check[0]
-            if current_time - conn_impl._time_in_pool < self._timeout:
+            if current_time - conn_impl._time_returned < self._timeout:
                 break
             conn_impls_to_check.pop(0)
             self._drop_conn_impl(conn_impl)
@@ -535,7 +559,6 @@ cdef class ThinPoolImpl(BaseThinPoolImpl):
         conn_impl = ThinConnImpl(self.dsn, self.connect_params)
         self._pre_connect(conn_impl, params)
         conn_impl.connect(self.connect_params)
-        conn_impl._time_in_pool = time.monotonic()
         return conn_impl
 
     def _notify_bg_task(self):
@@ -729,7 +752,6 @@ cdef class AsyncThinPoolImpl(BaseThinPoolImpl):
         conn_impl = AsyncThinConnImpl(self.dsn, self.connect_params)
         self._pre_connect(conn_impl, params)
         await conn_impl.connect(self.connect_params)
-        conn_impl._time_in_pool = time.monotonic()
         return conn_impl
 
     def _notify_bg_task(self):
@@ -856,7 +878,7 @@ cdef class PooledConnRequest:
         """
         cdef:
             ReadBuffer buf = conn_impl._protocol._read_buf
-            double elapsed_time
+            double elapsed_time, min_create_time
             bint has_data_ready
         if not buf._transport._is_async:
             while buf._pending_error_num == 0:
@@ -865,20 +887,27 @@ cdef class PooledConnRequest:
                     break
                 buf.check_control_packet()
         if buf._pending_error_num != 0:
-            self.pool_impl._drop_conn_impl(conn_impl)
             self.pool_impl._open_count -= 1
-        else:
-            self.conn_impl = conn_impl
-            if self.pool_impl._ping_interval == 0:
+            self.pool_impl._drop_conn_impl(conn_impl)
+            return 0
+        elif self.pool_impl._max_lifetime_session > 0:
+            min_create_time = \
+                    time.monotonic() - self.pool_impl._max_lifetime_session
+            if conn_impl._time_created < min_create_time:
+                self.pool_impl._open_count -= 1
+                self.pool_impl._drop_conn_impl(conn_impl)
+                return 0
+        self.conn_impl = conn_impl
+        if self.pool_impl._ping_interval == 0:
+            self.requires_ping = True
+        elif self.pool_impl._ping_interval > 0:
+            elapsed_time = time.monotonic() - conn_impl._time_returned
+            if elapsed_time > self.pool_impl._ping_interval:
                 self.requires_ping = True
-            elif self.pool_impl._ping_interval > 0:
-                elapsed_time = time.monotonic() - conn_impl._time_in_pool
-                if elapsed_time > self.pool_impl._ping_interval:
-                    self.requires_ping = True
-            if self.requires_ping:
-                self.pool_impl._add_request(self)
-            else:
-                self.completed = True
+        if self.requires_ping:
+            self.pool_impl._add_request(self)
+        else:
+            self.completed = True
 
     def fulfill(self):
         """
@@ -890,8 +919,8 @@ cdef class PooledConnRequest:
         cdef:
             BaseThinPoolImpl pool = self.pool_impl
             BaseThinConnImpl conn_impl
+            ssize_t ix
             object exc
-            ssize_t i
 
         # if an exception was raised in the background thread, raise it now
         if self.exception is not None:
@@ -910,13 +939,14 @@ cdef class PooledConnRequest:
         # connection is not required); in addition, ensure that the connection
         # class matches
         if not self.wants_new and pool._free_used_conn_impls:
-            for i, conn_impl in enumerate(reversed(pool._free_used_conn_impls)):
+            ix = len(pool._free_used_conn_impls) - 1
+            for conn_impl in reversed(pool._free_used_conn_impls):
                 if self.cclass is None or conn_impl._cclass == self.cclass:
-                    i = len(pool._free_used_conn_impls) - i - 1
-                    pool._free_used_conn_impls.pop(i)
+                    pool._free_used_conn_impls.pop(ix)
                     self._check_connection(conn_impl)
                     if self.completed or self.requires_ping:
                         return self.completed
+                ix -= 1
 
         # check for an available new connection (only permitted if the
         # connection class matches)

tests/ext/test_ext_1000_pool_shrink.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2024, Oracle and/or its affiliates.
+# Copyright (c) 2024, 2025, Oracle and/or its affiliates.
 #
 # This software is dual-licensed to you under the Universal Permissive License
 # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
@@ -62,9 +62,9 @@ def test_ext_1001(self):
         conn = pool.acquire()
         self.assertEqual(pool.opened, 3)
 
-    @unittest.skipIf(not test_env.get_is_thin(), "doesn't occur in thick mode")
+    @unittest.skipUnless(test_env.get_is_thin(), "doesn't occur in thick mode")
     def test_ext_1002(self):
-        "E1002 - test pool shrinks to min on pool inactivity"
+        "E1002 - test pool timeout shrinks to min on pool inactivity"
         pool = test_env.get_pool(min=3, max=10, increment=2, timeout=4)
         conns = [pool.acquire() for i in range(6)]
         self.assertEqual(pool.opened, 6)
@@ -73,9 +73,9 @@ def test_ext_1002(self):
         time.sleep(6)
         self.assertEqual(pool.opened, 3)
 
-    @unittest.skipIf(not test_env.get_is_thin(), "doesn't occur in thick mode")
+    @unittest.skipUnless(test_env.get_is_thin(), "doesn't occur in thick mode")
     def test_ext_1003(self):
-        "E1003 - test pool eliminates extra connections on inactivity"
+        "E1003 - test pool timeout eliminates extra connections on inactivity"
         pool = test_env.get_pool(min=4, max=10, increment=4, timeout=3)
         conns = [pool.acquire() for i in range(5)]
         self.assertEqual(pool.opened, 5)
@@ -85,6 +85,40 @@ def test_ext_1003(self):
         self.assertEqual(pool.opened, 5)
         del conns
 
+    @unittest.skipUnless(test_env.get_is_thin(), "doesn't occur in thick mode")
+    def test_ext_1004(self):
+        "E1004 - test pool max_lifetime_session on release"
+        pool = test_env.get_pool(
+            min=4, max=10, increment=4, max_lifetime_session=3
+        )
+        conns = [pool.acquire() for i in range(5)]
+        self.assertEqual(pool.opened, 5)
+        time.sleep(2)
+        self.assertEqual(pool.opened, 8)
+        time.sleep(2)
+        for conn in conns:
+            conn.close()
+        time.sleep(2)
+        self.assertEqual(pool.opened, 4)
+
+    @unittest.skipUnless(test_env.get_is_thin(), "doesn't occur in thick mode")
+    def test_ext_1005(self):
+        "E1005 - test pool max_lifetime_session on acquire"
+        pool = test_env.get_pool(
+            min=4, max=10, increment=4, max_lifetime_session=4
+        )
+        conns = [pool.acquire() for i in range(5)]
+        self.assertEqual(pool.opened, 5)
+        time.sleep(2)
+        self.assertEqual(pool.opened, 8)
+        for conn in conns:
+            conn.close()
+        time.sleep(4)
+        with pool.acquire():
+            pass
+        time.sleep(2)
+        self.assertEqual(pool.opened, 4)
+
 
 if __name__ == "__main__":
     test_env.run_test_cases()

tests/ext/test_ext_1900_pool_shrink_async.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2024, Oracle and/or its affiliates.
+# Copyright (c) 2024, 2025, Oracle and/or its affiliates.
 #
 # This software is dual-licensed to you under the Universal Permissive License
 # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
@@ -69,7 +69,7 @@ async def test_ext_1901(self):
         self.assertEqual(pool.opened, 3)
 
     async def test_ext_1902(self):
-        "E1902 - test pool shrinks to min on pool inactivity"
+        "E1902 - test pool timeout shrinks to min on pool inactivity"
         pool = test_env.get_pool_async(min=3, max=10, increment=2, timeout=4)
         conns = [await pool.acquire() for i in range(6)]
         self.assertEqual(pool.opened, 6)
@@ -79,7 +79,7 @@ async def test_ext_1902(self):
         self.assertEqual(pool.opened, 3)
 
     async def test_ext_1903(self):
-        "E1902 - test pool eliminates extra connections on inactivity"
+        "E1902 - test pool timeout eliminates extra connections on inactivity"
         pool = test_env.get_pool_async(min=4, max=10, increment=4, timeout=3)
         conns = [await pool.acquire() for i in range(5)]
         self.assertEqual(pool.opened, 5)
@@ -89,6 +89,38 @@ async def test_ext_1903(self):
         self.assertEqual(pool.opened, 5)
         del conns
 
+    async def test_ext_1904(self):
+        "E1904 - test pool max_lifetime_session on release"
+        pool = test_env.get_pool_async(
+            min=4, max=10, increment=4, max_lifetime_session=3
+        )
+        conns = [await pool.acquire() for i in range(5)]
+        self.assertEqual(pool.opened, 5)
+        await asyncio.sleep(2)
+        self.assertEqual(pool.opened, 8)
+        await asyncio.sleep(2)
+        for conn in conns:
+            await conn.close()
+        await asyncio.sleep(2)
+        self.assertEqual(pool.opened, 4)
+
+    async def test_ext_1905(self):
+        "E1905 - test pool max_lifetime_session on acquire"
+        pool = test_env.get_pool_async(
+            min=4, max=10, increment=4, max_lifetime_session=4
+        )
+        conns = [await pool.acquire() for i in range(5)]
+        self.assertEqual(pool.opened, 5)
+        await asyncio.sleep(2)
+        self.assertEqual(pool.opened, 8)
+        for conn in conns:
+            await conn.close()
+        await asyncio.sleep(4)
+        async with pool.acquire():
+            pass
+        await asyncio.sleep(2)
+        self.assertEqual(pool.opened, 4)
+
 
 if __name__ == "__main__":
     test_env.run_test_cases()