Prepare for 6.9 release with documentation and test updates

Author: sharadraju

doc/src/api_manual/connection.rst

@@ -447,6 +447,105 @@ The properties of a *Connection* object are listed below.
 Connection Methods
 ==================
 
+.. method:: connection.beginSessionlessTransaction()
+
+    .. versionadded:: 6.9
+
+    **Promise**::
+
+        promise = beginSessionlessTransaction(Object options);
+
+    Begins a new sessionless transaction using the specified transaction
+    identifier. This method returns the transaction identifier specified by
+    the user or generated by node-oracledb as a Buffer value.
+
+    See :ref:`sessionlesstxns` for more information.
+
+    The parameters of the ``connection.beginSessionlessTransaction()`` method are:
+
+    .. _beginsessionlesstxn:
+
+    .. list-table-with-summary:: connection.beginSessionlessTransaction() Parameters
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 30
+        :summary: The first column displays the name of the parameter. The
+         second column displays the data type of the parameter. The third
+         column displays the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``options``
+          - Object
+          - This is an optional parameter to ``beginSessionlessTransaction()``
+            that may be used to start a sessionless transaction. See
+            :ref:`beginSessionlessTransaction() options Parameter Properties
+            <begintxnoptionsparams>` for detailed information on its
+            properties.
+
+    **beginSessionlessTransaction(): Options Parameter Properties**
+
+    The properties of the ``options`` parameter are:
+
+    .. _begintxnoptionsparams:
+
+    .. list-table-with-summary:: beginSessionlessTransaction(): ``options`` Parameter Properties
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 30
+        :summary: The first column displays the name of the parameter. The
+         second column displays the data type of the parameter. The third
+         column displays the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``transactionId``
+          - String or Buffer
+          - A unique identifier for the sessionless transaction.
+
+            If the value is *undefined*, that is, no value is specified, node-oracledb generates a random `universally-unique identifier (UUID) <https://www.rfc-editor.org/rfc/rfc4122.txt>`__ value when :meth:`connection.beginSessionlessTransaction()` is called. An example is "36b8f84d-df4e-4d49-b662-bcde71a8764f". The user-chosen value cannot exceed 64 bytes in length.
+        * - ``timeout``
+          - Number
+          - The number of seconds before which this transaction can be resumed by a connection the next time that it is suspended.
+
+            If a transaction is not resumed within this specified duration, the transaction will be rolled back.
+
+            The default value is *60* seconds.
+        * - ``deferRoundTrip``
+          - Boolean
+          - Determines whether the request to start a transaction is to be sent immediately or with the next database operation.
+
+            When this property is set to *false*, the request to start a transaction is sent immediately. If set to *true*, the request is included with the next database operation on the connection.
+
+            The default value is *false*.
+
+    **Callback**:
+
+    If you are using the callback programming style::
+
+        beginSessionlessTransaction(Object options, function(Error error){});
+
+    See :ref:`beginsessionlesstxn` for information on the ``options`` parameter.
+
+    The parameters of the callback function ``function(Error error)`` are:
+
+    .. list-table-with-summary::
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 15 30
+        :summary: The first column displays the callback function parameter.
+         The second column displays the description of the parameter.
+
+        * - Callback Function Parameter
+          - Description
+        * - Error ``error``
+          - If ``beginSessionlessTransaction()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the :ref:`error message <errorobj>`.
+
 .. method:: connection.break()
 
     **Promise**::
@@ -1179,6 +1278,21 @@ Connection Methods
             Determines whether query results, :ref:`Implicit Results <implicitresults>`, and :ref:`nested cursors <nestedcursors>` should be returned as :ref:`ResultSet <resultsetclass>` objects or directly.
 
             The default is *false*.
+        * - ``suspendOnSuccess``
+          - Boolean
+          - .. _propexecsuspendonsuccess:
+
+            Determines whether an active sessionless transaction should be suspended when ``execute()`` completes successfully. This property is only applicable for sessionless transactions.
+
+            Setting this property to *true*, suspends an active sessionless transaction after successful execution of ``execute()``. If set to *false*, the sessionless transaction will not be suspended.
+
+            The default value is *false*.
+
+            When this property is used with transactions that are not sessionless, an error will be thrown.
+
+            See :ref:`sessionlesstxns`.
+
+            .. versionadded:: 6.9
 
     **Callback**:
 
