Added support for configuring the SDU used for sizing internal buffers.

Author: anthony-tuininga

doc/src/api_manual/connect_param.rst

@@ -51,7 +51,7 @@ ConnectParams Methods
         externalauth=None, mode=None, disable_oob=None, stmtcachesize=None, \
         edition=None, tag=None, matchanytag=None, config_dir=None, \
         appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-        connection_id_prefix=None, ssl_context=None, handle=None)
+        connection_id_prefix=None, ssl_context=None, sdu=None, handle=None)
 
     Sets the default values for one or more of the parameters of an empty
     ConnectParams object.  A default will be overriden when a connection string
@@ -248,6 +248,22 @@ ConnectParams Attributes
 
     This attribute is supported in the python-oracledb Thin and Thick modes.
 
+.. attribute:: ConnectParams.sdu
+
+    This read-only attribute is an integer that returns the requested size of
+    the Session Data Unit (SDU), in bytes. The value tunes internal buffers
+    used for communication to the database. Bigger values can increase
+    throughput for large queries or bulk data loads, but at the cost of higher
+    memory use. The SDU size that will actually be used is negotiated down to
+    the lower of this value and the database network SDU configuration value.
+    See the `SQL*Net documentation
+    <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
+    id=GUID-86D61D6F-AD26-421A-BABA-77949C8A2B04>`__ for more details.
+
+    This attribute is supported in the python-oracledb Thin and Thick modes.
+
+    .. versionadded:: 2.0.0
+
 .. attribute:: ConnectParams.server_type
 
     This read-only attribute is a string that returns the type of server

doc/src/api_manual/module.rst

@@ -48,7 +48,7 @@ Oracledb Methods
         edition=None, tag=None, matchanytag=False, \
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-        connection_id_prefix=None, ssl_context=None, handle=0)
+        connection_id_prefix=None, ssl_context=None, sdu=8192, handle=0)
 
     Constructor for creating a connection to the database. Returns a
     :ref:`Connection Object <connobj>`. All parameters are optional and can be
@@ -303,6 +303,17 @@ Oracledb Methods
     the default SSLContext object cannot be used.  This value is only used in
     the python-oracledb Thin mode.
 
+    The ``sdu`` parameter is expected to be an integer that returns the
+    requested size of the Session Data Unit (SDU), in bytes. The value tunes
+    internal buffers used for communication to the database. Bigger values can
+    increase throughput for large queries or bulk data loads, but at the cost
+    of higher memory use. The SDU size that will actually be used is
+    negotiated down to the lower of this value and the database network SDU
+    configuration value. See the `SQL*Net documentation <https://www.oracle.
+    com/pls/topic/lookup?ctx=dblatest&id=GUID-86D61D6F-AD26-421A-BABA-
+    77949C8A2B04>`__ for more details. This value is used in both the
+    python-oracledb Thin and Thick modes. The default value is 8192 bytes.
+
     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
@@ -312,7 +323,7 @@ Oracledb Methods
 
     .. versionchanged:: 2.0.0
 
-        The ``ssl_context`` parameter was added.
+        The ``ssl_context`` and ``sdu`` parameters were added.
 
 .. function:: ConnectParams(user=None, proxy_user=None, password=None, \
         newpassword=None, wallet_password=None, access_token=None, host=None, \
@@ -326,7 +337,7 @@ Oracledb Methods
         edition=None, tag=None, matchanytag=False, \
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-        connection_id_prefix=None, ssl_context=None, handle=0)
+        connection_id_prefix=None, ssl_context=None, sdu=8192, handle=0)
 
     Contains all the parameters that can be used to establish a connection to
     the database.
@@ -546,14 +557,25 @@ Oracledb Methods
     the default SSLContext object cannot be used.  This value is only used in
     the python-oracledb Thin mode.
 
+    The ``sdu`` parameter is expected to be an integer that returns the
+    requested size of the Session Data Unit (SDU), in bytes. The value tunes
+    internal buffers used for communication to the database. Bigger values can
+    increase throughput for large queries or bulk data loads, but at the cost
+    of higher memory use. The SDU size that will actually be used is
+    negotiated down to the lower of this value and the database network SDU
+    configuration value. See the `SQL*Net documentation <https://www.oracle.
+    com/pls/topic/lookup?ctx=dblatest&id=GUID-86D61D6F-AD26-421A-BABA-
+    77949C8A2B04>`__ for more details. This value is used in both the
+    python-oracledb Thin and Thick modes. The default value is 8192 bytes.
+
     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:: 2.0.0
 
