Test and Documentation updates for 6.3 features

doc/src/api_manual/connection.rst

@@ -342,6 +342,32 @@ The properties of a *Connection* object are listed below.
     value is *False*, then the specified connection does not have an active
     transaction.
 
+.. attribute:: connection.warning
+
+    .. versionadded:: 6.3
+
+    This read-only property provides an :ref:`error <errorobj>` object that
+    gives information about any database warnings (such as password being in
+    the grace period) that were generated during
+    :meth:`connection establishment <oracledb.getConnection()>` (both
+    standalone connections and pooled connections). This attribute is present
+    if a warning is thrown by the database but the operation is otherwise
+    completed successfully. The connection will be usable despite the warning.
+
+    For :ref:`standalone connections <standaloneconnection>`, the error object
+    returned by ``connection.warning`` will be present for the lifetime of the
+    connection.
+
+    For :ref:`pooled connections <connpooling>`, the error object returned by
+    ``connection.warning`` will be cleared when a connection is released to
+    the pool using :meth:`connection.close()`.
+
+    In node-oracledb Thick mode, warnings may be generated during pool
+    creation itself. These warnings will be placed on the new connections
+    created by the pool, provided no warnings were generated by the individual
+    connection creations, in which case those connection warnings will be
+    returned.
+
 .. _connectionmethods:
 
 Connection Methods
@@ -1120,6 +1146,14 @@ Connection Methods
             This property is a number. For `DML <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-2E008D4A-F6FD-4F34-9071-7E10419CA24D>`__ statements this contains the number of rows affected, for example the number of rows inserted. For non-DML statements such as queries and PL/SQL statements, ``rowsAffected`` is undefined.
 
             Due to Node.js type limitations, the largest value shown will be 232 - 1, even if more rows were affected. Larger values will wrap.
+        * - ``warning``
+          - .. _execwarning:
+
+            This property provides an :ref:`error <errorobj>` object that gives information about any database warnings (such as PL/SQL compilation warnings) that were generated during the last call to :meth:`connection.execute()`.
+
+            See :ref:`plsqlcompwarnings` for more information.
+
+            .. versionadded:: 6.3
 
 .. method:: connection.executeMany()
 
@@ -1365,6 +1399,15 @@ Connection Methods
             It is only present if a DML statement was executed.
 
             Due to Node.js type limitations, the largest value shown will be 232 - 1, even if more rows were affected. Larger values will wrap.
+        * - ``warning``
+          - Object
+          - .. _execmanywarning:
+
+            This property provides an :ref:`error <errorobj>` object that gives information about any database warnings (such as PL/SQL compilation warnings) that were generated during the last call to :meth:`connection.executeMany()`.
+
+            See :ref:`plsqlcompwarnings` for more information.
+
+            .. versionadded:: 6.3
 
 .. method:: connection.getDbObjectClass()
 

doc/src/release_notes.rst

