Update node-oracledb examples for the latest 3.1 release

javascript/node-oracledb/README.md

@@ -1,6 +1,6 @@
 # Node-oracledb Examples
 
-This directory contains [node-oracledb 3.0](https://www.npmjs.com/package/oracledb) examples.
+This directory contains [node-oracledb 3.1](https://www.npmjs.com/package/oracledb) examples.
 
 The node-oracledb add-on for Node.js powers high performance Oracle Database applications.
 
@@ -11,7 +11,7 @@ The node-oracledb add-on for Node.js powers high performance Oracle Database app
 Issues and questions about node-oracledb can be posted on
 [GitHub](https://github.com/oracle/node-oracledb/issues) or
 [Slack](https://node-oracledb.slack.com/) ([link to join
-Slack](https://join.slack.com/t/node-oracledb/shared_invite/enQtNDI4NTUyNjMzMDA5LWRiZWRkZjQ3NjBhNDUwOGJlNDFiZWJhZTIzYTJkMWQ5N2UwNTg5NzNmNmY1YmZjZGYxNmRhOTkyOTlhMmViNjY)).
+Slack](https://node-oracledb.slack.com/join/shared_invite/enQtNDU4Mjc2NzM5OTA2LTdkMzczODY3OGY3MGI0Yjk3NmQ4NDU4MTI2OGVjNTYzMjE5OGY5YzVkNDY4MWNkNjFiMDM2ZDMwOWRjNWVhNTg).
 
 To run the examples:
 
@@ -22,19 +22,31 @@ To run the examples:
   example, to load them in the HR schema run:
 
   ```
-  sqlplus hr/welcome@localhost/orclpdb @demo.sql
+  sqlplus hr
+  SQL> @demo.sql
   ```
 
-- Edit `dbconfig.js` and set your username, password and the database
+- Edit `dbconfig.js` and set your username and the database
 connection string:
 
   ```
   module.exports = {
       user: "hr",
-      password: "welcome",
+      password: process.env.NODE_ORACLEDB_PASSWORD,
       connectString:"localhost/orclpdb"
   };
+  ```
+
+- Set the environment variable `NODE_ORACLEDB_PASSWORD` to your database schema password.
+
+  On Windows:
+  ```
+  set NODE_ORACLEDB_PASSWORD=...
+  ```
 
+  On Linux:
+  ```
+  export NODE_ORACLEDB_PASSWORD=...
   ```
 
 - Then run the samples like:

javascript/node-oracledb/calltimeout.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -21,10 +21,12 @@
  * DESCRIPTION
  *   Shows how to time out long running database calls.
  *   See https://oracle.github.io/node-oracledb/doc/api.html#dbcalltimeouts
- *   Node-oracledb must be using Oracle Client 18c libraries, or greater.
  *
  *   This example uses Async/Await of Node 8.
  *
+ *   This example requires node-oracledb 3 or later.
+ *   Node-oracledb must be using Oracle Client 18c libraries, or greater.
+ *
  *****************************************************************************/
 
 let oracledb = require("oracledb");

javascript/node-oracledb/connect.js

@@ -22,6 +22,8 @@
  *   Tests a basic connection to the database.
  *   See dbconfig.js for information on connectString formats.
  *
+ *   For a connection pool example see connectionpool.js
+ *
  *****************************************************************************/
 
 var oracledb = require('oracledb');

javascript/node-oracledb/connectionpool.js

@@ -0,0 +1,118 @@
+/* Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved. */
+
+/******************************************************************************
+ *
+ * You may not use the identified files except in compliance with the Apache
+ * License, Version 2.0 (the "License.")
+ *
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * NAME
+ *   connectionpool.js
+ *
+ * DESCRIPTION
+ *   Shows connection pool usage.  Connection pools are recommended
+ *   for applications that use a lot of connections for short periods.
+ *
+ *   This example uses Node 8's async/await syntax.
+ *
+ *   Other connection pool examples are in sessionfixup.js, webapp.js,
+ *   webapppromises.js and webappawait.js
+ *
+ *   For a standalone connection example, see connect.js
+ *
+ *   In some networks forced pool termination may hang unless you have
+ *   'disable_oob=on' in sqlnet.ora, see
+ *   https://oracle.github.io/node-oracledb/doc/api.html#tnsadmin
+ *
+ *****************************************************************************/
+
+const oracledb = require('oracledb');
+const dbConfig = require('./dbconfig.js');
+
+async function init() {
+  try {
+    // Create a connection pool which will later be accessed via the
+    // pool cache as the 'default' pool.
+    await oracledb.createPool({
+      user: dbConfig.user,
+      password: dbConfig.password,
+      connectString: dbConfig.connectString
+      // edition: 'ORA$BASE', // used for Edition Based Redefintion
+      // events: false, // whether to handle Oracle Database FAN and RLB events or support CQN
+      // externalAuth: false, // whether connections should be established using External Authentication
+      // homogeneous: true, // all connections in the pool have the same credentials
+      // poolAlias: 'default', // set an alias to allow access to the pool via a name.
+      // poolIncrement: 1, // only grow the pool by one connection at a time
+      // poolMax: 4, // maximum size of the pool. Increase UV_THREADPOOL_SIZE if you increase poolMax
+      // poolMin: 0, // start with no connections; let the pool shrink completely
+      // poolPingInterval: 60, // check aliveness of connection if idle in the pool for 60 seconds
+      // poolTimeout: 60, // terminate connections that are idle in the pool for 60 seconds
+      // queueTimeout: 60000, // terminate getConnection() calls in the queue longer than 60000 milliseconds
+      // sessionCallback: myFunction, // function invoked for brand new connections or by a connection tag mismatch
+      // stmtCacheSize: 30 // number of statements that are cached in the statement cache of each connection
+    });
+    console.log('Connection pool started');
+
+    // Now the pool is running, it can be used
+    await dostuff();
+
+  } catch (err) {
+    console.error('init() error: ' + err.message);
+  } finally {
+    await closePoolAndExit();
+  }
+}
+
+async function dostuff() {
+  let connection;
+  try {
+    // Get a connection from the default pool
+    connection = await oracledb.getConnection();
+    let sql = `SELECT sysdate FROM dual WHERE :b = 1`;
+    let binds = [1];
+    let options = { outFormat: oracledb.OBJECT };
+    let result = await connection.execute(sql, binds, options);
+    console.log(result);
+  } catch (err) {
+    console.error(err);
+  } finally {
+    if (connection) {
+      try {
+        // Put the connection back in the pool
+        await connection.close();
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  }
+}
+
+async function closePoolAndExit() {
+  console.log('\nTerminating');
+  try {
+    // Get the pool from the pool cache and close it when no
+    // connections are in use, or force it closed after 10 seconds
+    // If this hangs, you may need DISABLE_OOB=ON in a sqlnet.ora file
+    await oracledb.getPool().close(10);
+    console.log('Pool closed');
+    process.exit(0);
+  } catch(err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}
+
+process
+  .once('SIGTERM', closePoolAndExit)
+  .once('SIGINT',  closePoolAndExit);
+
+init();

javascript/node-oracledb/cqn1.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -27,6 +27,8 @@
  *
  *   This example uses Node 8 syntax, but could be written to use callbacks.
  *
+ *   This example requires node-oracledb 2.3 or later.
+ *
  *****************************************************************************/
 
 const oracledb = require("oracledb");

javascript/node-oracledb/cqn2.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -28,6 +28,8 @@
  *
  *   This example uses Node 8 syntax, but could be written to use callbacks.
  *
+ *   This example requires node-oracledb 2.3 or later.
+ *
  *****************************************************************************/
 
 const oracledb = require("oracledb");

javascript/node-oracledb/date.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -27,10 +27,15 @@
  *
  *****************************************************************************///
 
+// Using a fixed Oracle time zone helps avoid machine and deployment differences
+process.env.ORA_SDTZ = 'UTC';
+
 var async = require('async');
 var oracledb = require('oracledb');
 var dbConfig = require('./dbconfig.js');
 
+oracledb.outFormat = oracledb.OBJECT;
+
 var doconnect = function(cb) {
   oracledb.getConnection(
     {
@@ -68,18 +73,20 @@ var docleanup = function (conn, cb) {
 
 var docreate = function(conn, cb) {
   conn.execute(
-    "CREATE TABLE datetest(timestampcol TIMESTAMP, datecol DATE)",
+    `CREATE TABLE datetest(
+       timestampcol TIMESTAMP,
+       timestamptz TIMESTAMP WITH TIME ZONE,
+       timestampltz TIMESTAMP WITH LOCAL TIME ZONE,
+       datecol DATE)`,
     function(err) {
       return cb(err, conn);
     });
 };
 
-// Setting a local timezone in applications is recommended.
-// Note setting the environment variable ORA_SDTZ is an efficient alternative.
 var doalter = function(conn, cb) {
   console.log('Altering session time zone');
   conn.execute(
-    "ALTER SESSION SET TIME_ZONE='UTC'",
+    "ALTER SESSION SET TIME_ZONE='+5:00'",  // resets ORA_SDTZ value
     function(err) {
       return cb(err, conn);
     });
@@ -92,9 +99,9 @@ var doinsert = function(conn, cb) {
   console.log("Inserting JavaScript date: " + date);
 
   conn.execute(
-    "INSERT INTO datetest (timestampcol, datecol) VALUES (:ts, :td)",
-    { ts: date,
-      td: date },
+    `INSERT INTO datetest (timestampcol, timestamptz, timestampltz, datecol)
+     VALUES (:ts, :tstz, :tsltz, :td)`,
+    { ts: date, tstz: date, tsltz: date, td: date },
     function(err, result) {
       if (err)
         return cb(err, conn);
@@ -108,24 +115,21 @@ var doinsert = function(conn, cb) {
 // Fetch the dates
 var doselect = function(conn, cb) {
   conn.execute(
-    "SELECT timestampcol, datecol FROM datetest",
+    `SELECT timestampcol, timestamptz, timestampltz, datecol,
+            TO_CHAR(CURRENT_DATE, 'DD-Mon-YYYY HH24:MI') AS CD
+     FROM datetest`,
     function(err, result) {
       if (err) {
         return cb(err, conn);
       }
 
       console.log("Query Results:");
-      console.log(result.rows);
+      console.log(result.rows[0]);
 
       // Show the queried dates are of type Date
-      console.log("Result Manipulation in JavaScript:");
-      var ts = result.rows[0][0];
+      var ts = result.rows[0]['TIMESTAMPCOL'];
       ts.setDate(ts.getDate() + 5);
-      console.log(ts);
-
-      var d = result.rows[0][1];
-      d.setDate(d.getDate() - 5);
-      console.log(d);
+      console.log("TIMESTAMP manipulation in JavaScript:", ts);
 
       return cb(null, conn);
     });

javascript/node-oracledb/dbconfig.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -36,7 +36,7 @@
  *     [//]host_name[:port][/service_name][:server_type][/instance_name]
  *
  *   Commonly just the host_name and service_name are needed
- *   e.g. "localhost/orclpdb" or "localhost/XE"
+ *   e.g. "localhost/orclpdb" or "localhost/XEPDB1"
  *
  *   If using a tnsnames.ora file, the file can be in a default
  *   location such as $ORACLE_HOME/network/admin/tnsnames.ora or
@@ -74,7 +74,7 @@ module.exports = {
   // Instead of hard coding the password, consider prompting for it,
   // passing it in an environment variable via process.env, or using
   // External Authentication.
-  password      : process.env.NODE_ORACLEDB_PASSWORD || "welcome",
+  password      : process.env.NODE_ORACLEDB_PASSWORD,
 
   // For information on connection strings see:
   // https://oracle.github.io/node-oracledb/doc/api.html#connectionstrings

javascript/node-oracledb/em_batcherrors.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -25,6 +25,8 @@
  *   desired.
  *   Use demo.sql to create the required schema.
  *
+ *   This example requires node-oracledb 2.2 or later.
+ *
  *****************************************************************************/
 
 var async = require('async');

javascript/node-oracledb/em_batcherrors_aa.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -26,6 +26,8 @@
  *   This example also uses Async/Await of Node 8.
  *   Use demo.sql to create the required schema.
  *
+ *   This example requires node-oracledb 2.2 or later.
+ *
  *****************************************************************************/
 
 var oracledb = require('oracledb');

javascript/node-oracledb/em_dmlreturn1.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -22,6 +22,8 @@
  *   executeMany() example of DML RETURNING that returns single values
  *   Use demo.sql to create the required schema.
  *
+ *   This example requires node-oracledb 2.2 or later.
+ *
  *****************************************************************************/
 
 var async = require('async');