Added properties on the Connection object to determine the database

domain name, the database name, the maximum number of open cursors, the
service name and whether a transaction is in progress or not.

Author: anthony-tuininga

doc/src/api_manual/connection.rst

@@ -609,6 +609,30 @@ Connection Attributes
 
         This attribute is an extension to the DB API definition.
 
+.. attribute:: Connection.db_domain
+
+    This read-only attribute specifies the Oracle Database domain name
+    associated with the connection. It is the same value returned by the SQL
+    ``SELECT value FROM V$PARAMETER WHERE NAME = 'db_domain'``.
+
+    .. versionadded:: 2.0.0
+
+    .. note::
+
+        This attribute is an extension to the DB API definition.
+
+.. attribute:: Connection.db_name
+
+    This read-only attribute specifies the Oracle Database name associated with
+    the connection. It is the same value returned by the SQL
+    ``SELECT NAME FROM V$DATABASE``.
+
+    .. versionadded:: 2.0.0
+
+    .. note::
+
+        This attribute is an extension to the DB API definition.
+
 .. attribute:: Connection.dbop
 
     This write-only attribute sets the database operation that is to be
@@ -742,6 +766,19 @@ Connection Attributes
         This attribute is an extension to the DB API definition.
 
 
+.. attribute:: Connection.max_open_cursors
+
+    This read-only attribute specifies the maximum number of cursors that the
+    database can have open concurrently. It is the same value returned by the
+    SQL ``SELECT VALUE FROM V$PARAMETER WHERE NAME = 'open_cursors'``.
+
+    .. versionadded:: 2.0.0
+
+    .. note::
+
+        This attribute is an extension to the DB API definition.
+
+
 .. attribute:: Connection.module
 
     This write-only attribute sets the module column in the v$session table.
@@ -784,6 +821,18 @@ Connection Attributes
 
         This attribute is an extension to the DB API definition.
 
+.. attribute:: Connection.service_name
+
+    This read-only attribute specifies the Oracle Database service name
+    associated with the connection.  This is the same value returned by the SQL
+    ``SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL``.
+
+    .. versionadded:: 2.0.0
+
+    .. note::
+
+        This attribute is an extension to the DB API definition.
+
 .. attribute:: Connection.stmtcachesize
 
     This read-write attribute specifies the size of the statement cache. This
@@ -837,6 +886,17 @@ Connection Attributes
 
         This attribute is an extension to the DB API definition.
 
+.. attribute:: Connection.transaction_in_progress
+
+    This read-only attribute specifies whether a transaction is currently in
+    progress on the database associated with the connection.
+
+    .. versionadded:: 2.0.0
+
+    .. note::
+
+        This attribute is an extension to the DB API definition.
+
 .. attribute:: Connection.username
 
     This read-only attribute returns the name of the user which established the

doc/src/release_notes.rst

@@ -25,6 +25,10 @@ Common Changes
 ++++++++++++++
 
 #)  Dropped support for Python 3.6 and added support for Python 3.12.