@@ -13,12 +13,16 @@ node-oracledb `v6.3.0 <https://github.com/oracle/node-oracledb/compare/v6.2.0...
 Common Changes
 ++++++++++++++
 
-#)  Added a ``warning`` property to the ``result`` object for database
-    warnings (such as PL/SQL compilation warnings) generated by calls to
-    :meth:`connection.execute()` or :meth:`connection.executeMany()`.
-
-#)  Added property :attr:`connection.warning` for warnings (such as the
-    password being in the grace period) generated during connection.
+#)  Added a :ref:`warning <execwarning>` property to the
+    :ref:`result <resultobject>` object for database warnings (such as PL/SQL
+    compilation warnings) that are generated by calls to
+    :meth:`connection.execute()`. Also, added the
+    :ref:`warning <execmanywarning>` property to the
+    :ref:`result <resultobjproperties>` object of
+    :meth:`connection.executeMany()`.
+
+#)  Added a :attr:`connection.warning` property for warnings (such as the
+    password being in the grace period) that are generated during connection.
 
 #)  VARCHAR2 and LOB columns which contain JSON, and have the "IS JSON" check
     constraint enabled, can now be fetched in the same way as columns of type

doc/src/user_guide/migrate.rst

@@ -4,6 +4,65 @@
 Upgrading to the Latest node-oracledb Releases
 **********************************************
 
+.. _upgradev62v63:
+
+Upgrading from node-oracledb 6.2 to 6.3
+=======================================
+
+- Review the :ref:`releasenotes` and take advantage of new features.
+
+- Using the new :ref:`warning <execwarning>` property of the
+  :ref:`result object <resultobject>` in :meth:`connection.execute()`, your
+  application can manually check for database warnings such as
+  :ref:`plsqlcompwarnings`. Also, you can use the new
+  :ref:`warning <execmanywarning>` property in the
+  :ref:`result object <resultobjproperties>` of
+  :meth:`connection.executeMany()` to check for similar warnings.
+
+- The new :attr:`connection.warning` property can be used to check for
+  warnings that are generated during connection such as the password being in
+  the grace period.
+
+- By setting the new :attr:`oracledb.future.oldJsonColumnAsObj` property to
+  *true*, you can fetch the VARCHAR2 and LOB columns which contain JSON in the
+  same way as :ref:`columns of type JSON <json21fetch>`. See
+  :ref:`json12ctype` for more information. In a future version of
+  node-oracledb, the setting of this attribute will no longer be required
+  since this will become the default behavior.
+
+- With the new :ref:`oracledb.DB_TYPE_XMLTYPE <oracledbconstantsdbtype>`
+  constant, you can now represent data of type ``SYS.XMLTYPE`` in the
+  ``fetchType`` and ``dbType`` :ref:`metadata <execmetadata>` information
+  attributes.
+
+- node-oracledb now supports using Azure and Oracle Cloud Infrastructure (OCI)
+  Software Development Kits (SDKs) to generate
+  :ref:`authentication tokens <tokenbasedauthentication>`.
+
+- With the new connection properties :attr:`connection.dbDomain`,
+  :attr:`connection.dbName`, :attr:`connection.maxOpenCursors`,
+  :attr:`connection.serviceName` and :attr:`connection.transactionInProgress`,
+  you can identify the database domain name, database instance name, maximum
+  number of cursors that can be opened per connection, database service name,
+  and status of any ongoing transactions on the connection respectively.
+
+- The new :ref:`metadata <execmetadata>` information attribute ``isJson``
+  indicates whether the fetched column contains JSON data.
+
+- The new :ref:`metadata <execmetadata>` information attributes
+  ``annotations``, ``domainName``, and ``domainSchema`` identifies the
+  `annotations <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
+  GUID-1AC16117-BBB6-4435-8794-2B99F8F68052>`__ object, the name of the
+  `SQL domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
+  GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`_, and the schema name of the
+  `SQL domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
+  GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ associated with the fetched
+  column. Annotations and SQL domains are supported from Oracle Database 23c
+  onwards. For node-oracledb Thick mode, Oracle Client 23c is also required.
+
+- In node-oracledb Thin mode, ``SYS.XMLTYPE`` data can now be
+  :ref:`fetched as strings <xmltype>`.
+
 .. _upgradev61v62:
 
 Upgrading from node-oracledb 6.1 to 6.2

doc/src/user_guide/plsql_execution.rst

@@ -446,18 +446,27 @@ tree/main/examples/plsqlproc.js>`__ and `plsqlfunc.js
 PL/SQL Compilation Warnings
 ---------------------------
 
-When creating PL/SQL procedures and functions in node-oracledb,
-compilation warnings must be manually checked for. This can be done by
-querying ``USER_ERRORS`` like:
+When creating PL/SQL procedures and functions (or creating types) in
+node-oracledb using SQL statements, the statement might succeed without
+throwing an error, but there may be additional informational messages. (These
+messages are sometimes known in Oracle as "success with info" messages). Your
+application can manually check for these messages using the
+:ref:`warning <execwarning>` property of the
+:ref:`result object <resultobject>` in :meth:`connection.execute()` or
+:meth:`connection.executemany()`. A subsequent query from a table like
+``USER_ERRORS`` will show more details. For example:
 
 .. code-block:: javascript
 
