Thin mode support and new examples

Author: sharadraju

.npmignore

@@ -1,5 +1,6 @@
 .github
 .nycrc
+.gitattributes
 .gitmodules
 .eslintrc
 INSTALL.md
@@ -8,7 +9,9 @@ Makefile
 Makefile.win32
 *.tgz
 /doc
-/examples
+/examples/*
+!/examples/example.js
+!/examples/dbconfig.js
 /test
 /build/Release/oracledb.node
 /build/oracledb.target.mk
@@ -33,6 +36,5 @@ Makefile.win32
 /odpi/test
 /odpi/.git
 /odpi/.github
-/odpi/.gitattributes
 /odpi/util
 \#*

README.md

@@ -1,12 +1,12 @@
-# node-oracledb version 6.0.0-dev
+# node-oracledb version 6.0.0-dev6
 
 **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.0.0-dev to connect Node.js 14.6, or later, to Oracle
+Use node-oracledb 6.0.0-dev6 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/release_notes.rst

@@ -10,11 +10,33 @@ node-oracledb `v6.0.0 <https://github.com/oracle/node-oracledb/compare/v5.5.0...
 
 **This release is under development**
 
+#)  node-oracledb is now a 'Thin' driver by default that connects directly
+    to Oracle Database.  Optional use of Oracle Client libraries enables a
+    :ref:`'Thick' mode <enablingthick>` with some additional functionality.
+
+#)  Added a new ``oracledb.fetchTypeHandler`` and equivalent execution option
+    allowing a user function to be specified that can make custom alterations
+    to SQL query data before it is returned to the app.
+
+#)  Deprecated execution option attribute ``fetchInfo``.  Use the new
+    ``fetchTypeHandler`` functionality instead.
+
+#)  Changed ``oracledb.DB_TYPE_*`` constants to be ``DbType`` objects
+    instead of numbers.
+
+#)  Added support for the Oracle Database 23c BOOLEAN SQL type.
+
 #)  Bumped the minimum Node.js version required to 14.6 so Node-API version 6
     and ``FinalizationRegistry`` can be used in the driver implementation.
 
-#)  Re-licensed to dual Apache 2.0 or UPL 1.0 licenses, see `LICENSE.txt
-    <https://github.com/oracle/node-oracledb/blob/main/LICENSE.txt>`__.
+#)  Allow ``package/prunebinaries.js`` to optionally remove all the Thick mode
+    binaries to enable a Thin-mode only installation.
+
+#)  Allow ``npm run buildpackage`` to create a package without Thick mode
+    binaries.
+
+#)  Re-licensed to dual Apache 2.0 or UPL 1.0 licenses, see
+    `LICENSE.txt <https://github.com/oracle/node-oracledb/blob/main/LICENSE.txt>`__.
 
 #)  Internal change: reorganized code to move functionality from C to JavaScript.
 

examples/README.md

@@ -1,27 +1,19 @@
 # Node-oracledb Examples
 
-This directory contains [node-oracledb](https://www.npmjs.com/package/oracledb)
+The directory in node-oracledb's [Github repository](https://github.com/oracle/node-oracledb/tree/main/examples) contains a lot of [node-oracledb](https://www.npmjs.com/package/oracledb)
 examples.  Documentation is
 [here](https://node-oracledb.readthedocs.io/en/latest/).
 
 To run the examples:
 
 - [Install node-oracledb](https://node-oracledb.readthedocs.io/en/latest/user_guide/installation.html#quickstart).
 
-- Edit `dbconfig.js` and set your username and the database connection string,
-  for example:
+- Ensure that you navigate to the `examples` directory in your terminal window
+  or IDE, where you are running the samples.
 
-  ```
-  module.exports = {
-      user: "hr",
-      password: process.env.NODE_ORACLEDB_PASSWORD,
-      connectString:"localhost/orclpdb1"
-  };
-
-  ```
-
-- In a terminal window, set the environment variable `NODE_ORACLEDB_PASSWORD` to
-  the value of your database password.
+- Review `dbconfig.js`.  In your terminal window or IDE, set the environment
+  variables.  For example, set `NODE_ORACLEDB_PASSWORD` to the value of your
+  database password.
 
 - Review the samples and then run them individually.  For example, to see what
   the file `example.js` does, use:
@@ -37,6 +29,11 @@ To run the examples:
   node demodrop.js
   ```
 
+Many examples can be run in either node-oracledb Thin (the default) or Thick
+modes.  Thin mode is a pure JavaScript implementation of node-oracledb.
+Setting the environment variable `NODE_ORACLEDB_DRIVER_MODE` to `'thick'` will
+change node-oracledb to use Thick mode.
+
 ## Example Overview
 
 If this is your first time with node-oracledb, start with
@@ -70,7 +67,6 @@ File Name                                                 | Description
 [`em_rowcounts.js`](em_rowcounts.js)                      | `executeMany()` example showing how to find the number of rows affected by each input row
 [`endtoend.js`](endtoend.js)                              | Example showing setting tracing attributes
 [`example.js`](example.js)                                | Basic example showing creating a table, inserting multiple rows, and querying rows
-[`fetchinfo.js`](fetchinfo.js)                            | Show how numbers and dates can be returned as strings using `fetchAsString` and `fetchInfo`
 [`impres.js`](impres.js)                                  | Shows PL/SQL 'Implict Results' returning multiple query results from PL/SQL code.
 [`insert1.js`](insert1.js)                                | Basic example creating a table and inserting data.  Shows DDL and DML
 [`insert2.js`](insert2.js)                                | Basic example showing auto commit behavior
@@ -83,6 +79,7 @@ File Name                                                 | Description
 [`lobselect.js`](lobselect.js)                            | Shows basic, non-streaming CLOB and BLOB queries
 [`lobstream1.js`](lobstream1.js)                          | Shows how to stream LOBs to files
 [`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
 [`plsqlarray.js`](plsqlarray.js)                          | Examples of binding PL/SQL "INDEX BY" tables
 [`plsqlfunc.js`](plsqlfunc.js)                            | How to call a PL/SQL function
@@ -109,5 +106,7 @@ File Name                                                 | Description
 [`sessiontagging1.js`](sessiontagging1.js)                | Simple pooled connection tagging for setting session state
 [`sessiontagging2.js`](sessiontagging2.js)                | More complex example of pooled connection tagging for setting session state
 [`soda1.js`](soda1.js)                                    | Basic Simple Oracle Document Access (SODA) example
+[`typehandlerdate.js`](typehandlerdate.js)                | Show how a type handler can format a queried date in a locale-specific way
+[`typehandlernum.js`](typehandlernum.js)                  | Show how a type handler can format a queried number in a locale-specific way
 [`version.js`](version.js)                                | Shows the node-oracledb version attributes
 [`webapp.js`](webapp.js)                                  | A simple web application using a connection pool

examples/aqmulti.js

@@ -31,30 +31,32 @@
  *   Before running this, a queue allowing RAW payloads must be
  *   created, see https://node-oracledb.readthedocs.io/en/latest/user_guide/aq.html#aqrawexample
  *
- *   This example requires node-oracledb 4 or later.
- *
- *   This example uses Node 8's async/await syntax.
- *
  *****************************************************************************/
 
