Add new property:instanceName with the connection object

doc/src/api_manual/connection.rst

@@ -132,6 +132,14 @@ The properties of a *Connection* object are listed below.
         This property can only be used in the node-oracledb Thick mode. See
         :ref:`enablingthick`.
 
+.. attribute:: connection.instanceName
+
+    .. versionadded:: 6.1
+
+    This read-only attribute specifies the Oracle Database instance name
+    associated with the connection. It returns the same value as the SQL expression
+    ``sys_context('userenv', 'instance_name')``.
+
 .. attribute:: connection.module
 
     This write-only property is a string and it is the `module

doc/src/release_notes.rst

@@ -5,6 +5,16 @@
 node-oracledb Release Notes
 =============================
 
+node-oracledb `v6.1.0 <https://github.com/oracle/node-oracledb/compare/v6.0.3...v6.1.0>`__ (TBD)
+------------------------------------------------------------------------------------------------
+
+Common Changes
+++++++++++++++
+
+#)  Added new property :attr:`connection.instanceName` which provides the
+    Oracle Database instance name associated with the connection. This returns the
+    same value as the SQL expression ``sys_context('userenv', 'instance_name')``.
+
 node-oracledb `v6.0.3 <https://github.com/oracle/node-oracledb/compare/v6.0.2...v6.0.3>`__ (12 Jul 2023)
 --------------------------------------------------------------------------------------------------------
 

lib/connection.js

@@ -1039,6 +1039,19 @@ class Connection extends EventEmitter {
     return info;
   }
 
+  //---------------------------------------------------------------------------
+  // instanceName
+  //
+  // Returns the Oracle Database instance name associated with the connection.
+  // This is the equivalent of the SQL expression:
+  // sys_context('userenv', 'instance_name')
+  //---------------------------------------------------------------------------
+  get instanceName() {
+    if (this._impl)
+      return this._impl.getInstanceName();
+    return undefined;
+  }
+
   //---------------------------------------------------------------------------
   // internalName
   //

lib/impl/connection.js

@@ -226,6 +226,15 @@ class ConnectionImpl {
     errors.throwNotImplemented("getting the external name");
   }
 
+  //---------------------------------------------------------------------------
+  // getInstanceName()
+  //
+  // Returns the Oracle Database instance name associated with the connection.
+  //---------------------------------------------------------------------------
+  getInstanceName() {
+    errors.throwNotImplemented("getting the Oracle Database instance name.");
+  }
+
   //---------------------------------------------------------------------------
   // getInternalName()
   //

lib/thin/connection.js

@@ -1038,6 +1038,12 @@ class ThinConnectionImpl extends ConnectionImpl {
     return '';
   }
 
+  //---------------------------------------------------------------------------
+  // Returns the Oracle Database instance name associated with the connection.
+  //---------------------------------------------------------------------------
+  getInstanceName() {
+    return this.instanceName;
+  }
 }
 
 module.exports = ThinConnectionImpl;

lib/thin/protocol/messages/auth.js

@@ -324,6 +324,7 @@ class AuthMessage extends Message {
 
       this.conn.sessionID = this.sessionData['AUTH_SESSION_ID'];
       this.conn.serialNum = this.sessionData['AUTH_SERIAL_NUM'];
+      this.conn.instanceName = this.sessionData['AUTH_INSTANCENAME'];
       let fullVersionNum = Number(this.sessionData['AUTH_VERSION_NO']);
       versionNum = (fullVersionNum >> 24) & 0xFF;
       if (buf.caps.ttcFieldVersion >= constants.TNS_CCAP_FIELD_VERSION_18_1_EXT_1) {

src/njsConnection.c

@@ -44,6 +44,7 @@ NJS_NAPI_METHOD_DECL_SYNC(njsConnection_getCallTimeout);
 NJS_NAPI_METHOD_DECL_SYNC(njsConnection_getCurrentSchema);
 NJS_NAPI_METHOD_DECL_ASYNC(njsConnection_getDbObjectClass);
 NJS_NAPI_METHOD_DECL_SYNC(njsConnection_getExternalName);
+NJS_NAPI_METHOD_DECL_SYNC(njsConnection_getInstanceName);
 NJS_NAPI_METHOD_DECL_SYNC(njsConnection_getInternalName);
 NJS_NAPI_METHOD_DECL_SYNC(njsConnection_getOracleServerVersion);
 NJS_NAPI_METHOD_DECL_SYNC(njsConnection_getOracleServerVersionString);
@@ -140,6 +141,8 @@ static const napi_property_descriptor njsClassProperties[] = {
             NULL, napi_default, NULL },
     { "getExternalName", NULL, njsConnection_getExternalName, NULL, NULL, NULL,
             napi_default, NULL },
+    { "getInstanceName", NULL, njsConnection_getInstanceName, NULL, NULL, NULL,
+            napi_default, NULL },
     { "getInternalName", NULL, njsConnection_getInternalName, NULL, NULL, NULL,
             napi_default, NULL },
     { "getOracleServerVersion", NULL, njsConnection_getOracleServerVersion,
@@ -1071,6 +1074,26 @@ NJS_NAPI_METHOD_IMPL_SYNC(njsConnection_getExternalName, 0, NULL)
 }
 
 
+//-----------------------------------------------------------------------------
+// njsConnection_getInstanceName()
+//   Get accessor for "instanceName" property
+//-----------------------------------------------------------------------------
+NJS_NAPI_METHOD_IMPL_SYNC(njsConnection_getInstanceName, 0, NULL)
+{
+    njsConnection *conn = (njsConnection*) callingInstance;
+    uint32_t valueLength;
+    const char *value;
+
+    if (conn->handle) {
+        if (dpiConn_getInstanceName(conn->handle, &value, &valueLength) < 0)
+            return njsUtils_throwErrorDPI(env, globals);
+        NJS_CHECK_NAPI(env, napi_create_string_utf8(env, value, valueLength,
+                returnValue))
+    }
+
+    return true;
+}
+
 
 //-----------------------------------------------------------------------------
 // njsConnection_getInternalName()

test/connection.js

@@ -551,4 +551,15 @@ describe('1. connection.js', function() {
       );
     });
   }); //1.16
+
+  describe('1.17 Oracle Database instance name associated with the connection', function() {
+    it('1.17.1 connection parameter instanceName comparision with query result', async function() {
+      const connection = await oracledb.getConnection(dbConfig);
+      const query = "select upper(sys_context('userenv', 'instance_name')) from dual";
+      const result = await connection.execute(query);
+      assert(result);
+      assert.deepStrictEqual(result.rows[0][0], connection.instanceName.toUpperCase());
+      connection.close();
+    });
+  }); //1.17
 });