-        The ``ssl_context`` parameter was added.
+        The ``ssl_context`` and ``sdu`` parameters were added.
 
 .. function:: create_pool(dsn=None, pool_class=oracledb.ConnectionPool, \
         params=None, min=1, max=2, increment=1, \
@@ -573,7 +595,7 @@ Oracledb Methods
         edition=None, tag=None, matchanytag=False, \
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-        connection_id_prefix=None, ssl_context=None, handle=0)
+        connection_id_prefix=None, ssl_context=None, sdu=8192, handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`ConnectionPool object <connpool>` for the pool.  See :ref:`Connection
@@ -875,24 +897,35 @@ Oracledb Methods
     the default SSLContext object cannot be used.  This value is only used in
     the python-oracledb Thin mode.
 
+    The ``sdu`` parameter is expected to be an integer that returns the
+    requested size of the Session Data Unit (SDU), in bytes. The value tunes
+    internal buffers used for communication to the database. Bigger values can
+    increase throughput for large queries or bulk data loads, but at the cost
+    of higher memory use. The SDU size that will actually be used is
+    negotiated down to the lower of this value and the database network SDU
+    configuration value. See the `SQL*Net documentation <https://www.oracle.
+    com/pls/topic/lookup?ctx=dblatest&id=GUID-86D61D6F-AD26-421A-BABA-
+    77949C8A2B04>`__ for more details. This value is used in both the
+    python-oracledb Thin and Thick modes. The default value is 8192 bytes.
+
     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
     created should *never* be used after the source handle has been closed or
     destroyed. This value is only used in the python-oracledb Thick mode. It
     should be used with extreme caution. The default value is 0.
 
-    .. versionchanged:: 2.0.0
-
-        The ``ssl_context`` parameter was added.
-
     In the python-oracledb Thick mode, connection pooling is handled by
     Oracle's `Session pooling <https://www.oracle.com/pls/topic/lookup?
     ctx=dblatest&id=GUID-F9662FFB-EAEF-495C-96FC-49C6D1D9625C>`__ technology.
     This allows python-oracledb applications to support features like
     `Application Continuity <https://www.oracle.com/pls/topic/lookup?
     ctx=dblatest&id=GUID-A8DD9422-2F82-42A9-9555-134296416E8F>`__.
 
+    .. versionchanged:: 2.0.0
+
+        The ``ssl_context`` and ``sdu`` parameters were added.
+
 
 .. function:: Cursor(connection)
 
@@ -1014,7 +1047,7 @@ Oracledb Methods
         edition=None, tag=None, matchanytag=False, \
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-        connection_id_prefix=None, ssl_context=None, handle=0)
+        connection_id_prefix=None, ssl_context=None, sdu=8192, handle=0)
 
     Creates and returns a :ref:`PoolParams Object <poolparam>`. The object
     can be passed to :meth:`oracledb.create_pool()`.
@@ -1286,14 +1319,25 @@ Oracledb Methods
     the default SSLContext object cannot be used.  This value is only used in
     the python-oracledb Thin mode.
 
+    The ``sdu`` parameter is expected to be an integer that returns the
+    requested size of the Session Data Unit (SDU), in bytes. The value tunes
+    internal buffers used for communication to the database. Bigger values can
+    increase throughput for large queries or bulk data loads, but at the cost
+    of higher memory use. The SDU size that will actually be used is
+    negotiated down to the lower of this value and the database network SDU
+    configuration value. See the `SQL*Net documentation <https://www.oracle.
+    com/pls/topic/lookup?ctx=dblatest&id=GUID-86D61D6F-AD26-421A-BABA-
+    77949C8A2B04>`__ for more details. This value is used in both the
+    python-oracledb Thin and Thick modes. The default value is 8192 bytes.
+
     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:: 2.0.0
 
-        The ``ssl_context`` parameter was added.
+        The ``ssl_context`` and ``sdu`` parameters were added.
 
 .. function:: Time(hour, minute, second)
 

doc/src/api_manual/pool_params.rst

@@ -46,7 +46,7 @@ PoolParams Methods
         externalauth=None, mode=None, disable_oob=None, stmtcachesize=None, \
         edition=None, tag=None, matchanytag=None, config_dir=None, \
         appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-        connection_id_prefix=None, ssl_context=None, handle=None)
+        connection_id_prefix=None, ssl_context=None, sdu=None, handle=None)
 
   Sets one or more of the parameters.
 

doc/src/release_notes.rst

@@ -17,6 +17,9 @@ Thin Mode Changes
     names with more than 255 UTF-8 encoded bytes.
 #)  Added support for an Oracle Database 23c JSON feature improving JSON
     storage usage.
+#)  Added parameter :attr:`ConnectParams.sdu` for configuring the Session Data
+    Unit (SDU) size for sizing internal buffers used for tuning communication
+    with the database.
 #)  Fixed bug in detecting the current time zone
     (`issue 257 <https://github.com/oracle/python-oracledb/issues/257>`__).
 #)  Added connection establishment parameter :data:`ConnectParams.ssl_context`

