Added new method enable_thin_mode() as requested (#408).

Author: anthony-tuininga

doc/src/api_manual/module.rst

@@ -1891,6 +1891,26 @@ Oracledb Methods
     (number of seconds since the epoch; see the documentation of the standard
     Python time module for details).
 
+
+.. function:: enable_thin_mode()
+
+    Makes python-oracledb be in Thin mode. After this method is called, Thick
+    mode cannot be enabled. If python-oracledb is already in Thick mode, then
+    calling ``enable_thin_mode()`` will fail. If connections have already been
+    opened, or a connection pool created, in Thin mode, then calling
+    ``enable_thin_mode()`` is a no-op.
+
+    Since python-oracledb defaults to Thin mode, almost all applications do not
+    need to call this method. However, because it bypasses python-oracledb's
+    internal mode-determination heuristic, it may be useful for applications
+    that are using :ref:`standalone connections <standaloneconnection>` in
+    multiple threads to concurrently create connections when the application
+    starts.
+
+    See :ref:`enablingthin` for more information.
+
+    .. versionadded:: 2.5.0
+
 .. function:: init_oracle_client(lib_dir=None, config_dir=None, \
         error_url=None, driver_name=None)
 

doc/src/release_notes.rst

@@ -34,6 +34,12 @@ Thin Mode Changes
 #)  Added :meth:`oracledb.register_protocol()` to allow users to register a
     function that will be called when a particular protocol is detected in a
     connection string.
+#)  Added :meth:`oracledb.enable_thin_mode()` as a means of enabling
+    python-oracledb Thin mode without waiting for an initial connection to be
+    succesfully established. Since python-oracledb defaults to Thin mode, this
+    method is mostly useful for applications with multiple threads concurrently
+    creating connections to different databases when the application starts
+    (`issue 408 <https://github.com/oracle/python-oracledb/issues/408>`__).
 #)  Fixed bug when calling :meth:`Connection.gettype()` for a type that exists
     but on which the user has insufficient privileges to view
     (`issue 397 <https://github.com/oracle/python-oracledb/issues/397>`__).

doc/src/user_guide/initialization.rst

@@ -307,6 +307,59 @@ On Linux and macOS, you might use::
 When your python-oracledb application is run, logging output is shown on the
 terminal.
 
+.. _enablingthin:
+
+Explicitly Enabling python-oracledb Thin Mode
+=============================================
+
+Python-oracledb defaults to Thin mode after determining that Thick mode is not
+going to be used.  In one special case, you may wish to explicitly enable Thin
+mode to prevent Thick mode from being enabled later.
+
+To allow application portability, the driver's internal logic allows
+applications to initally attempt
+:ref:`standalone connection <standaloneconnection>` creation in Thin mode, but
+then lets them :ref:`enable Thick mode <enablingthick>` if that connection is
+unsuccessful.  An example is when trying to connect to an Oracle Database that
+turns out to be an old version that requires Thick mode.  This heuristic means
+Thin mode is not enforced until the initial connection is successful.  Since
+all connections must be the same mode, any second and subsequent concurrent
+Thin mode connection attempts will wait for the initial standalone connection
+to succeed, meaning the driver mode is no longer potentially changeable to
+Thick mode.
+
+This heuristic delay does not impact:
+
+- Single-threaded applications using standalone connections.
+- Single or multi-threaded applications using
+  :ref:`connection pools <connpooling>` (even with ``min`` of 0).
+- Applications that have already called :func:`oracledb.init_oracle_client()`.
+
+In the case that you want to open multiple standalone Thin mode connections in
+multiple threads, you may wish to force Thin mode by calling
+:meth:`oracledb.enable_thin_mode()` as part of your application initialization.
+This avoids the mode heuristic delay. For example:
+
+.. code-block:: python
+
+    import oracledb
+
+    oracledb.enable_thin_mode()
+
+Once this method is called, then python-oracledb Thick mode cannot be enabled.
+If you call :func:`oracledb.init_oracle_client()`, you will get the following
+error::
+
+    DPY-2019: python-oracledb thick mode cannot be used because thin mode has
+    already been enabled or a thin mode connection has already been created
+
+If you have already enabled Thick mode by calling
+:func:`oracledb.init_oracle_client()` and then call
+:meth:`oracledb.enable_thin_mode()`, you will get the following error::
+
+    DPY-2053: python-oracledb thin mode cannot be used because thick mode has
+    already been enabled
+
 .. _optconfigfiles:
 
 Optional Oracle Configuration Files

src/oracledb/__init__.py

@@ -284,7 +284,10 @@
 
 from .driver_mode import is_thin_mode as is_thin_mode
 
-from .utils import register_protocol as register_protocol
+from .utils import (
+    enable_thin_mode as enable_thin_mode,
+    register_protocol as register_protocol,
+)
 
 from .thick_impl import (
     clientversion as clientversion,

src/oracledb/driver_mode.py

@@ -96,12 +96,6 @@ def get_manager(requested_thin_mode=None):
     """
     Returns the manager, but only after ensuring that no other threads are
     attempting to initialize the mode.
-
-    NOTE: the current implementation of the driver only requires
-    requested_thin_mode to be set when initializing the thick mode; for this
-    reason the error raised is specified about a thin mode connection already
-    being created. If this assumption changes, a new error message will be
-    required.
     """
     with manager.condition:
         if manager.thin_mode is None:
@@ -116,7 +110,10 @@ def get_manager(requested_thin_mode=None):
             requested_thin_mode is not None
             and requested_thin_mode != manager.thin_mode
         ):
-            errors._raise_err(errors.ERR_THIN_CONNECTION_ALREADY_CREATED)
+            if requested_thin_mode:
+                errors._raise_err(errors.ERR_THICK_MODE_ENABLED)
+            else:
+                errors._raise_err(errors.ERR_THIN_CONNECTION_ALREADY_CREATED)
     return manager
 
 

src/oracledb/errors.py

@@ -272,6 +272,7 @@ def _raise_not_supported(feature: str) -> None:
 ERR_INVALID_TPC_BEGIN_FLAGS = 2050
 ERR_INVALID_TPC_END_FLAGS = 2051
 ERR_MISMATCHED_TOKEN = 2052
+ERR_THICK_MODE_ENABLED = 2053
 
 # error numbers that result in NotSupportedError
 ERR_TIME_NOT_SUPPORTED = 3000
@@ -709,9 +710,14 @@ def _raise_not_supported(feature: str) -> None:
         "by python-oracledb in thin mode"
     ),
     ERR_TDS_TYPE_NOT_SUPPORTED: "Oracle TDS data type {num} is not supported",
