Added attributes "session_id" and "serial_num" on connections.

Author: anthony-tuininga

doc/src/api_manual/connection.rst

@@ -825,6 +825,25 @@ Connection Attributes
 
         This attribute is an extension to the DB API definition.
 
+.. attribute:: Connection.serial_num
+
+    This read-only attribute specifies the session serial number associated with
+    the connection. It is the same value returned by the SQL
+    ``SELECT SERIAL# FROM V$SESSION``. It is available only in python-oracledb
+    Thin mode.
+
+    .. versionadded:: 2.5.0
+
+    .. note::
+
+        This attribute is an extension to the DB API definition.
+
+        For applications using Database Resident Connection Pooling (DRCP),
+        the ``serial_num`` attribute may not contain the current session state
+        until a round-trip is made to the database after acquiring a session.
+        It is recommended to not use this attribute if your application uses
+        DRCP but may not perform a round-trip.
+
 .. attribute:: Connection.service_name
 
     This read-only attribute specifies the Oracle Database service name
@@ -837,6 +856,25 @@ Connection Attributes
 
         This attribute is an extension to the DB API definition.
 
+.. attribute:: Connection.session_id
+
+    This read-only attribute specifies the session identifier associated with
+    the connection. It is the same value returned by the SQL
+    ``SELECT SID FROM V$SESSION``. It is available only in python-oracledb
+    Thin mode.
+
+    .. versionadded:: 2.5.0
+
+    .. note::
+
+        This attribute is an extension to the DB API definition.
+
+        For applications using Database Resident Connection Pooling (DRCP),
+        the ``session_id`` attribute may not contain the current session state
+        until a round-trip is made to the database after acquiring a session.
+        It is recommended to not use this attribute if your application uses
+        DRCP but may not perform a round-trip.
+
 .. attribute:: Connection.stmtcachesize
 
     This read-write attribute specifies the size of the statement cache. This

doc/src/release_notes.rst

@@ -17,6 +17,9 @@ oracledb 2.5.0 (TBD)
 Thin Mode Changes
 +++++++++++++++++
 
+#)  Added attributes :attr:`Connection.session_id` and
+    :attr:`Connection.serial_num` that provide information about the session
+    identifier and session serial number associated with a connection.
 #)  Added attributes
     :attr:`oracledb.defaults.driver_name <defaults.driver_name>`,
     :attr:`oracledb.defaults.machine <defaults.machine>`,

src/oracledb/connection.py

@@ -237,6 +237,22 @@ def db_name(self) -> str:
         self._verify_connected()
         return self._impl.get_db_name()
 
