Some housekeeping for examples, tests and documentation

Author: sharadraju

README.md

@@ -1,12 +1,12 @@
 # node-oracledb version 6.7.0-dev
 
-+**This release is under development and information may be incomplete**
+**This release is under development and information may be incomplete**
 
 The node-oracledb add-on for Node.js powers high performance Oracle Database
 applications.  Applications can be written in TypeScript, or directly in
 JavaScript.
 
-Use node-oracledb 6.6.0 to connect Node.js 14.6, or later, to Oracle
+Use node-oracledb 6.7.0-dev to connect Node.js 14.6, or later, to Oracle
 Database.  Older versions of node-oracledb may work with older versions of
 Node.js.
 

doc/src/user_guide/connection_handling.rst

@@ -4088,15 +4088,13 @@ required authorization permissions to access the Azure App Configuration
 provider.
 
 To use node-oracledb to retrieve the configuration information from Azure App
-Configuration, you must install the following libraries:
-
-- `App Configuration <https://www.npmjs.com/package/@azure/
-  app-configuration>`__ (azure/app-configuration)
-- `Azure AD token authentication <https://www.npmjs.com/package/@azure/
-  identity>`__ (azure/identity)
-- `Azure Key Vault <https://www.npmjs.com/package/@azure/keyvault-secrets>`__
-  (azure/keyvault-secrets) is optional and required only if a password is
-  stored in the vault
+Configuration, you must install certain Microsoft Azure libraries which
+include `Azure App Configuration <https://www.npmjs.com/package/@azure/app-
+configuration>`__ and `Azure Identity <https://www.npmjs.com/package/@azure/
+identity>`__. Optionally, you must install `Azure Key Vault <https://www.
+npmjs.com/package/@azure/keyvault-secrets>`__ which is required only if a
+password is stored in the vault. For installation instructions of these
+libraries, see :ref:`azuremodules`.
 
 Configuration information is stored as key-value pairs in Azure App
 Configuration. You must add the connect descriptor as a key under a prefix
@@ -4384,17 +4382,13 @@ of your application's configuration information. Ensure that you have the
 necessary authorization permissions to access OCI Object Storage.
 
 To use node-oracledb to retrieve the configuration information from OCI Object
-Storage, you must install the following:
-
-- `OCI Node.js Client for Common Utilities <https://www.npmjs.com/package/
-  oci-common>`__ (oci-common)
-- `OCI Node.js Client for ObjectStorage Service <https://www.npmjs.com/package/
-  oci-objectstorage>`__ (oci-objectstorage)
-- `OCI Node.js Client for Secrets Service <https://www.npmjs.com/package/oci-
-  secrets>`__ (oci-secrets) is optional and required only if a password is
-  stored in the vault. See `Managing Vault Secrets <https://docs.oracle.com/en
-  -us/iaas/Content/KeyManagement/Tasks/managingsecrets.htm>`__ for more
-  information.
+Storage, you must install certain OCI libraries which include `OCI Node.js
+Client for Common Utilities <https://www.npmjs.com/package/oci-common>`__ and
+`OCI Node.js Client for ObjectStorage Service <https://www.npmjs.com/package/
+oci-objectstorage>`__. Optionally, you must install `OCI Node.js Client for
+Secrets Service <https://www.npmjs.com/package/oci-secrets>`__ which is
+required only if a password is stored in the vault. For installation
+instructions of these libraries, see :ref:`ocimodules`.
 
 Configuration information is stored as a JSON file in OCI Object Storage. You
 must add the connect descriptor in the JSON file. Optionally, you can add the

doc/src/user_guide/installation.rst

@@ -1644,3 +1644,74 @@ The output is like::
 
     { metaData: [ { name: 'D' } ],
       rows: [ { D: '24-Nov-2019 23:39' } ] }
