Add support for passthrough of connect strings to the Oracle Client

library parser (for backwards compatibility).

Author: anthony-tuininga

doc/src/api_manual/connect_params.rst

@@ -62,14 +62,17 @@ ConnectParams Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, use_sni=None, handle=None)
+        driver_name=oracledb.defaults.driver_name, use_sni=None, \
+        thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
+        handle=None)
 
     Sets the values for one or more of the parameters of a ConnectParams
     object.
 
     .. versionchanged:: 3.0.0
 
-        The ``use_sni`` and ``instance_name`` parameters were added.
+        The ``use_sni``, ``thick_mode_dsn_passthrough``, and ``instance_name``
+        parameters were added.
 
     .. versionchanged:: 2.5.0
 
@@ -544,6 +547,18 @@ ConnectParams Attributes
 
     .. versionadded:: 2.5.0
 
+.. attribute:: ConnectParams.thick_mode_dsn_passthrough
+
+    This read-only attribute is a boolean which indicates whether the connect
+    string should be passed unchanged to Oracle Client libraries for parsing or
+    if python-oracledb should parse the connect string itself when using Thick
+    mode. The default value is the value of
+    :attr:`defaults.thick_mode_dsn_passthrough`.
+
+    This attribute is only supported in python-oracledb Thick mode.
+
+    .. versionadded:: 3.0.0
+
 .. attribute:: ConnectParams.use_tcp_fast_open
 
     This read-only attribute is a boolean which indicates whether to use an

doc/src/api_manual/defaults.rst

@@ -162,3 +162,30 @@ Defaults Attributes
     This attribute is only used in python-oracledb Thin mode.
 
     .. versionadded:: 2.5.0
+
+.. attribute:: defaults.thick_mode_dsn_passthrough
+
+    The default value that determines whether :ref:`connection strings
+    <connstr>` passed to :meth:`oracledb.connect()` and
+    :meth:`oracledb.create_pool()` in python-oracledb Thick mode will be parsed
+    by Oracle Client libraries or by python-oracledb itself.
+
+    When the value of this attribute is *True*, then connection strings passed
+    to these methods will be sent unchanged to the Oracle Client libraries.
+
+    Setting this attribute to *False* makes Thick and Thin mode applications
+    behave similarly regarding connection string parameter handling and
+    locating any optional :ref:`tnsnames.ora files <optnetfiles>` configuration
+    file, see :ref:`usingconfigfiles`. Connection strings used in connection
+    and pool creation methods in Thick mode are parsed by python-oracledb
+    itself and a generated connect descriptor is sent to the Oracle Client
+    libraries. The location of any optional :ref:`tnsnames.ora file
+    <optnetfiles>` used to resolve a :ref:`TNS Alias <netservice>` is
+    determined by python-oracledb heuristics instead of by the Oracle Client
+    libraries.
+
+    This attribute has an initial value of *True*.
+
+    This attribute is ignored in python-oracledb Thin mode.
+
+    .. versionadded:: 3.0.0

doc/src/api_manual/module.rst

@@ -52,7 +52,9 @@ Oracledb Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, use_sni=False, handle=0)
+        driver_name=oracledb.defaults.driver_name, use_sni=False, \
+        thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
+        handle=0)
 
     Constructor for creating a connection to the database. Returns a
     :ref:`Connection Object <connobj>`. All parameters are optional and can be
@@ -397,6 +399,15 @@ Oracledb Methods
     is used in both the python-oracledb Thin and Thick modes.  The default is
     the value of :attr:`defaults.driver_name`.
 
+    The ``thick_mode_dsn_passthrough`` parameter is expected to be a boolean
+    which indicates whether the connect string should be passed unchanged to
+    the Oracle Client libraries for parsing when using python-oracledb Thick
+    mode. If this parameter is set to *False* in Thick mode, connect strings
+    are parsed by python-oracledb itself and a generated connect descriptor is
+    sent to the Oracle Client libraries. This value is only used in the
+    python-oracledb Thick mode. The default value is the value of
+    :attr:`defaults.thick_mode_dsn_passthrough`.
+
     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
@@ -407,9 +418,9 @@ Oracledb Methods
 
     .. versionchanged:: 3.0.0
 
-        The ``pool_alias``, ``instance_name`` and ``use_sni`` parameters were
-        added.  The ``pool`` parameter was deprecated. Use
-        :meth:`ConnectionPool.acquire()` instead.
+        The ``pool_alias``, ``instance_name``, ``use_sni``, and
+        ``thick_mode_dsn_passthrough`` parameters were added.  The ``pool``
+        parameter was deprecated. Use :meth:`ConnectionPool.acquire()` instead.
 
     .. versionchanged:: 2.5.0
 
@@ -454,7 +465,9 @@ Oracledb Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, use_sni=False, handle=0)
+        driver_name=oracledb.defaults.driver_name, use_sni=False, \
+        thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
+        handle=0)
 
     Constructor for creating a connection to the database. Returns an
     :ref:`AsyncConnection Object <asyncconnobj>`. All parameters are optional