+    @property
+    def session_id(self) -> int:
+        """
+        Specifies the session identifier.
+        """
+        self._verify_connected()
+        return self._impl.get_session_id()
+
+    @property
+    def serial_num(self) -> int:
+        """
+        Specifies the session serial number.
+        """
+        self._verify_connected()
+        return self._impl.get_serial_num()
+
     @property
     def edition(self) -> str:
         """

src/oracledb/impl/base/connection.pyx

@@ -278,9 +278,15 @@ cdef class BaseConnImpl:
     def get_sdu(self):
         errors._raise_not_supported("getting the session data unit (SDU)")
 
+    def get_serial_num(self):
+        errors._raise_not_supported("getting the session serial number")
+
     def get_service_name(self):
         errors._raise_not_supported("getting the service name")
 
+    def get_session_id(self):
+        errors._raise_not_supported("getting the session id")
+
     def get_stmt_cache_size(self):
         errors._raise_not_supported("getting the statement cache size")
 

src/oracledb/impl/thin/connection.pyx

@@ -35,7 +35,7 @@ cdef class BaseThinConnImpl(BaseConnImpl):
         StatementCache _statement_cache
         BaseProtocol _protocol
         uint32_t _session_id
-        uint32_t _serial_num
+        uint16_t _serial_num
         str _action
         bint _action_modified
         str _dbop
@@ -216,6 +216,12 @@ cdef class BaseThinConnImpl(BaseConnImpl):
     def get_db_name(self):
         return self._db_name
 
+    def get_session_id(self):
+        return self._session_id
+
+    def get_serial_num(self):
+        return self._serial_num
+
     def get_edition(self):
         return self._edition
 

src/oracledb/impl/thin/messages.pyx

@@ -281,8 +281,8 @@ cdef class Message:
                 if self.conn_impl._drcp_establish_session:
                     self.conn_impl._statement_cache.clear_open_cursors()
             self.conn_impl._drcp_establish_session = False
-            buf.skip_ub4()                  # session id
-            buf.skip_ub2()                  # serial number
+            buf.read_ub4(&self.conn_impl._session_id)
+            buf.read_ub2(&self.conn_impl._serial_num)
         else:
             errors._raise_err(errors.ERR_UNKNOWN_SERVER_PIGGYBACK,
                               opcode=opcode)
@@ -1628,7 +1628,7 @@ cdef class AuthMessage(Message):
             self.conn_impl._session_id = \
                     <uint32_t> int(self.session_data["AUTH_SESSION_ID"])
             self.conn_impl._serial_num = \
-                    <uint32_t> int(self.session_data["AUTH_SERIAL_NUM"])
+                    <uint16_t> int(self.session_data["AUTH_SERIAL_NUM"])
             self.conn_impl._db_domain = \
                     self.session_data.get("AUTH_SC_DB_DOMAIN")
             self.conn_impl._db_name = \

tests/test_1100_connection.py

@@ -866,6 +866,30 @@ def test_1150(self):
         )
         self.__verify_connect_arg("driver_name", "newdriver", sql)
 
+    @unittest.skipUnless(
+        test_env.get_is_thin(), "thick mode doesn't support session_id yet"
+    )
+    def test_1151(self):
+        "1151 - test getting session id"
+        conn = test_env.get_connection()
+        cursor = conn.cursor()
+        cursor.execute("select dbms_debug_jdwp.current_session_id from dual")
+        (fetched_value,) = cursor.fetchone()
+        self.assertEqual(conn.session_id, fetched_value)
+
+    @unittest.skipUnless(
+        test_env.get_is_thin(), "thick mode doesn't support serial_num yet"
+    )
+    def test_1152(self):
+        "1152 - test getting session serial number"
+        conn = test_env.get_connection()
+        cursor = conn.cursor()
+        cursor.execute(
+            "select dbms_debug_jdwp.current_session_serial from dual"
+        )
+        (fetched_value,) = cursor.fetchone()
+        self.assertEqual(conn.serial_num, fetched_value)
+
 
 if __name__ == "__main__":
     test_env.run_test_cases()

tests/test_5300_connection_async.py

@@ -649,6 +649,26 @@ async def test_5350(self):
         )
         await self.__verify_connect_arg("driver_name", "newdriver", sql)
 
+    async def test_5351(self):
+        "5351 - test getting session id"
+        async with test_env.get_connection_async() as conn:
+            cursor = conn.cursor()
+            await cursor.execute(
+                "select dbms_debug_jdwp.current_session_id from dual"
+            )
+            (fetched_value,) = await cursor.fetchone()
+            self.assertEqual(conn.session_id, fetched_value)
+
+    async def test_5352(self):
+        "5352 - test getting session serial number"
+        async with test_env.get_connection_async() as conn:
+            cursor = conn.cursor()
+            await cursor.execute(
+                "select dbms_debug_jdwp.current_session_serial from dual"
+            )
+            (fetched_value,) = await cursor.fetchone()
+            self.assertEqual(conn.serial_num, fetched_value)
+
 
 if __name__ == "__main__":
     test_env.run_test_cases()

tests/test_env.py

@@ -611,16 +611,19 @@ def get_sid_serial(self, conn=None):
         """
         if conn is None:
             conn = self.conn
-        with conn.cursor() as cursor:
-            cursor.execute(
-                """
-                select
-                    dbms_debug_jdwp.current_session_id,
-                    dbms_debug_jdwp.current_session_serial
-                from dual
-                """
-            )
-            return cursor.fetchone()
+        if get_is_thin():
+            return (conn.session_id, conn.serial_num)
+        else:
+            with conn.cursor() as cursor:
+                cursor.execute(
+                    """
+                    select
+                        dbms_debug_jdwp.current_session_id,
+                        dbms_debug_jdwp.current_session_serial
+                    from dual
+                    """
+                )
+                return cursor.fetchone()
 
     def get_soda_database(
         self,
@@ -725,16 +728,19 @@ async def get_sid_serial(self, conn=None):
         """
         if conn is None:
             conn = self.conn
-        with conn.cursor() as cursor:
-            await cursor.execute(
-                """
-                select
-                    dbms_debug_jdwp.current_session_id,
-                    dbms_debug_jdwp.current_session_serial
-                from dual
-                """
-            )
-            return await cursor.fetchone()
+        if get_is_thin():
+            return (conn.session_id, conn.serial_num)
+        else:
+            with conn.cursor() as cursor:
+                await cursor.execute(
+                    """
+                    select
+                        dbms_debug_jdwp.current_session_id,
+                        dbms_debug_jdwp.current_session_serial
+                    from dual
+                    """
+                )
+                return await cursor.fetchone()
 
     async def is_on_oracle_cloud(self, connection=None):
         if connection is None:

utils/templates/connection.py

@@ -235,6 +235,22 @@ def db_name(self) -> str:
         self._verify_connected()
         return self._impl.get_db_name()
 
+    @property
+    def session_id(self) -> int:
+        """
+        Specifies the session identifier.
+        """
+        self._verify_connected()
+        return self._impl.get_session_id()
+
+    @property
+    def serial_num(self) -> int:
+        """
+        Specifies the session serial number.
+        """
+        self._verify_connected()
+        return self._impl.get_serial_num()
+
     @property
     def edition(self) -> str:
         """