+#)  Added properties that provide information about the database:
+    :attr:`Connection.db_domain`, :attr:`Connection.db_name`,
+    :attr:`Connection.max_open_cursors`, :attr:`Connection.service_name`
+    and :attr:`Connection.transaction_in_progress`.
 #)  Added attributes :data:`FetchInfo.domain_schema`,
     :data:`FetchInfo.domain_name` and :data:`FetchInfo.annotations` for the
     `SQL domain <https://docs.oracle.com/en/database/oracle/oracle-database/

src/oracledb/connection.py

@@ -405,6 +405,22 @@ def econtext_id(self, value: str) -> None:
         self._verify_connected()
         self._impl.set_econtext_id(value)
 
+    @property
+    def db_domain(self) -> str:
+        """
+        Specifies the name of the database domain.
+        """
+        self._verify_connected()
+        return self._impl.get_db_domain()
+
+    @property
+    def db_name(self) -> str:
+        """
+        Specifies the name of the database.
+        """
+        self._verify_connected()
+        return self._impl.get_db_name()
+
     @property
     def edition(self) -> str:
         """
@@ -547,6 +563,15 @@ def maxBytesPerCharacter(self) -> int:
         """
         return 4
 
+    @property
+    def max_open_cursors(self) -> int:
+        """
+        Specifies the maximum number of cursors that the database can have open
+        concurrently.
+        """
+        self._verify_connected()
+        return self._impl.get_max_open_cursors()
+
     @property
     def module(self) -> None:
         raise AttributeError("module is not readable")
@@ -682,6 +707,15 @@ def rollback(self) -> None:
         self._verify_connected()
         self._impl.rollback()
 
+    @property
+    def service_name(self) -> str:
+        """
+        Specifies the name of the service that was used to connect to the
+        database.
+        """
+        self._verify_connected()
+        return self._impl.get_service_name()
+
     def shutdown(self, mode: int = 0) -> None:
         """
         Shutdown the database. In order to do this the connection must be
@@ -1004,6 +1038,15 @@ def tpc_rollback(self, xid: Xid = None) -> None:
             self._verify_xid(xid)
         self._impl.tpc_rollback(xid)
 
+    @property
+    def transaction_in_progress(self) -> bool:
+        """
+        Specifies whether a transaction is currently in progress on the
+        database using this connection.
+        """
+        self._verify_connected()
+        return self._impl.get_transaction_in_progress()
+
     def unsubscribe(self, subscr: Subscription) -> None:
         """
         Unsubscribe from events in the database that were originally subscribed

src/oracledb/impl/base/connection.pyx

@@ -211,6 +211,14 @@ cdef class BaseConnImpl:
     def get_current_schema(self):
         pass
 
+    @utils.CheckImpls("getting the database domain name")
+    def get_db_domain(self):
+        pass
+
+    @utils.CheckImpls("getting the database name")
+    def get_db_name(self):
+        pass
+
     @utils.CheckImpls("getting the edition")
     def get_edition(self):
         pass
@@ -235,10 +243,22 @@ cdef class BaseConnImpl:
     def get_ltxid(self):
         pass
 
+    @utils.CheckImpls("getting the maximum number of open cursors")
+    def get_max_open_cursors(self):
+        pass
+
+    @utils.CheckImpls("getting the service name")
+    def get_service_name(self):
+        pass
+
     @utils.CheckImpls("getting the statement cache size")
     def get_stmt_cache_size(self):
         pass
 
+    @utils.CheckImpls("getting if a transaction is in progress")
+    def get_transaction_in_progress(self):
+        pass
+
     @utils.CheckImpls("getting an object type")
     def get_type(self, object conn, str name):
         pass

src/oracledb/impl/thick/connection.pyx

@@ -466,6 +466,24 @@ cdef class ThickConnImpl(BaseConnImpl):
         if value is not NULL:
             return value[:value_length].decode()
 
+    def get_db_domain(self):
+        cdef:
+            uint32_t value_length
+            const char *value
+        if dpiConn_getDbDomain(self._handle, &value, &value_length) < 0:
+            _raise_from_odpi()
+        if value is not NULL:
+            return value[:value_length].decode()
+
+    def get_db_name(self):
+        cdef:
+            uint32_t value_length
+            const char *value
+        if dpiConn_getDbName(self._handle, &value, &value_length) < 0:
+            _raise_from_odpi()
+        if value is not NULL:
+            return value[:value_length].decode()
+
     def get_edition(self):
         cdef:
             uint32_t value_length
@@ -516,12 +534,33 @@ cdef class ThickConnImpl(BaseConnImpl):
             _raise_from_odpi()
         return value[:value_length]
 
+    def get_max_open_cursors(self):
+        cdef uint32_t value
+        if dpiConn_getMaxOpenCursors(self._handle, &value) < 0:
+            _raise_from_odpi()
+        return value
+
+    def get_service_name(self):
+        cdef:
+            uint32_t value_length
+            const char *value
+        if dpiConn_getServiceName(self._handle, &value, &value_length) < 0:
+            _raise_from_odpi()
+        if value is not NULL:
+            return value[:value_length].decode()
+
     def get_stmt_cache_size(self):
         cdef uint32_t value
         if dpiConn_getStmtCacheSize(self._handle, &value) < 0:
             _raise_from_odpi()
         return value
 
+    def get_transaction_in_progress(self):
+        cdef bint value
+        if dpiConn_getTransactionInProgress(self._handle, &value) < 0:
+            _raise_from_odpi()
+        return value
+
     def get_type(self, object conn, str name):
         cdef:
             dpiObjectType *handle

src/oracledb/impl/thick/odpi.pxd

@@ -572,6 +572,12 @@ cdef extern from "impl/thick/odpi/embed/dpi.c":
     int dpiConn_getCurrentSchema(dpiConn *conn, const char **value,
             uint32_t *valueLength) nogil
 
+    int dpiConn_getDbDomain(dpiConn *conn, const char **value,
+            uint32_t *valueLength) nogil
+
+    int dpiConn_getDbName(dpiConn *conn, const char **value,
+            uint32_t *valueLength) nogil
+
     int dpiConn_getEdition(dpiConn *conn, const char **value,
             uint32_t *valueLength) nogil
 
@@ -591,6 +597,9 @@ cdef extern from "impl/thick/odpi/embed/dpi.c":
     int dpiConn_getLTXID(dpiConn *conn, const char **value,
             uint32_t *valueLength) nogil
 
+    int dpiConn_getMaxOpenCursors(dpiConn *conn,
+            uint32_t *maxOpenCursors) nogil
+
     int dpiConn_getOciAttr(dpiConn *conn, uint32_t handleType,
             uint32_t attribute, dpiDataBuffer *value,
             uint32_t *valueLength) nogil
@@ -601,10 +610,16 @@ cdef extern from "impl/thick/odpi/embed/dpi.c":
     int dpiConn_getServerVersion(dpiConn *conn, const char **releaseString,
             uint32_t *releaseStringLength, dpiVersionInfo *versionInfo) nogil
 
+    int dpiConn_getServiceName(dpiConn *conn, const char **value,
+            uint32_t *valueLength) nogil
+
     int dpiConn_getSodaDb(dpiConn *conn, dpiSodaDb **db) nogil
 
     int dpiConn_getStmtCacheSize(dpiConn *conn, uint32_t *cacheSize) nogil
 
+    int dpiConn_getTransactionInProgress(dpiConn *conn,
+            bint *txnInProgress) nogil
+
     int dpiConn_getCallTimeout(dpiConn *conn, uint32_t *value) nogil
 
     int dpiConn_newMsgProps(dpiConn *conn, dpiMsgProps **props) nogil

src/oracledb/impl/thin/connection.pyx

@@ -53,10 +53,14 @@ cdef class ThinConnImpl(BaseConnImpl):
         bytes _ltxid
         str _current_schema
         bint _current_schema_modified
+        uint32_t _max_open_cursors
+        str _db_domain
+        str _db_name
         str _edition
         str _instance_name
         str _internal_name
         str _external_name
+        str _service_name
         array.array _cursors_to_close
         ssize_t _num_cursors_to_close
         bint _drcp_enabled
@@ -306,6 +310,12 @@ cdef class ThinConnImpl(BaseConnImpl):
     def get_current_schema(self):
         return self._current_schema
 
+    def get_db_domain(self):
+        return self._db_domain
+
+    def get_db_name(self):
+        return self._db_name
+
     def get_edition(self):
         return self._edition
 
@@ -325,9 +335,18 @@ cdef class ThinConnImpl(BaseConnImpl):
     def get_ltxid(self):
         return self._ltxid or b''
 
+    def get_max_open_cursors(self):
+        return self._max_open_cursors
+
+    def get_service_name(self):
+        return self._service_name
+
     def get_stmt_cache_size(self):
         return self._statement_cache_size
 
+    def get_transaction_in_progress(self):
+        return self._protocol._txn_in_progress
+
     def get_type(self, object conn, str name):
         cdef ThinDbObjectTypeCache cache = \
                 get_dbobject_type_cache(self._dbobject_type_cache_num)

src/oracledb/impl/thin/messages.pyx

@@ -1519,8 +1519,17 @@ 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._db_domain = \
+                    self.session_data.get("AUTH_SC_DB_DOMAIN")
+            self.conn_impl._db_name = \
+                    self.session_data.get("AUTH_SC_DBUNIQUE_NAME")
+            self.conn_impl._max_open_cursors = \
+                    int(self.session_data.get("AUTH_MAX_OPEN_CURSORS"))
+            self.conn_impl._service_name = \
+                    self.session_data.get("AUTH_SC_SERVICE_NAME")
             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)