Add tests and documentation for the final release

Author: sharadraju

doc/src/api_manual/connection.rst

@@ -1350,7 +1350,12 @@ Connection Methods
             If all values in all records for a particular bind variable are null, the type of that bind is ``oracledb.STRING`` with a maximum size of 1.
 
             The maximum sizes of strings and buffers are determined by scanning all records unless a :ref:`bindDefs <executemanyoptbinddefs>` property is used. This property explicitly specifies the characteristics of each bind variable.
-        * - options
+        * - ``numIterations``
+          - Number
+          - .. _executemanynumiterations:
+
+            If there are no bind values, or values have previously been bound, then you can set the ``numIterations`` parameter to an integer value that specifies the number of iterations. See :ref:`plsqlexecutemany` for an example of using this parameter.
+        * - ``options``
           - Object
           - .. _executemanyoptions:
 

doc/src/api_manual/oracledb.rst

@@ -3292,10 +3292,10 @@ Oracledb Methods
 
         promise = getNetworkServiceNames(String configDir);
 
-    Returns a list of network service names that is defined in the
-    :ref:`tnsnames.ora <tnsadmin>` file which is inside the directory that
-    is specified in the ``configDir`` property or the ``TNS_ADMIN``
-    environment variable if ``configDir`` is not specified. If a
+    Returns a list of TNS Aliases, also known as Network Service Names,
+    defined in the :ref:`tnsnames.ora <tnsadmin>` file which is inside the
+    directory that is specified in the ``configDir`` property or the
+    ``TNS_ADMIN`` environment variable if ``configDir`` is not specified. If a
     ``tnsnames.ora`` file does not exist, then an exception is raised.
 
     The parameters of the ``oracledb.getNetworkServiceNames()`` method are:

doc/src/conf.py

@@ -46,8 +46,8 @@
 # from the other)
 #
 # The short X.Y version.
-version = '6.6'
-release = '6.6.0'
+version = '6.7'
+release = '6.7.0'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

doc/src/release_notes.rst

@@ -5,44 +5,46 @@
 node-oracledb Release Notes
 ===========================
 
-For deprecated and desupported features, see :ref:`Deprecations and desupported features <deprecations>`.
+For deprecated and desupported features, see
+:ref:`Deprecations and desupported features <deprecations>`.
 
 node-oracledb `v6.7.0 <https://github.com/oracle/node-oracledb/compare/v6.6.0...v6.7.0>`__ (TBD)
 ---------------------------------------------------------------------------------------------------------
 
 Common Changes
 ++++++++++++++
 
-#)  Added tracing functionality for OpenTelemetry support.
+#)  Added :ref:`tracing functionality <tracehandlerinterface>` for
+    OpenTelemetry support.
 
 #)  Changed default values of ``transportConnectTimeout`` and
     ``retryDelay`` properties to *20* seconds and *1* second respectively in
     :meth:`oracledb.getConnection()` and :meth:`oracledb.createPool()` for
     consistency with other Oracle Database drivers.
 
 #)  Added method :meth:`oracledb.getNetworkServiceNames()` to support fetching
-    the list of network service names from the ``tnsnames.ora`` file.
+    the list of TNS Aliases from the ``tnsnames.ora`` file.
 
-#) Improvements to Centralized Configuration Providers support:
+#)  Improvements to Centralized Configuration Providers support:
 
-   - Added support to connect to Oracle Database via the centralized
-     configuration providers using wallets stored in Azure Key Vault and
-     OCI Vault.
+    - Added support to connect to Oracle Database via the centralized
+      configuration providers using wallets stored in Azure Key Vault and
+      OCI Vault.
 
-   - Added ability to cache the configuration information retrieved from
-     :ref:`Azure App Configuration <conninfocacheazure>` and
-     :ref:`OCI Object Storage <conninfocacheoci>` centralized configuration
-     providers.
+    - Added ability to cache the configuration information retrieved from
+      :ref:`Azure App Configuration <conninfocacheazure>` and
+      :ref:`OCI Object Storage <conninfocacheoci>` centralized configuration
+      providers.
 
-   - Ensure that the password stored in OCI vault and retrieved in
-     base64-encoded format is decoded correctly.
+    - Ensure that the password stored in OCI vault and retrieved in
+      base64-encoded format is decoded correctly.
 
-   - Added internal code changes to validate the updated OCI centralized
-     configuration provider URL syntax.
+    - Added internal code changes to validate the updated OCI centralized
+      configuration provider URL syntax.
 
-   - Changed the password type parameter values from `vault-oci` and
-     `vault-azure` to `ocivault` and `azurevault` respectively for consistency
-     with other Oracle Database drivers.
+    - Changed the password type parameter values from `vault-oci` and
+      `vault-azure` to `ocivault` and `azurevault` respectively for consistency
+      with other Oracle Database drivers.
 
 #)  Remove the 'Critical Dependency' warning from webpack builds.
     See `Issue #1678 <https://github.com/oracle/node-oracledb/issues/1678>`__.

