Added support for getting the value of ltxid in thin mode.

Author: anthony-tuininga

doc/src/api_manual/async_connection.rst

@@ -523,8 +523,7 @@ AsyncConnection Attributes
 
     .. note:
 
-        This attribute is only available when Oracle Database 12.1 or later is
-        in use
+        This attribute is only available with Oracle Database 12.1 or later.
 
 .. attribute:: AsyncConnection.max_identifier_length
 

doc/src/api_manual/connection.rst

@@ -774,8 +774,8 @@ Connection Attributes
     .. note:
 
         This attribute is an extension to the DB API definition. It is only
-        available when Oracle Database 12.1 or higher is in use on both the
-        server and the client.
+        available with Oracle Database 12.1 or higher. In python-oracledb Thick
+        mode, it also requires Oracle Client libraries 12.1 or higer.
 
 .. attribute:: Connection.max_identifier_length
 

doc/src/release_notes.rst

@@ -33,6 +33,8 @@ Thin Mode Changes
 #)  The thread that closes connection pools on interpreter shutdown is now only
     started when the first pool is created and not at module import
     (`issue 426 <https://github.com/oracle/python-oracledb/issues/426>`__).
+#)  Added support for Transaction Guard by adding support to get the value of
+    :attr:`Connection.ltxid`.
 #)  Fixed hang when attempting to use pipelining against a database that
     doesn't support the end of response flag.
 #)  Fixed hang when using asyncio and a connection is unexpectedly closed by

doc/src/user_guide/appendix_a.rst

@@ -287,7 +287,7 @@ see :ref:`driverdiff` and :ref:`compatibility`.
       - Yes - no callback
       - Yes - no callback
     * - Transaction Guard (TG) (see :ref:`tg`)
-      - No
+      - Yes
       - Yes
       - Yes
     * - Data Guard (DG) and Active Data Guard (ADG)

doc/src/user_guide/ha.rst

@@ -161,13 +161,9 @@ Python-oracledb supports `Transaction Guard
 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
 id=GUID-A675AF7B-6FF0-460D-A6E6-C15E7C328C8F>`__ which enables Python
 application to verify the success or failure of the last transaction in the
-event of an unplanned outage. This feature is available when both client and
-database are 12.1 or higher.
-
-.. note::
-
-    The Transaction Guard feature is only supported in the python-oracledb
-    Thick mode.  See :ref:`enablingthick`.
+event of an unplanned outage. This feature requires Oracle Database 12.1 or
+higher. When using python-oracledb Thick mode, Oracle Client 12.1 or higher is
+additionally required.
 
 Using Transaction Guard helps to:
 
@@ -184,7 +180,10 @@ logical transaction id (``ltxid``) from the connection and then call a
 procedure to determine the outcome of the commit for this logical transaction
 id.
 
-Follow the steps below to use the Transaction Guard feature in Python:
+The steps below show how to use Transaction Guard in python-oracledb in a
+single-instance database. Refer to Oracle documentation if you are using `RAC
+<https://www.oracle.com/pls/ topic/lookup?ctx=dblatest&id=RACAD>`__ or standby
+databases.
 
 1.  Grant execute privileges to the database users who will be checking the
     outcome of the commit. Log in as SYSDBA and run the following command:
@@ -193,8 +192,9 @@ Follow the steps below to use the Transaction Guard feature in Python:
 
         GRANT EXECUTE ON DBMS_APP_CONT TO <username>;
 
-2.  Create a new service by executing the following PL/SQL block as SYSDBA.
-    Replace the ``<service-name>``, ``<network-name>`` and
+2.  Create a new service by calling `DBMS_SERVICE.CREATE_SERVICE
+    <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-386E183E-D83C-48A7-8BA3-40248CFB89F4>`__
+    as SYSDBA.  Replace the ``<service-name>``, ``<network-name>`` and
     ``<retention-value>`` values with suitable values. It is important that the
     ``COMMIT_OUTCOME`` parameter be set to true for Transaction Guard to
     function properly.
@@ -210,12 +210,14 @@ Follow the steps below to use the Transaction Guard feature in Python:
         END;
         /
 
-3.  Start the service by executing the following PL/SQL block as SYSDBA:
+3.  Start the service by calling `DBMS_SERVICE.START_SERVICE
+    <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-140B93AC-9021-4091-B797-7CA3AAB446FE>`__
+    as SYSDBA:
 
     .. code-block:: sql
 
         BEGIN
-            DBMS_SERVICE.start_service('<service-name>');
+            DBMS_SERVICE.START_SERVICE('<service-name>');
         END;
         /
 
@@ -231,12 +233,18 @@ query:
 
 In the Python application code:
 