@@ -734,13 +747,15 @@ Oracledb Methods
     is used in both the python-oracledb Thin and Thick modes.  The default is
     the value of :attr:`defaults.driver_name`.
 
-    The ``handle`` parameter is ignored in the python-oracledb Thin mode.
+    The ``thick_mode_dsn_passthrough`` and ``handle`` parameters are ignored in
+    python-oracledb Thin mode.
 
     .. versionchanged:: 3.0.0
 
-        The ``pool_alias``, ``instance_name`` and ``use_sni`` parameters were
-        added. The ``pool`` parameter was deprecated. Use
-        :meth:`AsyncConnectionPool.acquire()` instead.
+        The ``pool_alias``, ``instance_name``, ``use_sni``, and
+        ``thick_mode_dsn_passthrough`` parameters were added. The ``pool``
+        parameter was deprecated. Use :meth:`AsyncConnectionPool.acquire()`
+        instead.
 
     .. versionchanged:: 2.5.0
 
@@ -783,7 +798,9 @@ Oracledb Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, use_sni=False, handle=0)
+        driver_name=oracledb.defaults.driver_name, use_sni=False, \
+        thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
+        handle=0)
 
     Contains all the parameters that can be used to establish a connection to
     the database.
@@ -1082,14 +1099,24 @@ Oracledb Methods
     is used in both the python-oracledb Thin and Thick modes.  The default is
     the value of :attr:`defaults.driver_name`.
 
+    The ``thick_mode_dsn_passthrough`` parameter is expected to be a boolean
+    which indicates whether the connect string should be passed unchanged to
+    the Oracle Client libraries for parsing when using python-oracledb Thick
+    mode. If this parameter is set to *False* in Thick mode, connect strings
+    are parsed by python-oracledb itself and a generated connect descriptor is
+    sent to the Oracle Client libraries. This value is only used in the
+    python-oracledb Thick mode. The default value is the value of
+    :attr:`defaults.thick_mode_dsn_passthrough`.
+
     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.0.0
 
-        The ``use_sni`` and ``instance_name`` parameters were added.
+        The ``use_sni``, ``thick_mode_dsn_passthrough``, and ``instance_name``
+        parameters were added.
 
     .. versionchanged:: 2.5.0
 