+
+.. _configproviderlibraries:
+
+Installing Configuration Provider Modules for node-oracledb
+===========================================================
+
+To use node-oracledb with
+:ref:`centralized configuration providers <configurationprovider>`, you must
+install the necessary modules for your preferred configuration provider as
+detailed below.
+
+.. _azuremodules:
+
+Install Modules for Azure App Configuration Provider
+----------------------------------------------------
+
+For node-oracledb to work with Azure App Configuration Provider, you must
+install the following Microsoft Azure modules:
+
+1. Install the `Azure App Configuration <https://www.npmjs.com/package/@azure/
+   app-configuration>`__ module using::
+
+        npm install @azure/app-configuration
+
+2. Install the `Azure Identity <https://www.npmjs.com/package/
+   @azure/identity>`__ module using::
+
+        npm install @azure/identity
+
+   This library offers a variety of credential classes capable of acquiring
+   Microsoft Entra ID (formerly Azure Active Directory) token to authenticate
+   service requests.
+
+3. Optionally, you need to install the `Azure Key Vault <https://www.npmjs.
+   com/package/@azure/keyvault-secrets>`__ module if a password is stored in
+   the Azure Key vault. This can be done using::
+
+        npm install @azure/keyvault-secrets
+
+See :ref:`azureappconfig` for information on using this configuration provider
+with node-oracledb.
+
+.. _ocimodules:
+
+Install Modules for OCI Object Storage Configuration Provider
+-------------------------------------------------------------
+
+For node-oracledb to work with OCI Object Storage configuration provider, you
+must install the following OCI modules:
+
+1. Install the `OCI Node.js Client for Common Utilities <https://www.npmjs.
+   com/package/oci-common>`__ module using::
+
+        npm install oci-common
+
+2. Install the `OCI Node.js Client for ObjectStorage Service <https://www.
+   npmjs.com/package/oci-objectstorage>`__ module using::
+
+        npm install oci-objectstorage
+
+3. Optionally, you need to install the `OCI Node.js Client for Secrets Service
+   <https://www.npmjs.com/package/oci-secrets>`__ module if a password is
+   stored in the OCI vault. This can be done by using::
+
+        npm install oci-secrets
+
+   See `Managing Vault Secrets <https://docs.oracle.com/en-us/iaas/Content/
+   KeyManagement/Tasks/managingsecrets.htm>`__ for more information.
+
+See :ref:`ociobjstorage` for information on using this configuration provider
+with node-oracledb.

examples/README.md

@@ -65,6 +65,7 @@ File Name                                                 | Description
 [`aqraw.js`](aqraw.js)                                    | Basic Oracle Advanced Queuing (AQ) example passing text messages
 [`aqutil.js`](aqutil.js)                                  | Common file to setup the user credentials for all the Advanced Queuing (AQ) examples.
 [`blobhttp.js`](blobhttp.js)                              | Simple web app that streams an image
+[`azureConfigProvider.js`](azureConfigProvider.js)        | Show how to connect to an Oracle Database using Azure Configuration Providers
 [`calltimeout.js`](calltimeout.js)                        | Shows how to cancel a SQL statement if it doesn't complete in a specified time
 [`connect.js`](connect.js)                                | Basic example for creating a standalone (non-pooled) connection
 [`connectionpool.js`](connectionpool.js)                  | Basic example creating a pool of connections
@@ -101,6 +102,7 @@ File Name                                                 | Description
 [`lobstream2.js`](lobstream2.js)                          | Shows using Stream data events to fetch a CLOB
 [`lowercasecolumns.js`](lowercasecolumns.js)              | Shows how a type handler can convert column names to lower case
 [`metadata.js`](metadata.js)                              | Shows the metadata available after executing SELECT statements
+[`ociConfigProvider.js`](ociConfigProvider.js)            | Show how to connect to an Oracle Database using OCI Configuration Providers
 [`plsqlarray.js`](plsqlarray.js)                          | Examples of binding PL/SQL "INDEX BY" tables
 [`plsqlfunc.js`](plsqlfunc.js)                            | How to call a PL/SQL function
 [`plsqlproc.js`](plsqlproc.js)                            | How to call a PL/SQL procedure