@@ -1479,6 +1593,21 @@ Connection Methods
             .. versionadded:: 5.3
 
             In earlier versions, statements were always added to the statement cache, if caching was enabled.
+        * - ``suspendOnSuccess``
+          - Boolean
+          - .. _executemanyoptsuspendonsuccess:
+
+            Determines whether an active sessionless transaction should be suspended when ``executeMany()`` completes successfully. This property is only applicable for sessionless transactions.
+
+            Setting this property to *true*, suspends an active sessionless transaction after successful execution of ``executeMany()``. If set to *false*, the sessionless transaction will not be suspended.
+
+            The default value is *false*.
+
+            When this property is used with transactions that are not sessionless, an error will be thrown.
+
+            See :ref:`sessionlesstxns`.
+
+            .. versionadded:: 6.9
 
     **executeMany(): bindDefs Object Properties**
 
@@ -1992,6 +2121,107 @@ Connection Methods
 
     See :meth:`~connection.execute()`.
 
+.. method:: connection.resumeSessionlessTransaction()
+
+    .. versionadded:: 6.9
+
+    **Promise**::
+
+        promise = resumeSessionlessTransaction(Buffer transactionId, Objects options);
+
+    Resumes an existing sessionless transaction using the specified
+    transaction identifier. This method returns the transaction identifier
+    used to resume the sessionless transaction as a Buffer value.
+
+    See :ref:`sessionlesstxns`.
+
+    The parameters of the ``connection.resumeSessionlessTransaction()`` method are:
+
+    .. _resumesessionlesstxn:
+
+    .. list-table-with-summary:: connection.resumeSessionlessTransaction() Parameters
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 30
+        :summary: The first column displays the name of the parameter. The
+         second column displays the data type of the parameter. The third
+         column displays the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``transactionId``
+          - Buffer
+          - The unique identifier of an existing sessionless transaction that is to be resumed.
+        * - ``options``
+          - Object
+          - This is a parameter that may be used to resume a sessionless
+            transaction. See :ref:`resumeSessionlessTransaction() options
+            Parameter Properties <resumetxnoptionsparams>` for detailed
+            information on its properties.
+
+    .. _resumetxnoptionsparams:
+
+    .. list-table-with-summary:: resumeSessionlessTransaction(): ``options`` Parameter Properties
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 30
+        :summary: The first column displays the name of the parameter. The
+         second column displays the data type of the parameter. The third
+         column displays the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``timeout``
+          - Number
+          - The number of seconds that the current connection waits to resume a transaction if another connection is using it.
+
+            This timeout is only effective when the transaction is in use by another connection. In this case, the current connection waits for the transaction to be suspended within this timeout period.
+
+            When ``deferRoundTrip`` is set to *false*, the wait happens in the ``resumeSessionlessTransaction()`` call itself, and the function blocks until the transaction becomes available or the timeout expires. When ``deferRoundTrip`` is set to *true*, the resume is deferred and the wait occurs at the time of the next database operation instead.
+
+            At the start of the wait period, if the transaction is not in use by any other connection, the resume happens immediately.
+
+            If the transaction remains in use by the other connection after the timeout period, the error `ORA-25351 <https://docs.oracle.com/en/error-help/db/ora-25351>`__ is raised. If another connection completes the transaction, the error `ORA-24756 <https://docs.oracle.com/en/error-help/db/ora-24756>`__ is raised. These error messages are only thrown for non-RAC instances.
+
+            For information on using Oracle RAC, see :ref:`Sessionless Transactions with Oracle RAC <sessionlesstxnswithrac>`.
+
+            The default value is *60* seconds.
+        * - ``deferRoundTrip``
+          - Boolean
+          - Determines whether the request to resume a transaction is to be sent immediately or with the next database operation.
+
+            When this property is set to *false*, the request to resume a transaction is sent immediately. If set to *true*, the request is included with the next database operation on the connection.
+
+            The default value is *false*.
+
+    **Callback**:
+
+    If you are using the callback programming style::
+
+        resumeSessionlessTransaction(Object options, function(Error error){});
+
+    See :ref:`resumesessionlesstxn` for information on the ``options``
+    parameter.
+
+    The parameters of the callback function ``function(Error error)`` are:
+
+    .. list-table-with-summary::
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 15 30
+        :summary: The first column displays the callback function parameter.
+         The second column displays the description of the parameter.
+
+        * - Callback Function Parameter
+          - Description
+        * - Error ``error``
+          - If ``resumeSessionlessTransaction()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the :ref:`error message <errorobj>`.
+
 .. method:: connection.rollback()
 
     **Promise**::