doc/src/user_guide/appendix_b.rst

@@ -164,11 +164,6 @@ attributes.
 The ``ENABLE=BROKEN`` connect descriptor option is not supported in
 python-oracledb Thin mode.  Use ``expire_time`` instead.
 
-The ``Session Data Unit (SDU)`` connect descriptor option that is used to tune
-network transfers is not supported in python-oracledb Thin mode. The value is
-hard-coded as 8 KB.  In python-oracledb Thick mode, the SDU connect descriptor
-option and equivalent ``sqlnet.ora`` setting are used.
-
 If a name is given as a connect string, then the python-oracledb Thin mode will
 consider it as a Net Service Name and not as the minimal Easy Connect string of
 a hostname.  The given connect string will be looked up in a ``tnsnames.ora``

doc/src/user_guide/tuning.rst

@@ -46,11 +46,20 @@ Some general tuning tips are:
 
 * Tune your network.  For example, when inserting or retrieving a large number
   of rows (or for large data), or when using a slow network, then tune the
-  Oracle Network Session Data Unit (SDU) and socket buffer sizes, see `Oracle
-  Net Services: Best Practices for Database Performance and High Availability
+  Oracle Network Session Data Unit (SDU) and socket buffer sizes, see
+  `Configuring Session Data Unit
+  <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-86D61D6F-AD26-421A-BABA-77949C8A2B04>`__
+  and `Oracle Net Services: Best Practices for Database Performance and High
+  Availability
   <https://static.rainfocus.com/oracle/oow19/sess/1553616880266001WLIh/PF/
   OOW19_Net_CON4641_1569022126580001esUl.pdf>`__.
 
+  In python-oracledb Thick mode the SDU size is configured in the
+  :ref:`optnetfiles`. In python-oracledb Thin mode, the SDU size can be passed
+  as a connection or pool creation parameter.  In both modes it may optionally
+  be set in the connection :ref:`Easy Connect string <easyconnect>` or
+  :ref:`connect descriptor <netservice>`.
+
 * Do not commit or rollback unnecessarily.  Use :attr:`Connection.autocommit`
   on the last of a sequence of DML statements.
 

src/oracledb/base_impl.pxd

@@ -134,6 +134,7 @@ cdef class Description(ConnectParamsNode):
         public uint32_t expire_time
         public uint32_t retry_count
         public uint32_t retry_delay
+        public uint32_t sdu
         public double tcp_connect_timeout
         public str service_name
         public str server_type

src/oracledb/connect_params.py

@@ -93,6 +93,7 @@ def __init__(
         debug_jdwp: str = None,
         connection_id_prefix: str = None,
         ssl_context: Any = None,
+        sdu: int = 8192,
         handle: int = 0,
         threaded: bool = True,
         encoding: str = None,
@@ -250,6 +251,13 @@ def __init__(
           parameter should only be specified if the default SSLContext object
           cannot be used (default: None)
 
+        - sdu: the requested size of the Session Data Unit (SDU), in bytes. The
+          value tunes internal buffers used for communication to the database.
+          Bigger values can increase throughput for large queries or bulk data
+          loads, but at the cost of higher memory use. The SDU size that will
+          actually be used is negotiated down to the lower of this value and
+          the database network SDU configuration value (default: 8192)
+
         - 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)
@@ -293,7 +301,8 @@ def __repr__(self):
             + f"supershardingkey={self.supershardingkey!r}, "
             + f"debug_jdwp={self.debug_jdwp!r}, "
             + f"connection_id_prefix={self.connection_id_prefix!r}, "
-            + f"ssl_context={self.ssl_context!r}"
+            + f"ssl_context={self.ssl_context!r}, "
+            + f"sdu={self.sdu!r}"
             + ")"
         )
 
@@ -506,6 +515,19 @@ def retry_delay(self) -> Union[list, int]:
         """
         return self._impl.retry_delay
 
+    @property
+    @_description_attr
+    def sdu(self) -> Union[list, int]:
+        """
+        The requested size of the Session Data Unit (SDU), in bytes. The value
+        tunes internal buffers used for communication to the database. Bigger
+        values can increase throughput for large queries or bulk data loads,
+        but at the cost of higher memory use. The SDU size that will actually
+        be used is negotiated down to the lower of this value and the database
+        network SDU configuration value.
+        """
+        return self._impl.sdu
+
     @property
     @_description_attr
     def server_type(self) -> Union[list, str]:
@@ -699,6 +721,7 @@ def set(
         debug_jdwp: str = None,
         connection_id_prefix: str = None,
         ssl_context: Any = None,
+        sdu: int = None,
         handle: int = None,
         threaded: bool = None,
         encoding: str = None,
@@ -847,6 +870,13 @@ def set(
           parameter should only be specified if the default SSLContext object
           cannot be used
 
+        - sdu: the requested size of the Session Data Unit (SDU), in bytes. The
+          value tunes internal buffers used for communication to the database.
+          Bigger values can increase throughput for large queries or bulk data
+          loads, but at the cost of higher memory use. The SDU size that will
+          actually be used is negotiated down to the lower of this value and
+          the database network SDU configuration value
+
         - 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

@@ -1178,6 +1178,7 @@ def connect(
     debug_jdwp: str = None,
     connection_id_prefix: str = None,
     ssl_context: Any = None,
+    sdu: int = 8192,
     handle: int = 0,
     threaded: bool = True,
     encoding: str = None,
@@ -1356,6 +1357,13 @@ def connect(
       should only be specified if the default SSLContext object cannot be used
       (default: None)
 
+    - sdu: the requested size of the Session Data Unit (SDU), in bytes. The
+      value tunes internal buffers used for communication to the database.
+      Bigger values can increase throughput for large queries or bulk data
+      loads, but at the cost of higher memory use. The SDU size that will
+      actually be used is negotiated down to the lower of this value and the
+      database network SDU configuration value (default: 8192)
+
     - 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/impl/base/connect_params.pyx

@@ -65,6 +65,7 @@ _tnsnames_files = {}
 cdef str DEFAULT_PROTOCOL = "tcp"
 cdef uint32_t DEFAULT_PORT = 1521
 cdef double DEFAULT_TCP_CONNECT_TIMEOUT = 60
+cdef uint32_t DEFAULT_SDU = 8192
 
 
 cdef int _add_container(dict args, str name, object value) except -1:
@@ -790,6 +791,7 @@ cdef class Description(ConnectParamsNode):
         ConnectParamsNode.__init__(self, True)
         self.tcp_connect_timeout = DEFAULT_TCP_CONNECT_TIMEOUT
         self.ssl_server_dn_match = True
+        self.sdu = DEFAULT_SDU
 
     cdef str _build_duration_str(self, double value):
         """
@@ -830,6 +832,8 @@ cdef class Description(ConnectParamsNode):
         if self.tcp_connect_timeout != DEFAULT_TCP_CONNECT_TIMEOUT:
             temp = self._build_duration_str(self.tcp_connect_timeout)
             parts.append(f"(TRANSPORT_CONNECT_TIMEOUT={temp})")
+        if self.sdu != DEFAULT_SDU:
+            parts.append(f"(SDU={self.sdu})")
 
         # add address lists, but if the address list contains only a single
         # entry and that entry does not have a host, the other parts aren't
@@ -894,6 +898,7 @@ cdef class Description(ConnectParamsNode):
         description.source_route = self.source_route
         description.retry_count = self.retry_count
         description.retry_delay = self.retry_delay
+        description.sdu = self.sdu
         description.tcp_connect_timeout = self.tcp_connect_timeout
         description.ssl_server_dn_match = self.ssl_server_dn_match
         description.ssl_server_cert_dn = self.ssl_server_cert_dn
@@ -925,6 +930,8 @@ cdef class Description(ConnectParamsNode):
         _set_bool_param(args, "source_route", &self.source_route)
         _set_uint_param(args, "retry_count", &self.retry_count)
         _set_uint_param(args, "retry_delay", &self.retry_delay)
+        _set_uint_param(args, "sdu", &self.sdu)
+        self.sdu = min(max(self.sdu, 512), 2097152)         # sanitize SDU
         _set_duration_param(args, "tcp_connect_timeout",
                             &self.tcp_connect_timeout)