All connect strings are parsed in the driver.

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -68,6 +68,13 @@ Common Changes
 #)  Added :meth:`oracledb.register_password_type()` to allow users to register
     a function that will be called when a password is supplied as a dictionary
     containing the key "type".
+#)  All connect strings are now parsed by the driver. Previously, only thin
+    mode parsed all connect strings and thick mode passed the connect string
+    unchanged to the Oracle Client library to parse. Parameters unrecognized by
+    the driver in Easy Connect strings are now ignored. Parameters unrecognized
+    by the driver in the ``CONNECT_DATA`` section of a full connect descriptor
+    are passed through unchanged. All other parameters in other sections of a
+    full connect deescriptor that are unrecognized by the driver are ignored.
 #)  Added attributes :attr:`DbObjectAttribute.precision`,
     :attr:`DbObjectAttribute.scale`, and :attr:`DbObjectAttribute.max_size` that
     provide additional metadata about

doc/src/user_guide/connection_handling.rst

@@ -129,19 +129,16 @@ If you like to encapsulate values, parameters can be passed using a
     conn = oracledb.connect(user="my_user", password="my_password", params=params)
 
 Some values such as the database host name can be specified as ``connect()``
-parameters, as part of the connect string, and in the ``params`` object.  If a
-``dsn`` is passed, the python-oracledb :ref:`Thick <enablingthick>` mode will
-use the ``dsn`` string to connect. Otherwise, a connection string is internally
-constructed from the individual parameters and ``params`` object values, with
-the individual parameters having precedence.  In python-oracledb's default Thin
-mode, a connection string is internally used that contains all relevant values
-specified.  The precedence in Thin mode is that values in any ``dsn`` parameter
-override values passed as individual parameters, which themselves override
-values set in the ``params`` object.  Similar precedence rules also apply to
-other values.
+parameters, as part of the connect string, and in the ``params`` object. If a
+``dsn`` is passed, a connection string is internally constructed from the
+individual parameters and ``params`` object values, with the individual
+parameters having precedence. The precedence is that values in any ``dsn``
+parameter override values passed as individual parameters, which themselves
+override values set in the ``params`` object. Similar precedence rules also
+apply to other values.
 
 A single, combined connection string can be passed to ``connect()`` but this
-may cause complications if the password contains '@' or '/' characters:
+may cause complications if the password contains "@" or "/" characters:
 
 .. code-block:: python
 
@@ -329,26 +326,37 @@ If the database is using a non-default port, it must be specified:
 The Easy Connect syntax supports Oracle Database service names.  It cannot be
 used with the older System Identifiers (SID).
 
