Added support for implicit pooling with DRCP.

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -13,6 +13,7 @@ oracledb 2.1.0 (TBD)
 Thin Mode Changes
 +++++++++++++++++
 
+#)  Added support for Oracle Database 23c feature: implicit pooling with DRCP.
 #)  Added support for Oracle Database 23c feature that can improve the
     performance of connection creation by reducing the number of round trips
     required for all connections created.

src/oracledb/base_impl.pxd

@@ -346,6 +346,7 @@ cdef class Description(ConnectParamsNode):
         public str sid
         public str cclass
         public str connection_id_prefix
+        public str pool_boundary
         public uint32_t purity
         public bint ssl_server_dn_match
         public str ssl_server_cert_dn

src/oracledb/connect_params.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2021, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2021, 2024, 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
@@ -94,6 +94,7 @@ def __init__(
         connection_id_prefix: str = None,
         ssl_context: Any = None,
         sdu: int = 8192,
+        pool_boundary: str = None,
         handle: int = 0,
     ):
         """
@@ -255,6 +256,11 @@ def __init__(
           actually be used is negotiated down to the lower of this value and
           the database network SDU configuration value (default: 8192)
 
+        - pool_boundary: one of the values "statement" or "transaction"
+          indicating when pooled DRCP connections can be returned to the pool.
+          This requires the use of DRCP with Oracle Database 23.4 or higher
+          (default: None)
+
         - handle: an integer representing a pointer to a valid service context
           handle. This value is only used in thick mode. It should be used with
           extreme caution (default: 0)
@@ -299,7 +305,8 @@ def __repr__(self):
             + f"debug_jdwp={self.debug_jdwp!r}, "
             + f"connection_id_prefix={self.connection_id_prefix!r}, "
             + f"ssl_context={self.ssl_context!r}, "
-            + f"sdu={self.sdu!r}"
+            + f"sdu={self.sdu!r}, "
+            + f"pool_boundary={self.pool_boundary!r}"
             + ")"
         )
 
@@ -461,6 +468,16 @@ def mode(self) -> int:
         """
         return self._impl.mode
 
+    @property
+    @_description_attr
+    def pool_boundary(self) -> Union[list, str]:
+        """
+        One of the values "statement" or "transaction" indicating when pooled
+        DRCP connections can be returned to the pool. This requires the use of
+        DRCP with Oracle Database 23.4 or higher.
+        """
+        return self._impl.pool_boundary
+
     @property
     @_address_attr
     def port(self) -> Union[list, int]:
@@ -719,6 +736,7 @@ def set(
         connection_id_prefix: str = None,
         ssl_context: Any = None,
         sdu: int = None,
+        pool_boundary: str = None,
         handle: int = None,
     ):
         """
@@ -871,6 +889,10 @@ def set(
           actually be used is negotiated down to the lower of this value and
           the database network SDU configuration value
 
+        - pool_boundary: one of the values "statement" or "transaction"
+          indicating when pooled DRCP connections can be returned to the pool.
+          This requires the use of DRCP with Oracle Database 23.4 or higher
+
         - handle: an integer representing a pointer to a valid service context
           handle. This value is only used in thick mode. It should be used with
           extreme caution

src/oracledb/connection.py

@@ -1197,6 +1197,7 @@ def connect(
     connection_id_prefix: str = None,
     ssl_context: Any = None,
     sdu: int = 8192,
+    pool_boundary: str = None,
     handle: int = 0,
 ) -> Connection:
     """