@@ -2349,6 +2579,45 @@ Connection Methods
 
             .. versionadded:: 4.0
 
+.. method:: connection.suspendSessionlessTransaction()
+
+    .. versionadded:: 6.9
+
+    **Promise**::
+
+        promise = suspendSessionlessTransaction();
+
+    Suspends the currently active sessionless transaction immediately.
+
+    This detaches the transaction from the connection, allowing it to be
+    resumed later with the transaction identifier that was specified when
+    creating the sessionless transaction. Also, the timeout value defined in
+    :meth:`Connection.beginSessionlessTransaction()` comes into effect and
+    determines how long the transaction can stay suspended.
+
+    See :ref:`sessionlesstxns`.
+
+    **Callback**:
+
+    If you are using the callback programming style::
+
+        suspendSessionlessTransaction(function(Error error){});
+
+    The parameter of the callback function is:
+
+    .. list-table-with-summary::
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 15 30
+        :summary: The first column displays the callback function parameter.
+         The second column displays the description of the parameter.
+
+        * - Callback Function Parameter
+          - Description
+        * - Error ``error``
+          - If ``suspendSessionlessTransaction()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the :ref:`error message <errorobj>`.
+
 .. method:: connection.startup()
 
     .. versionadded:: 5.0

doc/src/api_manual/oracledb.rst

@@ -2809,7 +2809,7 @@ Oracledb Methods
 
             With Simple Authentication, the configuration parameters can be provided at runtime.
 
-            With Instance Principal Authentication, OCI compute instances can be authorized to access services on Oracle Cloud such as Oracle Autonomous Database. Node.js applications running on such a compute instance are automatically authenticated, eliminating the need to provide database user credentials. This authentication method will only work on compute instances where internal network endpoints are reachable. For more information on OCI compute instances, see `OCI Compute Instances <https://docs.oracle.com/en-us/iaas/compute-cloud-at-customer/topics/compute/compute-instances.htm>`__, `Creating a Compute Instance <https://docs.oracle.com/en-us/iaas/Content/Compute/Tasks/launchinginstance.htm>`__, and `Calling Services from a Compute Instance <https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm>`__.
+            With Instance Principal Authentication, OCI compute instances can be authorized to access services on Oracle Cloud such as Oracle Autonomous Database. Node-oracledb applications running on such a compute instance are automatically authenticated, eliminating the need to provide database user credentials. This authentication method will only work on compute instances where internal network endpoints are reachable. See :ref:`instanceprincipalauth` for more information.
 
             See `OCI SDK Authentication Methods <https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm>`__ for more information.
           - Required

doc/src/conf.py

@@ -46,8 +46,8 @@
 # from the other)
 #
 # The short X.Y version.
-version = '6.8'
-release = '6.8.0'
+version = '6.9'
+release = '6.9.0'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

doc/src/release_notes.rst

@@ -19,6 +19,9 @@ node-oracledb `v6.9.0 <https://github.com/oracle/node-oracledb/compare/v6.8.0...
 Common Changes
 ++++++++++++++
 
+#)  Added support for Oracle Database 23ai
+    :ref:`Sessionless Transactions <sessionlesstxns>`.
+
 #)  Added support for :ref:`Transaction Guard <tg>` with the introduction of
     the :attr:`~connection.ltxid` property.
 
@@ -40,6 +43,10 @@ Common Changes
     with external bundlers such as webpack and esbuild.
     See `Issue #1791 <https://github.com/oracle/node-oracledb/issues/1791>`__.
 
+#)  Added :meth:`oracledb.registerConfigurationProviderHook()` to register
+    :ref:`centralized configuration provider <configproviderplugins>`
+    extension modules.
+
 #)  Added support for
     :ref:`instance principal authentication <_create_pool_oci_properties>`
     in :ref:`native IAM token-based authentication <cloudnativeauthoci>`

doc/src/user_guide/appendix_a.rst

@@ -242,6 +242,9 @@ node-oracledb Thin and Thick modes. For more details see :ref:`modediff`.
     * - Feature tracking
       - No
       - Yes
+    * - Oracle Database 23ai Sessionless Transactions (see :ref:`sessionlesstxns`)
+      - Yes
+      - Yes
     * - Two-phase Commit (TPC) (see :ref:`twopc`)
       - Yes
       - Yes