doc/src/user_guide/batch_statement.rst

@@ -189,6 +189,8 @@ Output is::
       [ [ 'AAAmI9AAMAAAAnVAAB' ] ],
       [ [ 'AAAmI9AAMAAAAnVAAC' ] ] ]
 
+.. _plsqlexecutemany:
+
 Calling PL/SQL with ``executeMany()``
 =====================================
 

doc/src/user_guide/migrate.rst

@@ -4,6 +4,38 @@
 Upgrading to the Latest node-oracledb Releases
 **********************************************
 
+.. _upgradev66v67:
+
+Upgrading from node-oracledb 6.6 to 6.7
+=======================================
+
+- Review the :ref:`releasenotes` and take advantage of new features.
+
+- Using the new :meth:`oracledb.getNetworkServiceNames()` method, you can
+  fetch the list of TNS Aliases from the ``tnsnames.ora`` file.
+
+- With :ref:`Centralized Configuration Providers <configurationprovider>`, you
+  can now:
+
+  - Connect to Oracle Database using wallets stored in Azure Key Vault and OCI
+    vault.
+
+  - Cache the configuration information retrieved from
+    :ref:`Azure App Configuration <conninfocacheazure>` and
+    :ref:`OCI Object Storage <conninfocacheoci>` centralized configuration
+    providers.
+
+- In node-oracledb Thin mode, you can use the attributes
+  :attr:`oracledb.driverName`, :attr:`oracledb.machine`,
+  :attr:`oracledb.osUser`, :attr:`oracledb.program`, and
+  :attr:`oracledb.terminal` to set information about the driver name, machine
+  name, operating system user, program name, and terminal name respectively.
+
+- In node-oracledb Thick mode, the new ``regId`` property of the
+  :ref:`message object parameter <messageparam>` in the CQN subscription
+  :ref:`callback <consubscribeoptcallback>` function returns a unique
+  identifier during registration.
+
 .. _upgradev65v66:
 
 Upgrading from node-oracledb 6.5 to 6.6

doc/src/user_guide/tracing.rst

@@ -159,21 +159,23 @@ node-oracledb.
 
 Node-oracledb applications that call PL/SQL can step through that PL/SQL code
 using JDWP in a debugger. This allows Node.js and PL/SQL code to be debugged
-in the same debugger environment. You can enable PL/SQL debugging in the
-node-oracledb modes as follows:
+in the same debugger environment. You can enable PL/SQL debugging in
+node-oracledb as follows:
 
-- If you are using node-oracledb Thick mode, set the ``ORA_DEBUG_JDWP``
+- In node-oracledb Thin or Thick modes, set the ``ORA_DEBUG_JDWP``
   environment variable to `host=hostname;port=portnum` indicating where the
   PL/SQL debugger is running. Then run the application.
 
-- In node-oracledb Thin mode, you can additionally set the connection
+- In node-oracledb Thin mode, you can alternatively set the connection
   parameter ``debugJdwp`` during connection. This variable defaults to the
   value of the ``ORA_DEBUG_JDWP`` environment variable.
 
-See `DBMS_DEBUG_JDWP <https://docs.oracle.com/en/database/oracle/oracle-
-database/19/arpls/DBMS_DEBUG_JDWP.html>`_ and `Debugging PL/SQL from ASP.NET
-and Visual Studio <http://cshay.blogspot.com/2006/10/debugging-plsql-from-
-aspnet-and-visual.html>`_.
+See the documentation on `DBMS_DEBUG_JDWP <https://www.oracle.com/pls/topic/
+lookup?ctx=dblatest&id=GUID-AFF566A0-9E90-4218-B5C6-A74C3BF1CE14>`_, the video
+`PL/SQL debugging with Visual Studio and Visual Studio Code <https://www.
+youtube.com/watch?v=wk-3hLe30kk>`_, and the blog post `Debugging PL/SQL with
+Visual Studio Code (and more) <https://medium.com/oracledevs/debugging-pl-sql-
+with-visual-studio-code-and-more-45631f3952cf>`_.
 
 .. _tracingsql:
 

test/aq9.js