+    ERR_THICK_MODE_ENABLED: (
+        "python-oracledb thin mode cannot be used because thick mode has "
+        "already been enabled"
+    ),
     ERR_THIN_CONNECTION_ALREADY_CREATED: (
-        "python-oracledb thick mode cannot be used because a thin mode "
-        "connection has already been created"
+        "python-oracledb thick mode cannot be used because thin mode has "
+        "already been enabled or a thin mode connection has already been "
+        "created"
     ),
     ERR_TIME_NOT_SUPPORTED: (
         "Oracle Database does not support time only variables"

src/oracledb/utils.py

@@ -31,9 +31,28 @@
 from typing import Callable, Union
 
 from . import base_impl
+from . import driver_mode
 from . import errors
 
 
+def enable_thin_mode():
+    """
+    Makes python-oracledb be in Thin mode. After this method is called, Thick
+    mode cannot be enabled. If python-oracledb is already in Thick mode, then
+    calling ``enable_thin_mode()`` will fail. If connections have already been
+    opened, or a connection pool created, in Thin mode, then calling
+    ``enable_thin_mode()`` is a no-op.
+
+    Since python-oracledb defaults to Thin mode, almost all applications do not
+    need to call this method. However, because it bypasses python-oracledb's
+    internal mode-determination heuristic, it may be useful for applications
+    that are using standalone connections in multiple threads to concurrently
+    create connections when the application starts.
+    """
+    with driver_mode.get_manager(requested_thin_mode=True):
+        pass
+
+
 def params_initer(f):
     """
     Decorator function which is used on the ConnectParams and PoolParams