-* Use the connection attribute :attr:`~Connection.ltxid` to determine the
+* Connect to the appropriately enabled database service. If the connection is
+  TAF, AC or TAC enabled, then do not proceed with TG.
+* Check :attr:`oracledb._Error.isrecoverable` to confirm the error is
+  recoverable. If not, do not proceed with TG.
+* Use the connection attribute :attr:`Connection.ltxid` to find the
   logical transaction id.
-* Call the ``DBMS_APP_CONT.GET_LTXID_OUTCOME`` PL/SQL procedure with the
-  logical transaction id acquired from the connection attribute.  This returns
-  a boolean value indicating if the last transaction was committed and whether
-  the last call was completed successfully or not.
+* Call the `DBMS_APP_CONT.GET_LTXID_OUTCOME
+  <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-03CEB530-D3A5-40B1-87C8-5BF1BB5D5D54>`__
+  PL/SQL procedure with the logical transaction id.  This returns a boolean
+  value indicating if the last transaction was committed and whether the last
+  call was completed successfully or not.
+* Take any necessary action to re-do uncommitted work.
 
 See the `Transaction Guard Sample
 <https://github.com/oracle/python-oracledb/blob/main/

samples/transaction_guard.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2016, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2016, 2025, Oracle and/or its affiliates.
 #
 # Portions Copyright 2007-2015, Anthony Tuininga. All rights reserved.
 #
@@ -57,8 +57,9 @@
 import oracledb
 import sample_env
 
-# this script is currently only supported in python-oracledb thick mode
-oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client())
+# determine whether to use python-oracledb thin mode or thick mode
+if not sample_env.get_is_thin():
+    oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client())
 
 # constants
 CONNECT_STRING = "localhost/orcl-tg"

src/oracledb/impl/thin/capabilities.pyx

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2021, 2024, Oracle and/or its affiliates.
+# Copyright (c) 2021, 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
@@ -121,7 +121,8 @@ cdef class Capabilities:
         self.compile_caps[TNS_CCAP_LOB2] = TNS_CCAP_LOB2_QUASI | \
                 TNS_CCAP_LOB2_2GB_PREFETCH
         self.compile_caps[TNS_CCAP_TTC3] = TNS_CCAP_IMPLICIT_RESULTS | \
-                TNS_CCAP_BIG_CHUNK_CLR | TNS_CCAP_KEEP_OUT_ORDER
+                TNS_CCAP_BIG_CHUNK_CLR | TNS_CCAP_KEEP_OUT_ORDER | \
+                TNS_CCAP_LTXID
         self.compile_caps[TNS_CCAP_TTC2] = TNS_CCAP_ZLNP
         self.compile_caps[TNS_CCAP_OCI2] = TNS_CCAP_DRCP
         self.compile_caps[TNS_CCAP_CLIENT_FN] = TNS_CCAP_CLIENT_FN_MAX

src/oracledb/impl/thin/constants.pxi

@@ -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
@@ -384,6 +384,7 @@ cdef enum:
     TNS_CCAP_RPC_VERSION_MAX = 7
     TNS_CCAP_RPC_SIG_VALUE = 3
     TNS_CCAP_DBF_VERSION_MAX = 1
+    TNS_CCAP_LTXID = 0x08
     TNS_CCAP_IMPLICIT_RESULTS = 0x10
     TNS_CCAP_BIG_CHUNK_CLR = 0x20
     TNS_CCAP_KEEP_OUT_ORDER = 0x80

src/oracledb/impl/thin/messages.pyx

@@ -229,7 +229,7 @@ cdef class Message:
         if opcode == TNS_SERVER_PIGGYBACK_LTXID:
             buf.read_ub4(&num_bytes)
             if num_bytes > 0:
-                buf.skip_raw_bytes(num_bytes)
+                self.conn_impl._ltxid = buf.read_bytes()
         elif opcode == TNS_SERVER_PIGGYBACK_QUERY_CACHE_INVALIDATION \
                 or opcode == TNS_SERVER_PIGGYBACK_TRACE_EVENT:
             pass

tests/ext/test_ext_2300_tg.py

@@ -0,0 +1,152 @@
+# -----------------------------------------------------------------------------
+# Copyright (c) 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
+# 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+# either license.
+#
+# If you elect to accept the software under the Apache License, Version 2.0,
+# the following applies:
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# -----------------------------------------------------------------------------
+
+"""
+E2300 - Module for testing Transaction Guard (TG). No special setup is required
+but the test suite makes use of debugging packages that are not intended for
+normal use. It also creates and drops a service.
+"""
+
+import oracledb
+import test_env
+
+
+class TestCase(test_env.BaseTestCase):
+    service_name = "oracledb-test-tg"
+    requires_connection = False
+
+    @classmethod
+    def setUpClass(cls):
+        cls.admin_conn = test_env.get_admin_connection()
+        user = test_env.get_main_user()
+        with cls.admin_conn.cursor() as cursor:
+            cursor.execute(
+                f"""
+                declare
+                    params          dbms_service.svc_parameter_array;
+                begin
+                    params('COMMIT_OUTCOME') := 'true';
+                    params('RETENTION_TIMEOUT') := 604800;
+                    dbms_service.create_service('{cls.service_name}',
+                                                '{cls.service_name}', params);
+                    dbms_service.start_service('{cls.service_name}');
+                end;
+                """
+            )
+            cursor.execute(f"grant execute on dbms_tg_dbg to {user}")
+            cursor.execute(f"grant execute on dbms_app_cont to {user}")
+
+    @classmethod
+    def tearDownClass(cls):
+        user = test_env.get_main_user()
+        with cls.admin_conn.cursor() as cursor:
+            cursor.execute(f"revoke execute on dbms_tg_dbg from {user}")
+            cursor.execute(f"revoke execute on dbms_app_cont from {user}")
+            cursor.callproc("dbms_service.stop_service", [cls.service_name])
+            cursor.callproc("dbms_service.delete_service", [cls.service_name])
+
+    def test_ext_2300(self):
+        "E2300 - test standalone connection"
+        params = test_env.get_connect_params().copy()
+        params.parse_connect_string(test_env.get_connect_string())
+        params.set(service_name=self.service_name)
+        for arg_name in ("pre_commit", "post_commit"):
+            with self.subTest(arg_name=arg_name):
+                conn = oracledb.connect(params=params)
+                cursor = conn.cursor()
+                cursor.execute("truncate table TestTempTable")
+                cursor.execute(
+                    """
+                    insert into TestTempTable (IntCol, StringCol1)
+                    values (:1, :2)
+                    """,
+                    [2300, "String for test 2300"],
+                )
+                full_arg_name = f"dbms_tg_dbg.tg_failpoint_{arg_name}"
+                cursor.execute(
+                    f"""
+                    begin
+                        dbms_tg_dbg.set_failpoint({full_arg_name});
+                    end;
+                    """
+                )
+                ltxid = conn.ltxid
+                with self.assertRaisesFullCode("DPY-4011"):
+                    conn.commit()
+                conn = oracledb.connect(params=params)
+                cursor = conn.cursor()
+                committed_var = cursor.var(bool)
+                completed_var = cursor.var(bool)
+                cursor.callproc(
+                    "dbms_app_cont.get_ltxid_outcome",
+                    [ltxid, committed_var, completed_var],
+                )
+                expected_value = arg_name == "post_commit"
+                self.assertEqual(committed_var.getvalue(), expected_value)
+                self.assertEqual(completed_var.getvalue(), expected_value)
+
+    def test_ext_2301(self):
+        "E2301 - test pooled connection"
+        params = test_env.get_pool_params().copy()
+        params.parse_connect_string(test_env.get_connect_string())
+        params.set(service_name=self.service_name, max=10)
+        pool = oracledb.create_pool(params=params)
+        for arg_name in ("pre_commit", "post_commit"):
+            with self.subTest(arg_name=arg_name):
+                conn = pool.acquire()
+                cursor = conn.cursor()
+                cursor.execute("truncate table TestTempTable")
+                cursor.execute(
+                    """
+                    insert into TestTempTable (IntCol, StringCol1)
+                    values (:1, :2)
+                    """,
+                    [2300, "String for test 2300"],
+                )
+                full_arg_name = f"dbms_tg_dbg.tg_failpoint_{arg_name}"
+                cursor.execute(
+                    f"""
+                    begin
+                        dbms_tg_dbg.set_failpoint({full_arg_name});
+                    end;
+                    """
+                )
+                ltxid = conn.ltxid
+                with self.assertRaisesFullCode("DPY-4011"):
+                    conn.commit()
+                conn = pool.acquire()
+                cursor = conn.cursor()
+                committed_var = cursor.var(bool)
+                completed_var = cursor.var(bool)
+                cursor.callproc(
+                    "dbms_app_cont.get_ltxid_outcome",
+                    [ltxid, committed_var, completed_var],
+                )
+                expected_value = arg_name == "post_commit"
+                self.assertEqual(committed_var.getvalue(), expected_value)
+                self.assertEqual(completed_var.getvalue(), expected_value)
+
+
+if __name__ == "__main__":
+    test_env.run_test_cases()