Fixed bug that caused oracledb._Error.isrecoverable to always be False.

Author: anthony-tuininga

doc/src/api_manual/module.rst

@@ -4295,8 +4295,10 @@ See :ref:`exception` for usage information.
 .. attribute:: _Error.isrecoverable
 
     Boolean attribute representing whether the error is recoverable or not.
-    This is False in all cases unless both Oracle Database 12.1 (or later) and
-    Oracle Client 12.1 (or later) are being used.
+    This requires Oracle Database 12.1 (or later). If python-oracledb Thick
+    mode is used, then Oracle Client 12.1 (or later) is also required.
+
+    See :ref:`tg` for more information.
 
 .. _oracledbplugins:
 

doc/src/release_notes.rst

@@ -33,8 +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`.
+#)  Added support for Transaction Guard by adding support to get the values of
+    :attr:`Connection.ltxid` and :attr:`oracledb._Error.isrecoverable`.
 #)  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
@@ -66,6 +66,9 @@ Thin Mode Changes
 Thick Mode Changes
 ++++++++++++++++++
 
+#)  Fixed bug that caused :attr:`oracledb._Error.isrecoverable` to always be
+    `False`.
+
 Common Changes
 ++++++++++++++
 

src/oracledb/impl/thin/messages.pyx

@@ -65,10 +65,39 @@ cdef class Message:
         connection" error is detected, the connection is forced closed
         immediately.
         """
+        cdef bint is_recoverable = False
         if self.error_occurred:
+            if self.error_info.num in (
+                28,     # session has been terminated
+                31,     # session marked for kill
+                376,    # file %s cannot be read at this time
+                603,    # ORACLE server session terminated
+                1012,   # not logged on
+                1033,   # ORACLE initialization or shutdown in progress
+                1034,   # the Oracle instance is not available for use
+                1089,   # immediate shutdown or close in progress
+                1090,   # shutdown in progress
+                1092,   # ORACLE instance terminated
+                1115,   # IO error reading block from file %s (block # %s)
+                2396,   # exceeded maximum idle time
+                3113,   # end-of-file on communication channel
+                3114,   # not connected to ORACLE
+                3135,   # connection lost contact
+                12153,  # TNS:not connected
+                12514,  # Service %s is not registered with the listener
+                12537,  # TNS:connection closed
+                12547,  # TNS:lost contact
+                12570,  # TNS:packet reader failure
+                12571,  # TNS:packet writer failure
+                12583,  # TNS:no reader
+                12757,  # instance does not currently know of requested service
+                16456,  # missing or invalid value
+            ):
+                is_recoverable = True
             error = errors._Error(self.error_info.message,
                                   code=self.error_info.num,
-                                  offset=self.error_info.pos)
+                                  offset=self.error_info.pos,
+                                  isrecoverable=is_recoverable)
             if error.is_session_dead:
                 self.conn_impl._protocol._force_close()
             raise error.exc_type(error)

tests/test_1700_error.py

@@ -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
@@ -58,6 +58,7 @@ def test_1701(self):
         self.assertEqual(error_obj.code, 20101)
         self.assertEqual(error_obj.offset, 0)
         self.assertIsInstance(error_obj.isrecoverable, bool)
+        self.assertFalse(error_obj.isrecoverable)
         new_error_obj = pickle.loads(pickle.dumps(error_obj))
         self.assertIsInstance(new_error_obj, oracledb._Error)
         self.assertEqual(new_error_obj.message, error_obj.message)
@@ -198,6 +199,20 @@ def test_1708(self):
             self.assertEqual(error_obj.full_code, f"ORA-{code}")
             self.assertTrue("Help:" not in error_obj.message)
 
+    @unittest.skipIf(test_env.get_is_drcp(), "not supported with DRCP")
+    def test_1709(self):
+        "1709 - error from killed connection is deemed recoverable"
+        admin_conn = test_env.get_admin_connection()
+        conn = test_env.get_connection()
+        sid, serial = self.get_sid_serial(conn)
+        with admin_conn.cursor() as admin_cursor:
+            sql = f"alter system kill session '{sid},{serial}'"
+            admin_cursor.execute(sql)
+        with self.assertRaisesFullCode("DPY-4011") as cm:
+            with conn.cursor() as cursor:
+                cursor.execute("select user from dual")
+        self.assertTrue(cm.error_obj.isrecoverable)
+
 
 if __name__ == "__main__":
     test_env.run_test_cases()

tests/test_6800_error_async.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2023, 2024, Oracle and/or its affiliates.
+# Copyright (c) 2023, 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
@@ -61,6 +61,7 @@ async def test_6801(self):
         self.assertEqual(error_obj.code, 20101)
         self.assertEqual(error_obj.offset, 0)
         self.assertIsInstance(error_obj.isrecoverable, bool)
+        self.assertFalse(error_obj.isrecoverable)
         new_error_obj = pickle.loads(pickle.dumps(error_obj))
         self.assertIsInstance(new_error_obj, oracledb._Error)
         self.assertEqual(new_error_obj.message, error_obj.message)
@@ -206,6 +207,20 @@ async def test_6808(self):
         self.assertEqual(result.warning.full_code, "DPY-7000")
         await self.cursor.execute(f"drop procedure {proc_name}")
 
+    @unittest.skipIf(test_env.get_is_drcp(), "not supported with DRCP")
+    async def test_6809(self):
+        "6809 - error from killed connection is deemed recoverable"
+        admin_conn = await test_env.get_admin_connection_async()
+        conn = await test_env.get_connection_async()
+        sid, serial = await self.get_sid_serial(conn)
+        with admin_conn.cursor() as admin_cursor:
+            sql = f"alter system kill session '{sid},{serial}'"
+            await admin_cursor.execute(sql)
+        with self.assertRaisesFullCode("DPY-4011") as cm:
+            with conn.cursor() as cursor:
+                await cursor.execute("select user from dual")
+        self.assertTrue(cm.error_obj.isrecoverable)
+
 
 if __name__ == "__main__":
     test_env.run_test_cases()

tests/test_env.py

@@ -552,11 +552,11 @@ def __exit__(self, exc_type, exc_value, tb):
         if not issubclass(exc_type, oracledb.Error):
             return False
         if issubclass(exc_type, oracledb.Error):
-            error_obj = exc_value.args[0]
-            if error_obj.full_code not in self.full_codes:
+            self.error_obj = exc_value.args[0]
+            if self.error_obj.full_code not in self.full_codes:
                 message = (
                     f"{self.message_fragment} should have been raised but "
-                    f'"{error_obj.full_code}" was raised instead.'
+                    f'"{self.error_obj.full_code}" was raised instead.'
                 )
                 raise AssertionError(message)
         return True