Added support for multiple pools with DRCP.

Author: anthony-tuininga

doc/src/api_manual/connect_params.rst

@@ -62,11 +62,15 @@ ConnectParams Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=None, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        extra_auth_params=None, handle=None)
+        extra_auth_params=None, pool_Name=None, handle=None)
 
     Sets the values for one or more of the parameters of a ConnectParams
     object.
 
+    .. versionchanged:: 3.2.0
+
+        The ``pool_name`` parameter was added.
+
     .. versionchanged:: 3.0.0
 
         The ``use_sni``, ``thick_mode_dsn_passthrough``, ``extra_auth_params``
@@ -333,6 +337,16 @@ ConnectParams Attributes
 
     .. versionadded:: 2.1.0
 
+.. attribute:: ConnectParams.pool_name
+
+    This read-only attribute is a string that specifies the name of the pool
+    when using multiple DRCP pools with Oracle Database 23.4 or later. See
+    :ref:`DRCP Pool Names <poolnames>`.
+
+    This attribute is supported in both python-oracledb Thin and Thick modes.
+
+    .. versionadded:: 3.2.0
+
 .. attribute:: ConnectParams.port
 
     This read-only attribute is an integer that returns the port number on

doc/src/api_manual/module.rst

@@ -47,7 +47,7 @@ Oracledb Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=False, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        extra_auth_params=None, handle=0)
+        extra_auth_params=None, pool_name=None, handle=0)
 
     Constructor for creating a connection to the database. Returns a
     :ref:`Connection Object <connobj>`. All parameters are optional and can be
@@ -410,6 +410,11 @@ Oracledb Methods
     used in both the python-oracledb Thin and Thick modes. See
     :ref:`tokenauth`.
 
+    The ``pool_name`` parameter is expected to be a string which specifies the
+    name of the pool when using multiple DRCP pools with Oracle Database 23.4
+    or later. This value is used in both python-oracledb Thin and Thick modes.
+    See :ref:`DRCP Pool Names <poolnames>`.
+
     If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
     and is only of use when embedding Python in an application (like
     PowerBuilder) which has already made the connection. The connection thus
@@ -418,6 +423,10 @@ Oracledb Methods
     is ignored in the Thin mode.  It should be used with extreme caution. The
     default value is *0*.
 
+    .. versionchanged:: 3.2.0
+
+        The ``pool_name`` parameter was added.
+
     .. versionchanged:: 3.0.0
 
         The ``pool_alias``, ``instance_name``, ``use_sni``,
@@ -470,7 +479,7 @@ Oracledb Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=False, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        extra_auth_params=None, handle=0)
+        extra_auth_params=None, pool_name=None, handle=0)
 
     Constructor for creating a connection to the database. Returns an
     :ref:`AsyncConnection Object <asyncconnobj>`. All parameters are optional
@@ -760,9 +769,18 @@ Oracledb Methods
     This value is used in both the python-oracledb Thin and Thick modes. See
     :ref:`tokenauth`.
 
+    The ``pool_name`` parameter is expected to be a string which specifies the
+    name of the pool when using multiple DRCP pools with Oracle Database 23.4
+    or later. This value is used in both python-oracledb Thin and Thick modes.
+    See :ref:`DRCP Pool Names <poolnames>`.
+
     The ``thick_mode_dsn_passthrough`` and ``handle`` parameters are ignored in
     python-oracledb Thin mode.
 
+    .. versionchanged:: 3.2.0
+
+        The ``pool_name`` parameter was added.
+
     .. versionchanged:: 3.0.0
 
         The ``pool_alias``, ``instance_name``, ``use_sni``,
@@ -813,7 +831,7 @@ Oracledb Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=False, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        extra_auth_params=None, handle=0)
+        extra_auth_params=None, pool_name=None, handle=0)
 
     Contains all the parameters that can be used to establish a connection to
     the database.
@@ -1130,11 +1148,20 @@ Oracledb Methods
     used in both the python-oracledb Thin and Thick modes. See
     :ref:`tokenauth`.
 
+    The ``pool_name`` parameter is expected to be a string which specifies the
+    name of the pool when using multiple DRCP pools with Oracle Database 23.4
+    or later. This value is used in both python-oracledb Thin and Thick modes.
+    See :ref:`DRCP Pool Names <poolnames>`.
+
     The ``handle`` parameter is expected to be an integer which represents a
     pointer to a valid service context handle. This value is only used in the
     python-oracledb Thick mode.  It should be used with extreme caution. The
     default value is *0*.
 
+    .. versionchanged:: 3.2.0
+
+        The ``pool_name`` parameter was added.
+
     .. versionchanged:: 3.0.0
 
         The ``instance_name``, ``use_sni``, ``thick_mode_dsn_passthrough`` and