@@ -1150,7 +1177,9 @@ Oracledb Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, use_sni=False, handle=0)
+        driver_name=oracledb.defaults.driver_name, use_sni=False, \
+        thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
+        handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`ConnectionPool object <connpool>` for the pool.  See :ref:`Connection
@@ -1570,6 +1599,15 @@ Oracledb Methods
     is used in both the python-oracledb Thin and Thick modes.  The default is
     the value of :attr:`defaults.driver_name`.
 
+    The ``thick_mode_dsn_passthrough`` parameter is expected to be a boolean
+    which indicates whether the connect string should be passed unchanged to
+    the Oracle Client libraries for parsing when using python-oracledb Thick
+    mode. If this parameter is set to *False* in Thick mode, connect strings
+    are parsed by python-oracledb itself and a generated connect descriptor is
+    sent to the Oracle Client libraries. This value is only used in the
+    python-oracledb Thick mode. The default value is
+    :attr:`defaults.thick_mode_dsn_passthrough`.
+
     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
@@ -1580,8 +1618,8 @@ Oracledb Methods
 
     .. versionchanged:: 3.0.0
 
-        The ``pool_alias``, ``instance_name`` and ``use_sni`` parameters were
-        added.
+        The ``pool_alias``, ``instance_name``, ``use_sni``, and
+        ``thick_mode_dsn_passthrough`` parameters were added.
 
     .. versionchanged:: 2.5.0
 
@@ -1631,7 +1669,9 @@ Oracledb Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, use_sni=False, handle=0)
+        driver_name=oracledb.defaults.driver_name, use_sni=False, \
+        thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
+        handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`AsyncConnectionPool object <asyncconnpoolobj>` for the pool.
@@ -1970,12 +2010,13 @@ Oracledb Methods
     is used in both the python-oracledb Thin and Thick modes.  The default is
     the value of :attr:`defaults.driver_name`.
 
-    The ``handle`` parameter is ignored in the python-oracledb Thin mode.
+    The ``handle`` and ``thick_mode_dsn_passthrough`` parameters are ignored in
+    python-oracledb Thin mode.
 
     .. versionchanged:: 3.0.0
 
-        The ``pool_alias``, ``instance_name`` and ``use_sni`` parameters were
-        added.
+        The ``pool_alias``, ``instance_name``, ``use_sni``, and
+        ``thick_mode_dsn_passthrough`` parameters were added.
 
     .. versionchanged:: 2.5.0
 
@@ -2192,7 +2233,9 @@ Oracledb Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, use_sni=False, handle=0)
+        driver_name=oracledb.defaults.driver_name, use_sni=False, \
+        thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
+        handle=0)
 
     Creates and returns a :ref:`PoolParams Object <poolparam>`. The object
     can be passed to :meth:`oracledb.create_pool()`.
@@ -2555,14 +2598,24 @@ Oracledb Methods
     is used in both the python-oracledb Thin and Thick modes.  The default is
     the value of :attr:`defaults.driver_name`.
 
+    The ``thick_mode_dsn_passthrough`` parameter is expected to be a boolean
+    which indicates whether the connect string should be passed unchanged to
+    the Oracle Client libraries for parsing when using python-oracledb Thick
+    mode. If this parameter is set to *False* in Thick mode, connect strings
+    are parsed by python-oracledb itself and a generated connect descriptor is
+    sent to the Oracle Client libraries. This value is only used in the
+    python-oracledb Thick mode. The default value is
+    :attr:`defualts.thick_mode_dsn_passthrough`.
+
     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.0.0
 
-        The ``use_sni`` and ``instance_name`` parameters were added.
+        The ``use_sni``, ``thick_mode_dsn_passthrough``, and ``instance_name``
+        parameters were added.
 
     .. versionchanged:: 2.5.0
 

doc/src/api_manual/pool_params.rst

@@ -51,13 +51,16 @@ PoolParams Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, use_sni=None, handle=None)
+        driver_name=oracledb.defaults.driver_name, use_sni=None, \
+        thick_mode_dsn_passthrough=oracledb.defaults.thick_mode_dsn_passthrough, \
+        handle=None)
 
         Sets one or more of the parameters.
 
         .. versionchanged:: 3.0.0
 
-            The ``use_sni`` and ``instance_name`` parameters were added.
+            The ``use_sni``, ``thick_mode_dsn_passthrough``, and
+            ``instance_name`` parameters were added.
 
         .. versionchanged:: 2.5.0
 

doc/src/release_notes.rst

@@ -88,7 +88,8 @@ 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
+#)  All connect strings are parsed by the driver if the new parameter
+    ``thick_mode_dsn_passthrough`` is set to *True*. 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 :ref:`Easy Connect strings <easyconnect>` are now ignored.

src/oracledb/base_impl.pxd

@@ -241,6 +241,7 @@ cdef class DefaultsImpl:
         public str config_dir
         public bint fetch_lobs
         public bint fetch_decimals
+        public bint thick_mode_dsn_passthrough
         public uint32_t prefetchrows
         public uint32_t stmtcachesize
         public str program
@@ -559,6 +560,7 @@ cdef class ConnectParamsImpl:
         public str terminal
         public str osuser
         public str driver_name
+        public bint thick_mode_dsn_passthrough
 
     cdef int _check_credentials(self) except -1
     cdef int _copy(self, ConnectParamsImpl other_params) except -1

src/oracledb/connect_params.py

@@ -105,6 +105,7 @@ def __init__(
         osuser: Optional[str] = None,
         driver_name: Optional[str] = None,
         use_sni: Optional[bool] = None,
+        thick_mode_dsn_passthrough: Optional[bool] = None,
         handle: Optional[int] = None,
     ):
         """
@@ -302,6 +303,14 @@ def __init__(
           bypass the second TLS neogiation that would otherwise be required
           (default: False)
 
+        - thick_mode_dsn_passthrough: boolean indicating whether to pass the
+          connect string to the Oracle Client libraries unchanged without
+          parsing by the driver. Setting this to False makes thick and thin
+          mode applications behave similarly regarding connection string
+          parameter handling and locating any optional tnsnames.ora
+          configuration file (default:
+          oracledb.defaults.thick_mode_dsn_passthrough)
+
         - 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)
@@ -356,7 +365,8 @@ def __repr__(self):
             + f"terminal={self.terminal!r}, "
             + f"osuser={self.osuser!r}, "
             + f"driver_name={self.driver_name!r}, "
-            + f"use_sni={self.use_sni!r}"
+            + f"use_sni={self.use_sni!r}, "
+            + f"thick_mode_dsn_passthrough={self.thick_mode_dsn_passthrough!r}"
             + ")"
         )
 
@@ -740,6 +750,17 @@ def terminal(self) -> str:
         """
         return self._impl.terminal
 
+    @property
+    def thick_mode_dsn_passthrough(self) -> bool:
+        """
+        Boolean indicating whether to pass the connect string to the Oracle
+        Client libraries unchanged without parsing by the driver. Setting this
+        to False makes thick and thin mode applications behave similarly
+        regarding connection string parameter handling and locating any
+        optional tnsnames.ora configuration file.
+        """
+        return self._impl.thick_mode_dsn_passthrough
+
     @property
     def user(self) -> str:
         """
@@ -877,6 +898,7 @@ def set(
         osuser: Optional[str] = None,
         driver_name: Optional[str] = None,
         use_sni: Optional[bool] = None,
+        thick_mode_dsn_passthrough: Optional[bool] = None,
         handle: Optional[int] = None,
     ):
         """
@@ -1061,6 +1083,13 @@ def set(
         - use_sni: boolean indicating whether to use the TLS SNI extension to
           bypass the second TLS neogiation that would otherwise be required
 
+        - thick_mode_dsn_passthrough: boolean indicating whether to pass the
+          connect string to the Oracle Client libraries unchanged without
+          parsing by the driver. Setting this to False makes thick and thin
+          mode applications behave similarly regarding connection string
+          parameter handling and locating any optional tnsnames.ora
+          configuration file
+
         - 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