-const fs = require('fs');
+'use strict';
+
+Error.stackTraceLimit = 50;
+
 const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 
-// On Windows and macOS, you can specify the directory containing the Oracle
-// Client Libraries at runtime, or before Node.js starts.  On other platforms
-// the system library search path must always be set before Node.js is started.
-// See the node-oracledb installation documentation.
-// If the search path is not correct, you will get a DPI-1047 error.
-let libPath;
-if (process.platform === 'win32') {           // Windows
-  libPath = 'C:\\oracle\\instantclient_19_12';
-} else if (process.platform === 'darwin') {   // macOS
-  libPath = process.env.HOME + '/Downloads/instantclient_19_8';
-}
-if (libPath && fs.existsSync(libPath)) {
-  oracledb.initOracleClient({ libDir: libPath });
+
+// This example requires node-oracledb Thick mode.
+//
+// Thick mode requires Oracle Client or Oracle Instant Client libraries.  On
+// Windows and macOS Intel you can specify the directory containing the
+// libraries at runtime or before Node.js starts.  On other platforms (where
+// Oracle libraries are available) the system library search path must always
+// include the Oracle library path before Node.js starts.  If the search path
+// is not correct, you will get a DPI-1047 error.  See the node-oracledb
+// installation documentation.
+let clientOpts = {};
+if (process.platform === 'win32') {                                   // Windows
+  clientOpts = { libDir: 'C:\\oracle\\instantclient_19_17' };
+} else if (process.platform === 'darwin' && process.arch === 'x64') { // macOS Intel
+  clientOpts = { libDir: process.env.HOME + '/Downloads/instantclient_19_8' };
 }
+oracledb.initOracleClient(clientOpts);  // enable node-oracledb Thick mode
 
 const queueName = "DEMO_RAW_QUEUE";
 
@@ -66,7 +68,7 @@ async function enq() {
     const queue = await connection.getQueue(queueName);
     queue.enqOptions.visibility = oracledb.AQ_VISIBILITY_IMMEDIATE; // Send a message without requiring a commit
 
-    console.log('Enqueuing messages');
+    console.log('Enqueuing 4 messages');
 
     const messages = [
       "Message 1",

examples/aqobject.js

@@ -32,30 +32,31 @@
  *   payload must be created, see
  *   https://node-oracledb.readthedocs.io/en/latest/user_guide/aq.html#aqobjexample
  *
- *   This example requires node-oracledb 4 or later.
- *
- *   This example uses Node 8's async/await syntax.
- *
  *****************************************************************************/
 
-const fs = require('fs');
+'use strict';
+
+Error.stackTraceLimit = 50;
+
 const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 
-// On Windows and macOS, you can specify the directory containing the Oracle
-// Client Libraries at runtime, or before Node.js starts.  On other platforms
-// the system library search path must always be set before Node.js is started.
-// See the node-oracledb installation documentation.
-// If the search path is not correct, you will get a DPI-1047 error.
-let libPath;
-if (process.platform === 'win32') {           // Windows
-  libPath = 'C:\\oracle\\instantclient_19_12';
-} else if (process.platform === 'darwin') {   // macOS
-  libPath = process.env.HOME + '/Downloads/instantclient_19_8';
-}
-if (libPath && fs.existsSync(libPath)) {
-  oracledb.initOracleClient({ libDir: libPath });
+// This example requires node-oracledb Thick mode.
+//
+// Thick mode requires Oracle Client or Oracle Instant Client libraries.  On
+// Windows and macOS Intel you can specify the directory containing the
+// libraries at runtime or before Node.js starts.  On other platforms (where
+// Oracle libraries are available) the system library search path must always
+// include the Oracle library path before Node.js starts.  If the search path
+// is not correct, you will get a DPI-1047 error.  See the node-oracledb
+// installation documentation.
+let clientOpts = {};
+if (process.platform === 'win32') {                                   // Windows
+  clientOpts = { libDir: 'C:\\oracle\\instantclient_19_17' };
+} else if (process.platform === 'darwin' && process.arch === 'x64') { // macOS Intel
+  clientOpts = { libDir: process.env.HOME + '/Downloads/instantclient_19_8' };
 }
+oracledb.initOracleClient(clientOpts);  // enable node-oracledb Thick mode
 
 const queueName = "ADDR_QUEUE";
 

examples/aqoptions.js

@@ -31,30 +31,31 @@
  *   Before running this, a queue allowing RAW payloads must be created, see
  *   https://node-oracledb.readthedocs.io/en/latest/user_guide/aq.html#aqrawexample
  *
- *   This example requires node-oracledb 4 or later.
- *
- *   This example uses Node 8's async/await syntax.
- *
  *****************************************************************************/
 
-const fs = require('fs');
+'use strict';
+
+Error.stackTraceLimit = 50;
+
 const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 
-// On Windows and macOS, you can specify the directory containing the Oracle
-// Client Libraries at runtime, or before Node.js starts.  On other platforms
-// the system library search path must always be set before Node.js is started.
-// See the node-oracledb installation documentation.
-// If the search path is not correct, you will get a DPI-1047 error.
-let libPath;
-if (process.platform === 'win32') {           // Windows
-  libPath = 'C:\\oracle\\instantclient_19_12';
-} else if (process.platform === 'darwin') {   // macOS
-  libPath = process.env.HOME + '/Downloads/instantclient_19_8';
-}
-if (libPath && fs.existsSync(libPath)) {
-  oracledb.initOracleClient({ libDir: libPath });
+// This example requires node-oracledb Thick mode.
+//
+// Thick mode requires Oracle Client or Oracle Instant Client libraries.  On
+// Windows and macOS Intel you can specify the directory containing the
+// libraries at runtime or before Node.js starts.  On other platforms (where
+// Oracle libraries are available) the system library search path must always
+// include the Oracle library path before Node.js starts.  If the search path
+// is not correct, you will get a DPI-1047 error.  See the node-oracledb
+// installation documentation.
+let clientOpts = {};
+if (process.platform === 'win32') {                                   // Windows
+  clientOpts = { libDir: 'C:\\oracle\\instantclient_19_17' };
+} else if (process.platform === 'darwin' && process.arch === 'x64') { // macOS Intel
+  clientOpts = { libDir: process.env.HOME + '/Downloads/instantclient_19_8' };
 }
+oracledb.initOracleClient(clientOpts);  // enable node-oracledb Thick mode
 
 const queueName = "DEMO_RAW_QUEUE";
 

examples/aqraw.js

@@ -31,30 +31,31 @@
  *   Before running this, a queue allowing RAW payloads must be created, see
  *   https://node-oracledb.readthedocs.io/en/latest/user_guide/aq.html#aqrawexample
  *
- *   This example requires node-oracledb 4 or later.
- *
- *   This example uses Node 8's async/await syntax.
- *
  *****************************************************************************/
 
-const fs = require('fs');
+'use strict';
+
+Error.stackTraceLimit = 50;
+
 const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 
-// On Windows and macOS, you can specify the directory containing the Oracle
-// Client Libraries at runtime, or before Node.js starts.  On other platforms
-// the system library search path must always be set before Node.js is started.
-// See the node-oracledb installation documentation.
-// If the search path is not correct, you will get a DPI-1047 error.
-let libPath;
-if (process.platform === 'win32') {           // Windows
-  libPath = 'C:\\oracle\\instantclient_19_12';
-} else if (process.platform === 'darwin') {   // macOS
-  libPath = process.env.HOME + '/Downloads/instantclient_19_8';
-}
-if (libPath && fs.existsSync(libPath)) {
-  oracledb.initOracleClient({ libDir: libPath });
+// This example requires node-oracledb Thick mode.
+//
+// Thick mode requires Oracle Client or Oracle Instant Client libraries.  On
+// Windows and macOS Intel you can specify the directory containing the
+// libraries at runtime or before Node.js starts.  On other platforms (where
+// Oracle libraries are available) the system library search path must always
+// include the Oracle library path before Node.js starts.  If the search path
+// is not correct, you will get a DPI-1047 error.  See the node-oracledb
+// installation documentation.
+let clientOpts = {};
+if (process.platform === 'win32') {                                   // Windows
+  clientOpts = { libDir: 'C:\\oracle\\instantclient_19_17' };
+} else if (process.platform === 'darwin' && process.arch === 'x64') { // macOS Intel
+  clientOpts = { libDir: process.env.HOME + '/Downloads/instantclient_19_8' };
 }
+oracledb.initOracleClient(clientOpts);  // enable node-oracledb Thick mode
 
 const queueName = "DEMO_RAW_QUEUE";