@@ -1196,7 +1223,7 @@ Oracledb Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=False, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        extra_auth_params=None, handle=0)
+        extra_auth_params=None, pool_name=None, handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`ConnectionPool object <connpool>` for the pool.  See :ref:`Connection
@@ -1634,6 +1661,11 @@ Oracledb Methods
     used in both the python-oracledb Thin and Thick modes. See
     :ref:`tokenauth`.
 
+    The ``pool_name`` parameter is expected to be a string which specifies the
+    name of the pool when using multiple DRCP pools with Oracle Database 23.4
+    or later. This value is used in both python-oracledb Thin and Thick modes.
+    See :ref:`DRCP Pool Names <poolnames>`.
+
     If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
     and is only of use when embedding Python in an application (like
     PowerBuilder) which has already made the connection. The connection thus
@@ -1642,6 +1674,10 @@ Oracledb Methods
     is ignored in the Thin mode. It should be used with extreme caution. The
     default value is *0*.
 
+    .. versionchanged:: 3.2.0
+
+        The ``pool_name`` parameter was added.
+
     .. versionchanged:: 3.0.0
 
         The ``pool_alias``, ``instance_name``, ``use_sni``,
@@ -1698,7 +1734,7 @@ Oracledb Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=False, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        extra_auth_params=None, handle=0)
+        extra_auth_params=None, pool_name=None, handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`AsyncConnectionPool object <asyncconnpoolobj>` for the pool.
@@ -2047,9 +2083,18 @@ Oracledb Methods
     used in both the python-oracledb Thin and Thick modes. See
     :ref:`tokenauth`.
 
+    The ``pool_name`` parameter is expected to be a string which specifies the
+    name of the pool when using multiple DRCP pools with Oracle Database 23.4
+    or later. This value is used in both python-oracledb Thin and Thick modes.
+    See :ref:`DRCP Pool Names <poolnames>`.
+
     The ``handle`` and ``thick_mode_dsn_passthrough`` parameters are ignored in
     python-oracledb Thin mode.
 
+    .. versionchanged:: 3.2.0
+
+        The ``pool_name`` parameter was added.
+
     .. versionchanged:: 3.0.0
 
         The ``pool_alias``, ``instance_name``, ``use_sni``,
@@ -2293,7 +2338,7 @@ Oracledb Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=False, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        extra_auth_params=None, handle=0)
+        extra_auth_params=None, pool_name=None, handle=0)
 
     Creates and returns a :ref:`PoolParams Object <poolparam>`. The object
     can be passed to :meth:`oracledb.create_pool()`.
@@ -2674,11 +2719,20 @@ Oracledb Methods
     used in both the python-oracledb Thin and Thick modes. See
     :ref:`tokenauth`.
 
+    The ``pool_name`` parameter is expected to be a string which specifies the
+    name of the pool when using multiple DRCP pools with Oracle Database 23.4
+    or later. This value is used in both python-oracledb Thin and Thick modes.
+    See :ref:`DRCP Pool Names <poolnames>`.
+
     The ``handle`` parameter is expected to be an integer which represents a
     pointer to a valid service context handle. This value is only used in the
     python-oracledb Thick mode. It should be used with extreme caution. The
     default value is *0*.
 
+    .. versionchanged:: 3.2.0
+
+        The ``pool_name`` parameter was added.
+
     .. versionchanged:: 3.0.0
 
         The ``use_sni``, ``instance_name``, ``thick_mode_dsn_passthrough``,

doc/src/api_manual/pool_params.rst

@@ -53,10 +53,14 @@ PoolParams Methods
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
         driver_name=oracledb.defaults.driver_name, use_sni=None, \
         thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
-        extra_auth_params=None, handle=None)
+        extra_auth_params=None, pool_name=None, handle=None)
 
         Sets one or more of the parameters.
 
+        .. versionchanged:: 3.2.0
+
+            The ``pool_name`` parameter was added.
+
         .. versionchanged:: 3.0.0
 
             The ``use_sni``, ``thick_mode_dsn_passthrough``,

doc/src/release_notes.rst

@@ -47,6 +47,8 @@ Thick Mode Changes
 Common Changes
 ++++++++++++++
 
+#)  Added parameter ``pool_name`` to connection and pool creation methods to
+    support Oracle Database 23ai multi-pool :ref:`drcp`.
 #)  Added Instance Principal authentication support when using
     :ref:`OCI Cloud Native Authentication <cloudnativeauthoci>`.
 #)  Use GitHub Arm Linux runner for builds. Supplied by wojiushixiaobai

doc/src/user_guide/connection_handling.rst

@@ -2893,7 +2893,11 @@ Enabling DRCP in Oracle Database
 Oracle Database versions prior to 21c can have a single DRCP connection pool.
 From Oracle Database 21c, each pluggable database can optionally have its own
 pool, or can use the container level pool. From Oracle Database 23ai, you can
-create multiple pools at the pluggable, or container, database level.
+create multiple pools at the pluggable, or container, database level. This
+multi-pool feature is useful where different applications connect to the same
+database, but there is a concern that one application's use of the pool may
+impact other applications. If this is not the case, a single pool may allow
+best resource sharing on the database host.
 
 Note that DRCP is already enabled in Oracle Autonomous Database and pool
 management is different to the steps below.
@@ -3033,7 +3037,7 @@ To enable connections to use DRCP pooled servers, you can:
                                 server_type="pooled",
                                 cclass="MYAPP")
 
-**DRCP Connection Class Names**
+**DRCP Connection Classes**
 
 The best practice is to specify a ``cclass`` class name when creating a
 python-oracledb connection pool.  This user-chosen name provides some
@@ -3071,14 +3075,37 @@ default, python-oracledb pooled connections use ``PURITY_SELF`` and standalone
 connections use ``PURITY_NEW``.
 
 To limit session sharing, you can explicitly require that new session memory be
-allocated each time :meth:`~ConnectionPool.acquire()` is called:
+allocated each time :meth:`~ConnectionPool.acquire()` is called. Do this when
+creating a driver connection pool by specifying the ``purity`` as
+``PURITY_NEW``:
 
 .. code-block:: python
 
     pool = oracledb.create_pool(user="hr", password=userpwd, dsn="dbhost.example.com/orclpdb:pooled",
                                 min=2, max=5, increment=1,
                                 cclass="MYAPP", purity=oracledb.PURITY_NEW)
 
+The overheads can impact ultimate scalability.
+
+.. _poolnames:
+
+**DRCP Pool Names**
+
+From Oracle Database 23ai, multiple DRCP pools can be created by setting a pool
+name at DRCP pool creation time. Applications can then specifiy which DRCP pool
+to use by passing the ``pool_name`` parameter during connection, or connection
+pool, creation, for example:
+
+.. code-block:: python
+
+    pool = oracledb.create_pool(user="hr", password=userpwd,
+                                dsn="dbhost.example.com/orclpdb:pooled",
+                                min=2, max=5, increment=1,
+                                cclass="MYAPP", pool_name="MYPOOL")
+
+When specifying a pool name, you should still set a connection class name to
+allow efficient use of the pool's resources.
+
 **Acquiring a DRCP Connection**
 
 Once DRCP has been enabled and the driver connection pool has been created with
@@ -3132,39 +3159,40 @@ other users:
     . . .
     connection.close()
 
-Setting the DRCP Connection Class and Purity in the Connection String
----------------------------------------------------------------------
+Setting DRCP Parameters in Connection Strings
+---------------------------------------------
 
-Although setting the DRCP connection class and purity in the application is
-preferred, sometimes it is not possible to modify an existing code base. For
-these applications, you can specify the class and purity along with the pooled
-server option in the connection string.
+Setting the DRCP connection class, purity, and pool name as function parameters
+in the application is preferred, but sometimes it is not possible to modify an
+existing code base. For these applications, you can specify the values along
+with the pooled server option in the connection string.
+
+You can specify the class and purity options in connection strings when using
+Oracle Database 21c, or later. You can specify the pool name when using Oracle
+Database 23ai, or later.
 
 For example with the :ref:`Easy Connect <easyconnect>` syntax::
 
-    dbhost.example.com/orclpdb:pooled?pool_connection_class=MYAPP&pool_purity=self
+    dbhost.example.com/orclpdb:pooled?pool_connection_class=MYAPP&pool_purity=self&pool_name=MYPOOL
 
-or by using a :ref:`TNS Alias <netservice>` in a
+Or by using a :ref:`TNS Alias <netservice>` in a
 :ref:`tnsnames.ora <optnetfiles>` file::
 
     customerpool = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)
               (HOST=dbhost.example.com)
               (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=orclpdb)
               (SERVER=POOLED)
               (POOL_CONNECTION_CLASS=MYAPP)
-              (POOL_PURITY=SELF)))
-
-You can specify the class and purity options in connection strings when using
-python-oracledb Thin mode with Oracle Database 21c, or later.
-
-For python-oracledb Thick mode, setting these options in the connection string
-is supported if you are using Oracle Database 21c (or later) and Oracle Client
-19c (or later). However, explicitly specifying the purity as *SELF* in this way
-may cause some unusable connections in a python-oracledb Thick mode connection
-pool to not be terminated. In summary, if you cannot programmatically set the
-class name and purity, or cannot use python-oracledb Thin mode, then avoid
-explicitly setting the purity as a connection string parameter when using a
-local python-oracledb connection pool in Thick mode.
+              (POOL_PURITY=SELF)
+              (POOL_NAME=MYPOOL)))
+
+Explicitly specifying the purity as *SELF* in a connection string may cause
+some unusable connections in a python-oracledb Thick mode connection pool to
+not be terminated, potentially eventually rendering all connections in the pool
+to be unusable. If you cannot programmatically set the class name and purity,
+or cannot use python-oracledb Thin mode, then avoid explicitly setting the
+purity as a connection string parameter when using a local python-oracledb
+Thick mode connection pool.
 
 .. _monitoringdrcp:
 

src/oracledb/base_impl.pxd

@@ -503,6 +503,7 @@ cdef class Description(ConnectParamsNode):
         public str cclass
         public str connection_id_prefix
         public str pool_boundary
+        public str pool_name
         public uint32_t purity
         public bint ssl_server_dn_match
         public bint use_tcp_fast_open