-The latest `Easy Connect <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
+The `Easy Connect <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
 id=GUID-8C85D289-6AF3-41BC-848B-BF39D32648BA>`__ syntax allows the use of
 multiple hosts or ports, along with optional entries for the wallet location,
 the distinguished name of the database server, and allows some network
 configuration options such as the connection timeout and keep-alive values to
-be set. This means that a :ref:`sqlnet.ora <optnetfiles>` file is not needed
-for some common connection scenarios. See the technical brief `Oracle Database
-Easy Connect Plus <https://download.oracle.com/ocomdocs/global/Oracle-Net-Easy
--Connect-Plus.pdf>`__ for more information.
+be set::
 
-In python-oracledb Thin mode, any unknown Easy Connect options are ignored and
-are not passed to the database.  See :ref:`Connection String Differences
-<diffconnstr>` for more information.
+.. code-block:: python
 
-In python-oracledb Thick mode, it is the Oracle Client libraries that parse the
-Easy Connect string.  Check the Easy Connect Naming method in `Oracle Net
-Service Administrator's Guide
-<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
-id=GUID-B0437826-43C1-49EC-A94D-B650B6A4A6EE>`__ for the syntax to use in your
-version of the Oracle Client libraries.
+    connection = oracledb.connect(user="hr", password=userpwd,
+                                  dsn="dbhost.example.com/orclpdb?expire_time=2")
+
+This means that a :ref:`sqlnet.ora <optnetfiles>` file is not needed for common
+connection scenarios. See the technical brief `Oracle Database Easy Connect
+Plus <https://download.oracle.com/ocomdocs/global/Oracle-Net-Easy
+-Connect-Plus.pdf>`__ for additional information.
+
+Python-oracledb specific settings can also be passed as Easy Connect arguments.
+For example to set the statement cache size used by connections::
+
+.. code-block:: python
+
+    connection = oracledb.connect(user="hr", password=userpwd,
+                                  dsn="dbhost.example.com/orclpdb?pyo.stmtcachesize=50")
+
+See :ref:`defineconnparams` and :ref:`definepoolparams` for the settings that
+can be passed as arguments.
+
+Any Easy Connect parameters that are unknown to python-oracledb are ignored and
+not passed to the database.  See :ref:`Connection String Differences
+<diffconnstr>` for more information.
 
 .. _conndescriptor:
 
@@ -386,6 +394,9 @@ This prints::
 
     (DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=tcp)(HOST=dbhost.example.com)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=orclpdb))(SECURITY=(SSL_SERVER_DN_MATCH=True)))
 
+The ``CONNECT_DATA`` parameters of a full connect descriptor that are
+unrecognized by python-oracledb are passed to the database unchanged.
+
 .. _netservice:
 
 TNS Aliases for Connection Strings
@@ -1216,12 +1227,9 @@ Note :meth:`ConnectParams.set()` has no effect after
 
 Some values such as the database host name can be specified as
 :func:`oracledb.connect()`, parameters, as part of the connect string, and in
-the ``params`` object.  If a ``dsn`` is passed, the python-oracledb :ref:`Thick
-<enablingthick>` mode will use the ``dsn`` string to connect. Otherwise, a
-connection string is internally constructed from the individual parameters and
-``params`` object values, with the individual parameters having precedence.  In
-python-oracledb's default Thin mode, a connection string is internally used
-that contains all relevant values specified.  The precedence in Thin mode is
+the ``params`` object.  If a ``dsn`` is passed, a connection string is
+internally constructed from the individual parameters and ``params`` object
+values, with the individual parameters having precedence. The precedence is
 that values in any ``dsn`` parameter override values passed as individual
 parameters, which themselves override values set in the ``params`` object.
 Similar precedence rules also apply to other values.
@@ -2454,15 +2462,12 @@ individually using the ``set()`` method:
 
 Some values such as the database host name, can be specified as
 :func:`oracledb.create_pool()` parameters, as part of the connect string, and
-in the ``params`` object.  If a ``dsn`` is passed, the python-oracledb
-:ref:`Thick <enablingthick>` mode will use the ``dsn`` string to connect.
-Otherwise, a connection string is internally constructed from the individual
-parameters and ``params`` object values, with the individual parameters having
-precedence.  In python-oracledb's default Thin mode, a connection string is
-internally used that contains all relevant values specified.  The precedence in
-Thin mode is that values in any ``dsn`` parameter override values passed as
-individual parameters, which themselves override values set in the ``params``
-object.  Similar precedence rules also apply to other values.
+in the ``params`` object.  If a ``dsn`` is passed, a connection string is
+internally constructed from the individual parameters and ``params`` object
+values, with the individual parameters having precedence. The precedence is
+that values in any ``dsn`` parameter override values passed as individual
+parameters, which themselves override values set in the ``params`` object.
+Similar precedence rules also apply to other values.
 
 .. _definepoolparams:
 

src/oracledb/base_impl.pxd

@@ -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
@@ -500,9 +500,11 @@ cdef class Description(ConnectParamsNode):
         public str ssl_server_cert_dn
         public object ssl_version
         public str wallet_location
+        dict extra_connect_data_args
         str connection_id
 
     cdef str _build_duration_str(self, double value)
+    cdef str _value_repr(self, object value)
     cdef str build_connect_string(self, str cid=*)
     cdef int set_server_type(self, str value) except -1
 
@@ -556,6 +558,7 @@ cdef class ConnectParamsImpl:
 
     cdef int _check_credentials(self) except -1
     cdef int _copy(self, ConnectParamsImpl other_params) except -1
+    cdef str _get_connect_string(self)
     cdef bytes _get_new_password(self)
     cdef bytearray _get_obfuscator(self, str secret_value)
     cdef bytes _get_password(self)

src/oracledb/connection.py

@@ -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
@@ -549,7 +549,7 @@ def __init__(
                 errors._raise_err(errors.ERR_INVALID_CONNECT_PARAMS)
             else:
                 params_impl = params._impl.copy()
-            dsn = params_impl.process_args(dsn, kwargs, thin)
+            dsn = params_impl.process_args(dsn, kwargs)
 
             # see if connection is being acquired from a pool
             if pool is None:
@@ -1545,7 +1545,7 @@ async def _connect(self, dsn, pool, params, kwargs):
             errors._raise_err(errors.ERR_INVALID_CONNECT_PARAMS)
         else:
             params_impl = params._impl.copy()
-        dsn = params_impl.process_args(dsn, kwargs, thin=True)
+        dsn = params_impl.process_args(dsn, kwargs)
 
         # see if connection is being acquired from a pool
         if pool is None:

src/oracledb/impl/base/connect_params.pyx

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2022, 2024, Oracle and/or its affiliates.
+# Copyright (c) 2022, 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
@@ -188,6 +188,12 @@ cdef class ConnectParamsImpl:
         self.osuser = other_params.osuser
         self.driver_name = other_params.driver_name
 
+    cdef str _get_connect_string(self):
+        """
+        Returns the connect string to use for the stored components.
+        """
+        return self.description_list.build_connect_string()
+
     cdef bytes _get_new_password(self):
         """
         Returns the new password, after removing the obfuscation.
@@ -434,7 +440,7 @@ cdef class ConnectParamsImpl:
         """
         Returns a connect string generated from the parameters.
         """
-        return self.description_list.build_connect_string()
+        return self._get_connect_string()
 
     def get_full_user(self):
         """
@@ -511,16 +517,15 @@ cdef class ConnectParamsImpl:
         else:
             self.user = user
 
-    def process_args(self, str dsn, dict kwargs, bint thin):
+    def process_args(self, str dsn, dict kwargs):
         """
         Processes the arguments to connect() and create_pool().
 
             - the keyword arguments are set
             - if no user was specified in the keyword arguments and a dsn is
               specified, it is parsed to determine the user, password and
               connect string and the user and password are stored
-            - in thin mode, the connect string is then parsed into its
-              components and stored
+            - the connect string is then parsed into its components and stored
             - if no dsn was specified, one is built from the components
             - the connect string is returned
         """
@@ -529,10 +534,10 @@ cdef class ConnectParamsImpl:
         if self.user is None and not self.externalauth and dsn is not None:
             user, password, dsn = self.parse_dsn_with_credentials(dsn)
             self.set(dict(user=user, password=password))
-        if dsn is not None and thin:
+        if dsn is not None:
             self.parse_connect_string(dsn)
-        if dsn is None:
-            dsn = self.get_connect_string()
+        else:
+            dsn = self._get_connect_string()
         return dsn
 
 
@@ -767,6 +772,17 @@ cdef class Description(ConnectParamsNode):
             return f"{value_minutes}min"
         return f"{value_int}"
 
+    cdef str _value_repr(self, object value):
+        """
+        Returns the representation to use for a value. Strings are returned as
+        is but dictionaries are returned as key/value pairs in the format
+        expected by the listener.
+        """
+        if isinstance(value, str):
+            return value
+        return "".join(f"({k.upper()}={self._value_repr(v)})"
+                       for k, v in value.items())
+
     cdef str build_connect_string(self, str cid=None):
         """
         Build a connect string from the components.
@@ -829,6 +845,9 @@ cdef class Description(ConnectParamsNode):
                 temp_parts.append(f"(POOL_PURITY=SELF)")
             elif self.purity == PURITY_NEW:
                 temp_parts.append(f"(POOL_PURITY=NEW)")
+        if self.extra_connect_data_args is not None:
+            temp_parts.extend(f"({k.upper()}={self._value_repr(v)})"
+                              for k, v in self.extra_connect_data_args.items())
         if self.connection_id is not None:
             temp_parts.append(f"(CONNECTION_ID={self.connection_id})")
         if temp_parts:
@@ -904,6 +923,9 @@ cdef class Description(ConnectParamsNode):
         _set_str_param(args, "pool_boundary", self)
         _set_str_param(args, "connection_id_prefix", self)
         _set_bool_param(args, "use_tcp_fast_open", &self.use_tcp_fast_open)
+        extra_args = args.get("extra_connect_data_args")
+        if extra_args is not None:
+            self.extra_connect_data_args = extra_args
 
     def set_from_description_args(self, dict args):
         """

src/oracledb/impl/base/parsers.pyx

@@ -50,8 +50,21 @@ CONTAINER_PARAM_NAMES = set([
     "security",
 ])
 
-# a set of parameter names supported in EasyConnect strings that are common
-# to all drivers
+# CONNECT_DATA parameter names that are supported by the driver; all other
+# simple key/value pairs are passed unchanged to the database
+CONNECT_DATA_PARAM_NAMES = set([
+    "cclass",
+    "connection_id_prefix",
+    "pool_boundary",
+    "purity",
+    "server_type",
+    "service_name",
+    "sid",
+    "use_tcp_fast_open",
+])
+
+# a set of parameter names supported by the driver in EasyConnect strings that
+# are common to all drivers
 COMMON_PARAM_NAMES = set([
     "expire_time",
     "https_proxy",
@@ -593,6 +606,22 @@ cdef class ConnectStringParser(BaseParser):
             value = self.data_as_str[service_name_end_pos + 1:self.temp_pos]
             self.description.set_server_type(value)
 
+    cdef dict _set_connect_data(self, dict args):
+        """
+        Sets the connect data value.
+        """
+        cdef:
+            dict extras, result = {}
+            object value
+            str key
+        for key, value in args.items():
+            if key in CONNECT_DATA_PARAM_NAMES:
+                result[key] = value
+            else:
+                extras = result.setdefault("extra_connect_data_args", {})
+                extras[key] = value
+        return result
+
     cdef int _set_descriptor_arg(
         self, dict args, str name, object value
     ) except -1:
@@ -614,6 +643,8 @@ cdef class ConnectStringParser(BaseParser):
                 if not isinstance(addresses, list):
                     addresses = [addresses]
                 value = [dict(address=a) for a in addresses] + [value]
+            elif name == "connect_data":
+                value = self._set_connect_data(value)
             args[name] = value
         elif isinstance(orig_value, list):
             args[name].append(value)