@@ -45,16 +45,12 @@ describe('301. aq9.js', function() {
   const ORDER_TYP   = `${AQ_USER}.ORDER_TYP`;
 
   before(async function() {
-    const userConfig = {
-      user: dbConfig.user,
-      password: dbConfig.password,
-      connectString: dbConfig.connectString
-    };
-    const initConn = await oracledb.getConnection(userConfig);
+    const initConn = await oracledb.getConnection(dbConfig);
     const dbVersion = initConn.oracleServerVersion;
     await initConn.close();
 
-    if (!dbConfig.test.DBA_PRIVILEGE || oracledb.thin || dbVersion < 1900000000) {
+    if (!dbConfig.test.DBA_PRIVILEGE || oracledb.thin || dbVersion < 1900000000
+      || testsUtil.getClientVersion() < 2306000000) {
       isRunnable = false;
     }
 

test/columnMetadata.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2015, 2023, Oracle and/or its affiliates. */
+/* Copyright (c) 2015, 2024, Oracle and/or its affiliates. */
 
 /******************************************************************************
  *
@@ -241,7 +241,7 @@ describe('9. columnMetadata.js', function() {
       await connection.execute(sqlDrop);
     });
 
-    it('9.10 works with a large number of columns', async function() {
+    it('9.3.1 works with a large number of columns', async function() {
       const column_size = 300;
       columns_string = genColumns(column_size, " NUMBER");
 
@@ -269,7 +269,7 @@ describe('9. columnMetadata.js', function() {
       await connection.execute(sqlDrop);
     });
 
-    it('9.11 works with re-executes with multiple packet response', async function() {
+    it('9.3.2 works with re-executes with multiple packet response', async function() {
       const column_size = 50;
       const numRows = 5;
       oracledb.fetchAsString = [oracledb.CLOB];

test/connection.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2015, 2023, Oracle and/or its affiliates. */
+/* Copyright (c) 2015, 2024, Oracle and/or its affiliates. */
 
 /******************************************************************************
  *
@@ -762,7 +762,14 @@ describe('1. connection.js', function() {
       }
 
       res = await conn2.execute(sqlDriverName);
-      assert.deepStrictEqual(res.rows[0][0], 'mydriver1');
+      /*
+        In Oracle 12.1 DB, The driver name (CLIENT_DRIVER column in V$SESSION_CONNECT_INFO view)
+        can be set only upto 8 characters.
+      */
+      let serverVersion = conn2.oracleServerVersion;
+      if (serverVersion < 1202000000)
+        assert.deepStrictEqual(res.rows[0][0], 'mydriver');
+      else assert.deepStrictEqual(res.rows[0][0], 'mydriver1');
 
       // Generate random values for the third connection
       const randomPgm3 = random.getRandomLengthString(16);
@@ -794,7 +801,14 @@ describe('1. connection.js', function() {
       }
 
       res = await conn3.execute(sqlDriverName);
-      assert.deepStrictEqual(res.rows[0][0], 'mydriver3');
+      /*
+        In Oracle 12.1 DB, The driver name (CLIENT_DRIVER column in V$SESSION_CONNECT_INFO view)
+        can be set only upto 8 characters.
+      */
+      serverVersion = conn2.oracleServerVersion;
+      if (serverVersion < 1202000000)
+        assert.deepStrictEqual(res.rows[0][0], 'mydriver');
+      else assert.deepStrictEqual(res.rows[0][0], 'mydriver3');
 
       // Cleanup
       await conn1.close();
@@ -817,7 +831,9 @@ describe('1. connection.js', function() {
       assert.strictEqual(res.rows[0][0], os.hostname());
       assert.strictEqual(res.rows[0][1], os.userInfo().username);
       assert.strictEqual(res.rows[0][2], 'unknown');
-      assert.strictEqual(res.rows[0][3], process.argv0);
+      // Whitespaces, ( and ) are replaced by ? for the program name
+      // in V$SESSION
+      assert.strictEqual(res.rows[0][3], process.argv0.replace(/[\s()]/g, '?'));
 
       if (dbConfig.test.drcp) {
         const bindParams = {
@@ -828,11 +844,20 @@ describe('1. connection.js', function() {
         res = await conn.execute(sqlDRCPSessionDetails, bindParams);
         assert.deepStrictEqual(res.rows[0][0], os.hostname());
         assert.deepStrictEqual(res.rows[0][1], 'unknown');
-        assert.deepStrictEqual(res.rows[0][2], process.argv0);
+        // Whitespaces, ( and ) are replaced by ? for the program name
+        // in V$SESSION
+        assert.deepStrictEqual(res.rows[0][2], process.argv0.replace(/[\s()]/g, '?'));
       }
 
       res = await conn.execute(sqlDriverName);
-      assert.strictEqual(res.rows[0][0], "node-oracledb : " + oracledb.versionString + " thn");
+      /*
+        In Oracle 12.1 DB, The driver name (CLIENT_DRIVER column in V$SESSION_CONNECT_INFO view)
+        can be set only upto 8 characters.
+      */
+      const serverVersion = conn.oracleServerVersion;
+      if (serverVersion < 1202000000)
+        assert.strictEqual(res.rows[0][0], "node-ora");
+      else assert.strictEqual(res.rows[0][0], "node-oracledb : " + oracledb.versionString + " thn");
 
       await conn.close();
     }); // 1.18.3