Add new property "instance_name" on connections.

doc/src/api_manual/connection.rst

@@ -683,6 +683,16 @@ Connection Attributes
         This attribute is an extension to the DB API definition.
 
 
+.. attribute:: Connection.instance_name
+
+    This read-only attribute specifies the Oracle Database instance name
+    associated with the connection. It is the same value as the SQL expression
+    ``sys_context('userenv', 'instance_name')``.
+
+    .. note::
+
+        This attribute is an extension to the DB API definition.
+
 .. attribute:: Connection.internal_name
 
     This read-write attribute specifies the internal name that is used by the

doc/src/release_notes.rst

@@ -54,6 +54,10 @@ Thick Mode Changes
 Common Changes
 ++++++++++++++
 
+#)  Added new property :attr:`Connection.instance_name` which provides the
+    Oracle Database instance name associated with the connection. This is the
+    same value as the SQL expression
+    ``sys_context('userenv', 'instance_name')``.
 #)  Added support for automatically retrying a query if the error
     ``ORA-00932: inconsistent data types`` is raised (which can occur if a
     table or view is recreated with a data type that is incompatible with

src/oracledb/connection.py

@@ -467,6 +467,17 @@ def inputtypehandler(self, value: Callable) -> None:
         self._verify_connected()
         self._impl.inputtypehandler = value
 
+    @property
+    def instance_name(self) -> str:
+        """
+        Returns the instance name associated with the connection. This is the
+        equivalent of the SQL expression:
+
+        sys_context('userenv', 'instance_name')
+        """
+        self._verify_connected()
+        return self._impl.get_instance_name()
+
     @property
     def internal_name(self) -> str:
         """

src/oracledb/impl/base/connection.pyx

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2020, 2022, Oracle and/or its affiliates.
+# Copyright (c) 2020, 2023, 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
@@ -223,6 +223,10 @@ cdef class BaseConnImpl:
     def get_handle(self):
         pass
 
+    @utils.CheckImpls("getting the instance name")
+    def get_instance_name(self):
+        pass
+
     @utils.CheckImpls("getting the internal name")
     def get_internal_name(self):
         pass

src/oracledb/impl/thick/connection.pyx

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2020, 2022, Oracle and/or its affiliates.
+# Copyright (c) 2020, 2023, 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
@@ -490,6 +490,15 @@ cdef class ThickConnImpl(BaseConnImpl):
             _raise_from_odpi()
         return <uint64_t> handle
 
+    def get_instance_name(self):
+        cdef:
+            uint32_t value_length
+            const char *value
+        if dpiConn_getInstanceName(self._handle, &value, &value_length) < 0:
+            _raise_from_odpi()
+        if value is not NULL:
+            return value[:value_length].decode()
+
     def get_internal_name(self):
         cdef:
             uint32_t value_length

src/oracledb/impl/thick/odpi.pxd

@@ -566,6 +566,9 @@ cdef extern from "impl/thick/odpi/embed/dpi.c":
 
     int dpiConn_getHandle(dpiConn *conn, void **handle) nogil
 
+    int dpiConn_getInstanceName(dpiConn *conn, const char **value,
+            uint32_t *valueLength) nogil
+
     int dpiConn_getInternalName(dpiConn *conn, const char **value,
             uint32_t *valueLength) nogil
 

src/oracledb/impl/thin/connection.pyx

@@ -54,6 +54,7 @@ cdef class ThinConnImpl(BaseConnImpl):
         str _current_schema
         bint _current_schema_modified
         str _edition
+        str _instance_name
         str _internal_name
         str _external_name
         array.array _cursors_to_close
@@ -350,6 +351,9 @@ cdef class ThinConnImpl(BaseConnImpl):
     def get_external_name(self):
         return self._external_name
 
+    def get_instance_name(self):
+        return self._instance_name
+
     def get_internal_name(self):
         return self._internal_name
 

src/oracledb/impl/thin/messages.pyx

@@ -1489,6 +1489,8 @@ cdef class AuthMessage(Message):
                     <uint32_t> int(self.session_data["AUTH_SESSION_ID"])
             self.conn_impl._serial_num = \
                     <uint32_t> int(self.session_data["AUTH_SERIAL_NUM"])
+            self.conn_impl._instance_name = \
+                    self.session_data.get("AUTH_INSTANCENAME")
             self.conn_impl._server_version = \
                     "%d.%d.%d.%d.%d" % self._get_version_tuple(buf)
 

tests/test_1100_connection.py

@@ -609,5 +609,15 @@ def test_1139_invalid_params(self):
         self.assertRaisesRegex(oracledb.ProgrammingError, "^DPY-2025:",
                                oracledb.connect, params={"number": 7})
 
+    def test_1140_instance_name(self):
+        "1140 - test connection instance name"
+        connection = test_env.get_connection()
+        cursor = connection.cursor()
+        cursor.execute("""
+                select upper(sys_context('userenv', 'instance_name'))
+                from dual""")
+        instance_name, = cursor.fetchone()
+        self.assertEqual(connection.instance_name.upper(), instance_name)
+
 if __name__ == "__main__":
     test_env.run_test_cases()