examples/azureProviderSample.js renamed to examples/azureConfigProvider.js

@@ -23,12 +23,12 @@
  * limitations under the License.
  *
  * NAME
- *   azureProviderSample.js
+ *   azureConfigProvider.js
  *
  * DESCRIPTION
- *   Sample program to connect to the database using DB connectstring, username and password
- *   which are fetched from the Azure Configuration Store using the connectstring which consists of
- *   required parameters to authenticate azure configuration store.
+ *   Sample program to connect to the database using DB connect string,
+ *   username and password fetched from the Azure Configuration Providers
+ *   using the Azure Configuration Store URL.
  *
  *****************************************************************************/
 
@@ -62,7 +62,9 @@ if (process.env.NODE_ORACLEDB_DRIVER_MODE === 'thick') {
 console.log(oracledb.thin ? 'Running in thin mode' : 'Running in thick mode');
 
 async function run() {
-  // replace xxxx with the corresponding values of the parameter
+  // Replace the connect string with correct Azure Config Store URL
+  // Replace xxxx with the corresponding values of the authentication
+  // parameters
   let connection;
   const options = {
     connectString: 'config-azure://testappconfig.azconfig.io/?key=testapp/testkey/&azure_client_id=xxxx&azure_client_certificate_path=xxxx&azure_tenant_id=xxxx'

examples/ociProviderSample.js renamed to examples/ociConfigProvider.js

@@ -23,12 +23,12 @@
  * limitations under the License.
  *
  * NAME
- *   ociProviderSample.js
+ *   ociConfigProvider.js
  *
  * DESCRIPTION
- *   Sample program to connect to the database using DB connectstring, username and password
- *   which are fetched from the OCI Object Store using the connectstring which consists of
- *   required parameters to authenticate OCI Object Store.
+ *   Sample program to connect to the database using DB connect string,
+ *   username and password fetched from the OCI Configuration Providers
+ *   using the OCI Object Store Connect String URL.
  *
  *****************************************************************************/
 
@@ -62,10 +62,11 @@ if (process.env.NODE_ORACLEDB_DRIVER_MODE === 'thick') {
 console.log(oracledb.thin ? 'Running in thin mode' : 'Running in thick mode');
 
 async function run() {
-  //replace xxxx with correct values of the parameter
+  // Replace the connect string with correct OCI Config Store URL
+  // Replace xxxx in the connect string with the correct authentication parameter values
   let connection;
   const options = {
-    connectString: 'config-ociobject://test.us-phoenix-1.oraclecloud.com/n/testnamespace/b/testbucket/o/testobject?oci_tenancy=xxxx&oci_user=xxxx&oci_fingerprint=xxxx&oci_key_file=xxxx',
+    connectString: 'config-ociobject://test.region.oraclecloud.com/n/testnamespace/b/testbucket/o/testobject?oci_tenancy=xxxx&oci_user=xxxx&oci_fingerprint=xxxx&oci_key_file=xxxx',
   };
   try {
     // Get a non-pooled connection

examples/selectjson.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2015, 2023, Oracle and/or its affiliates. */
+/* Copyright (c) 2015, 2024, Oracle and/or its affiliates. */
 
 /******************************************************************************
  *
@@ -87,7 +87,7 @@ async function run() {
         console.error(e);
     }
 
-    connection.execute(`CREATE TABLE no_purchaseorder (po_document JSON)`);
+    await connection.execute(`CREATE TABLE no_purchaseorder (po_document JSON)`);
 
     console.log('2. Inserting Data');
 

test/binding_DMLInsert.js

@@ -103,7 +103,8 @@ describe('92.binding_DMLInsert.js', function() {
               await connection.execute("insert into " + table_name + " ( content ) values (:c)", bindVar);
             },
             // ORA-01877: string is too long for internal buffer
-            /ORA-01877:/
+            // ORA-01866: the datetime class is invalid
+            /ORA-01877:|ORA-01866:/
           );
         }
         if (dbColType === "BLOB" || dbColType.indexOf("RAW") > -1) {