-    await connection.execute(
+    const result = await connection.execute(
         `CREATE OR REPLACE PROCEDURE badproc AS
         BEGIN
             INVALID
         END;`);
 
+    if (result.warning && result.warning.code == "NJS-700")
+        console.log(result.warning.message)
+
     const r = await connection.execute(
         `SELECT line, position, text
         FROM user_errors
@@ -471,8 +480,20 @@ querying ``USER_ERRORS`` like:
         console.error('at line', r.rows[0].LINE, 'position', r.rows[0].POSITION);
     }
 
-Output is like::
+In node-oracledb Thin mode, the output would be::
+
+    NJS-700: creation succeeded with compilation errors
+    PLS-00103: Encountered the symbol "END" when expecting one of the following:
+
+        := . ( @ % ;
+    The symbol ";" was substituted for "END" to continue.
+
+    at line 4 position 8
+
+In node-oracledb Thick mode, the output would be::
 
+    NJS-700: creation succeeded with compilation errors
+    ORA-24344: success with compilation error
     PLS-00103: Encountered the symbol "END" when expecting one of the following:
 
         := . ( @ % ;

test/dbObject4.js

@@ -37,7 +37,7 @@ const dbConfig  = require('./dbconfig.js');
 const testsUtil = require('./testsUtil.js');
 
 describe('203. dbObject4.js', () => {
-  let conn;
+  let conn, testCount = 0;
   const TYPE = 'NODB_TYP_OBJ_4';
   const TABLE  = 'NODB_TAB_OBJ4';
 
@@ -106,7 +106,13 @@ describe('203. dbObject4.js', () => {
     await conn.close();
   }); // after()
 
-  it('203.1 insert an object with LTZ type attribute', async () => {
+  it('203.1 insert an object with LTZ type attribute', async function() {
+    /*
+     * The Oracle Instant Client version should be 19.20 or greater as there is a
+     * bug in setting the timezone with the lower Oracle Instant Client versions.
+    */
+    const isRunnable = await testsUtil.checkPrerequisites(1920000000, undefined);
+    if (!isRunnable) this.skip();
     const seq = 101;
     let sql = `INSERT INTO ${TABLE} VALUES (:1, :2)`;
 
@@ -129,6 +135,7 @@ describe('203. dbObject4.js', () => {
     assert.strictEqual(result.rows[0][1]['ENTRY'].getTime(), date1.getTime());
     assert.strictEqual(result.rows[0][1]['EXIT'].getTime(), date2.getTime());
     assert.strictEqual(result.rows[0][0], seq);
+    testCount++;
   }); // 203.1
 
   it('203.2 insert null value for LTZ type attribute', async () => {
@@ -152,6 +159,7 @@ describe('203. dbObject4.js', () => {
     assert.strictEqual(result.rows[0][1]['ENTRY'], null);
     assert.strictEqual(result.rows[0][1]['EXIT'], null);
     assert.strictEqual(result.rows[0][0], seq);
+    testCount++;
   }); // 203.2
 
   it('203.3 insert undefined value for LTZ type attribute', async () => {
@@ -175,6 +183,7 @@ describe('203. dbObject4.js', () => {
     assert.strictEqual(result.rows[0][1]['ENTRY'], null);
     assert.strictEqual(result.rows[0][1]['EXIT'], null);
     assert.strictEqual(result.rows[0][0], seq);
+    testCount++;
   }); // 203.3
 
   it('203.4 insert an empty JSON', async () => {
@@ -193,6 +202,7 @@ describe('203. dbObject4.js', () => {
 
     assert.strictEqual(result.rows[0][1]['ENTRY'], null);
     assert.strictEqual(result.rows[0][1]['EXIT'], null);
+    testCount++;
   }); // 203.4
 
   it('203.5 call procedure with 2 OUT binds of DbObject', async function() {
@@ -207,11 +217,11 @@ describe('203. dbObject4.js', () => {
     );
 
     let resultSet = await result.outBinds.p_cur1.getRows();
-    assert.equal(resultSet.length, 4);
+    assert.equal(resultSet.length, testCount);
     result.outBinds.p_cur1.close();
 
     resultSet = await result.outBinds.p_cur2.getRows();
-    assert.equal(resultSet.length, 4);
+    assert.equal(resultSet.length, testCount);
     result.outBinds.p_cur2.close();
   }); // 203.5;