@@ -1379,6 +1380,10 @@ def connect(
       actually be used is negotiated down to the lower of this value and the
       database network SDU configuration value (default: 8192)
 
+    - pool_boundary: one of the values "statement" or "transaction" indicating
+      when pooled DRCP connections can be returned to the pool. This requires
+      the use of DRCP with Oracle Database 23.4 or higher (default: None)
+
     - handle: an integer representing a pointer to a valid service context
       handle. This value is only used in thick mode. It should be used with
       extreme caution (default: 0)
@@ -1762,6 +1767,7 @@ def connect_async(
     connection_id_prefix: str = None,
     ssl_context: Any = None,
     sdu: int = 8192,
+    pool_boundary: str = None,
     handle: int = 0,
 ) -> AsyncConnection:
     """
@@ -1944,6 +1950,10 @@ def connect_async(
       actually be used is negotiated down to the lower of this value and the
       database network SDU configuration value (default: 8192)
 
+    - pool_boundary: one of the values "statement" or "transaction" indicating
+      when pooled DRCP connections can be returned to the pool. This requires
+      the use of DRCP with Oracle Database 23.4 or higher (default: None)
+
     - handle: an integer representing a pointer to a valid service context
       handle. This value is only used in thick mode. It should be used with
       extreme caution (default: 0)

src/oracledb/errors.py

@@ -239,6 +239,7 @@ def _raise_err(
 ERR_DBOBJECT_ATTR_MAX_SIZE_VIOLATED = 2043
 ERR_DBOBJECT_ELEMENT_MAX_SIZE_VIOLATED = 2044
 ERR_INVALID_ARRAYSIZE = 2045
+ERR_CURSOR_HAS_BEEN_CLOSED = 2046
 
 # error numbers that result in NotSupportedError
 ERR_TIME_NOT_SUPPORTED = 3000
@@ -293,6 +294,7 @@ def _raise_err(
 ERR_NO_CONFIG_DIR = 4027
 ERR_INVALID_SERVER_TYPE = 4028
 ERR_TOO_MANY_BATCH_ERRORS = 4029
+ERR_INVALID_POOL_BOUNDARY = 4030
 
 # error numbers that result in InternalError
 ERR_MESSAGE_TYPE_UNKNOWN = 5000
@@ -448,6 +450,7 @@ def _raise_err(
     ),
     ERR_CONTENT_INVALID_AFTER_NUMBER: "invalid number (content after number)",
     ERR_CURSOR_NOT_OPEN: "cursor is not open",
+    ERR_CURSOR_HAS_BEEN_CLOSED: "cursor has been closed by the database",
     ERR_DBOBJECT_ATTR_MAX_SIZE_VIOLATED: (
         "attribute {attr_name} of type {type_name} exceeds its maximum size "
         "(actual: {actual_size}, maximum: {max_size})"
@@ -520,6 +523,7 @@ def _raise_err(
     ERR_INVALID_NUMBER: "invalid number",
     ERR_INVALID_OBJECT_TYPE_NAME: 'invalid object type name: "{name}"',
     ERR_INVALID_OCI_ATTR_TYPE: "invalid OCI attribute type {attr_type}",
+    ERR_INVALID_POOL_BOUNDARY: "invalid DRCP pool boundary {boundary}",
     ERR_INVALID_POOL_CLASS: "invalid connection pool class",
     ERR_INVALID_POOL_PARAMS: "invalid pool params",
     ERR_INVALID_POOL_PURITY: "invalid DRCP purity {purity}",

src/oracledb/impl/base/connect_params.pyx

@@ -871,6 +871,8 @@ cdef class Description(ConnectParamsNode):
             temp_parts.append(f"(SID={self.sid})")
         if self.server_type is not None:
             temp_parts.append(f"(SERVER={self.server_type})")
+        if self.pool_boundary is not None:
+            temp_parts.append(f"(POOL_BOUNDARY={self.pool_boundary})")
         if cid is not None:
             temp_parts.append(f"(CID={cid})")
         else:
@@ -935,6 +937,7 @@ cdef class Description(ConnectParamsNode):
         _set_server_type_param(args, "server_type", self)
         _set_str_param(args, "cclass", self)
         _set_purity_param(args, "purity", &self.purity)
+        _set_pool_boundary_param(args, "pool_boundary", self)
         _set_str_param(args, "connection_id_prefix", self)
 
     def set_from_description_args(self, dict args):

src/oracledb/impl/base/utils.pyx

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2022, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2022, 2024, 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
@@ -91,6 +91,23 @@ cdef int _set_uint_param(dict args, str name, uint32_t* out_val) except -1:
         out_val[0] = int(in_val)
 
 
+cdef int _set_pool_boundary_param(dict args, str name,
+                                  object target) except -1:
+    """
+    Sets a pool boundary parameter to the value specified. This must be one of
+    the values "statement" or "transaction". If it is not one of these values
+    an error is raised. If a value is specified and meets the criteria it is
+    set directly on the target (since strings are treated as Python objects).
+    """
+    in_val = args.get(name)
+    if in_val is not None:
+        in_val = in_val.lower()
+        if in_val not in ("statement", "transaction"):
+            errors._raise_err(errors.ERR_INVALID_POOL_BOUNDARY,
+                              boundary=in_val)
+        setattr(target, name, in_val)
+
+
 cdef int _set_protocol_param(dict args, str name, object target) except -1:
     """
     Sets a protocol parameter to the value provided in the dictionary. This

src/oracledb/impl/thin/capabilities.pyx

@@ -84,6 +84,8 @@ cdef class Capabilities:
                 TNS_CCAP_O5LOGON | TNS_CCAP_O5LOGON_NP | \
                 TNS_CCAP_O7LOGON | TNS_CCAP_O8LOGON_LONG_IDENTIFIER | \
                 TNS_CCAP_O9LOGON_LONG_PASSWORD
+        self.compile_caps[TNS_CCAP_FEATURE_BACKPORT] = \
+                TNS_CCAP_CTB_IMPLICIT_POOL
         self.compile_caps[TNS_CCAP_FIELD_VERSION] = self.ttc_field_version
         self.compile_caps[TNS_CCAP_SERVER_DEFINE_CONV] = 1
         self.compile_caps[TNS_CCAP_TTC1] = \

src/oracledb/impl/thin/constants.pxi

@@ -631,6 +631,7 @@ cdef enum:
 cdef enum:
     TNS_CCAP_SQL_VERSION = 0
     TNS_CCAP_LOGON_TYPES = 4
+    TNS_CCAP_FEATURE_BACKPORT = 5
     TNS_CCAP_FIELD_VERSION = 7
     TNS_CCAP_SERVER_DEFINE_CONV = 8
     TNS_CCAP_TTC1 = 15
@@ -676,6 +677,7 @@ cdef enum:
     TNS_CCAP_O7LOGON = 32
     TNS_CCAP_O8LOGON_LONG_IDENTIFIER = 64
     TNS_CCAP_O9LOGON_LONG_PASSWORD = 0x80
+    TNS_CCAP_CTB_IMPLICIT_POOL = 0x08
     TNS_CCAP_END_OF_CALL_STATUS = 0x01
     TNS_CCAP_IND_RCD = 0x08
     TNS_CCAP_FAST_BVEC = 0x20
@@ -724,6 +726,11 @@ cdef enum:
     TNS_UDS_FLAGS_IS_JSON = 0x00000100
     TNS_UDS_FLAGS_IS_OSON = 0x00000800
 
+# end of call status flags
+cdef enum:
+    TNS_EOCS_FLAGS_TXN_IN_PROGRESS = 0x00000002
+    TNS_EOCS_FLAGS_SESS_RELEASE = 0x00008000
+
 # accept flags
 cdef enum:
     TNS_ACCEPT_FLAG_FAST_AUTH = 0x10000000
@@ -735,7 +742,6 @@ cdef enum:
     TNS_DURATION_SESSION = 10
     TNS_MAX_LONG_LENGTH = 0x7fffffff
     TNS_MAX_CURSORS_TO_CLOSE = 500
-    TNS_TXN_IN_PROGRESS = 0x00000002
     TNS_MAX_CONNECT_DATA = 230
     TNS_MAX_UROWID_LENGTH = 5267
     TNS_SERVER_CONVERTS_CHARS = 0x01

src/oracledb/impl/thin/cursor.pyx

@@ -204,15 +204,18 @@ cdef class ThinCursorImpl(BaseThinCursorImpl):
         # if a PL/SQL statement requires a full execute, perform only a single
         # iteration in order to allow the determination of input/output binds
         # to be completed; after that, an execution of the remaining iterations
-        # can be performed
+        # can be performed (but only if the cursor remains intact)
         if stmt._is_plsql and (stmt._cursor_id == 0 or stmt._binds_changed):
             message.num_execs = 1
+            while num_execs > 0:
+                num_execs -= 1
+                protocol._process_single_message(message)
+                message.offset += 1
+                if stmt._cursor_id != 0:
+                    break
+        if num_execs > 0:
+            message.num_execs = num_execs
             protocol._process_single_message(message)
-            if num_execs == 1:
-                return
-            message.offset = 1
-            message.num_execs = num_execs - 1
-        protocol._process_single_message(message)
         self.warning = message.warning
 
     def parse(self, cursor):
@@ -289,15 +292,18 @@ cdef class AsyncThinCursorImpl(BaseThinCursorImpl):
         # if a PL/SQL statement requires a full execute, perform only a single
         # iteration in order to allow the determination of input/output binds
         # to be completed; after that, an execution of the remaining iterations
-        # can be performed
+        # can be performed (but only if the cursor remains intact)
         if stmt._is_plsql and (stmt._cursor_id == 0 or stmt._binds_changed):
             message.num_execs = 1
+            while num_execs > 0:
+                num_execs -= 1
+                await protocol._process_single_message(message)
+                message.offset += 1
+                if stmt._cursor_id != 0:
+                    break
+        if num_execs > 0:
+            message.num_execs = num_execs
             await protocol._process_single_message(message)
-            if num_execs == 1:
-                return
-            message.offset = 1
-            message.num_execs = num_execs - 1
-        await protocol._process_single_message(message)
         self.warning = message.warning
 
     async def fetch_next_row(self, cursor):