Update some examples and comments

Author: Christopher Jones

examples/dbconfig.js

@@ -20,28 +20,26 @@
  *
  * DESCRIPTION
  *   Holds the credentials used by node-oracledb examples to connect
- *   to the database.
- *
- *   The connectString here uses the Easy Connect syntax
- *   "localhost/XE".  This connects to the database service XE on the
- *   the local machine.
+ *   to the database.  Production applications should instead consider
+ *   using External Authentication to avoid hard coded credentials.
  *
  *   Applications can set the connectString value to an Easy Connect
- *   string, or a Connect Name from a tnsnames.ora file, or the name
- *   of a local Oracle database instance.
+ *   string, or a Net Service Name from a tnsnames.ora file or
+ *   external naming service, or it can be the name of a local Oracle
+ *   database instance.
  *
- *   The full Easy Connect syntax is:
+ *   The Easy Connect syntax is:
  *     [//]host_name[:port][/service_name][:server_type][/instance_name]
- *   see https://docs.oracle.com/database/121/NETAG/naming.htm#i498306
  *
- *   If a tnsnames.ora file is used, set the TNS_ADMIN environment
- *   variable such that $TNS_ADMIN/tnsnames.ora is read.
- *   Alternatively use $ORACLE_HOME/network/admin/tnsnames.ora or
- *   /etc/tnsnames.ora.
+ *   If using a tnsnames.ora file, the file can be in a default
+ *   location such as $ORACLE_HOME/network/admin/tnsnames.ora or
+ *   /etc/tnsnames.ora.  Alternatively set the TNS_ADMIN environment
+ *   variable and put the file in $TNS_ADMIN/tnsnames.ora.
  *
  *   If connectString is not specified, the empty string "" is used
  *   which indicates to connect to the local, default database.
  *
+ * TROUBLESHOOTING
  *   Errors like:
  *     ORA-12541: TNS:no listener
  *   or
@@ -58,5 +56,7 @@
 module.exports = {
   user          : "hr",
   password      : "welcome",
-  connectString : "localhost/XE"
+  // For information on connection strings see:
+  // https://github.com/oracle/node-oracledb/blob/master/doc/api.md#connectionstrings
+  connectString : "localhost/XE"  // Easy Connect syntax
 };

examples/demo.sql

@@ -21,6 +21,9 @@
  * DESCRIPTION
  *   Create database objects for the examples
  *
+ *   Scripts to create Oracle Database's traditional sample schemas can
+ *   be found at: https://github.com/oracle/db-sample-schemas
+ *
  *****************************************************************************/
 
 SET ECHO ON

examples/insert2.js

@@ -20,10 +20,10 @@
  *
  * DESCRIPTION
  *   Show the auto commit behavior.
- * 
+ *
  *   By default, node-oracledb does not commit on execute.
  *   The driver also has commit() and rollback() methods to explicitly control transactions.
- * 
+ *
  *   Note: when a connection is closed, any open transaction will be committed.
  *
  *****************************************************************************/
@@ -52,7 +52,7 @@ oracledb.getConnection(
           return;
         }
         console.log("Table created");
-        
+
         connection1.execute(
           "INSERT INTO test VALUES (:id, :nm)",
           [1, 'Chris'],  // Bind values
@@ -61,7 +61,7 @@ oracledb.getConnection(
           {
             if (err) { console.error(err.message); return; }
             console.log("Rows inserted: " + result.rowsAffected);  // 1
-            
+
             connection1.execute(
               "INSERT INTO test VALUES (:id, :nm)",
               [2, 'Alison'],  // Bind values
@@ -70,7 +70,7 @@ oracledb.getConnection(
               {
                 if (err) { console.error(err.message); return; }
                 console.log("Rows inserted: " + result.rowsAffected);  // 1
-                
+
                 // Create a second connection
                 oracledb.getConnection(
                   {
@@ -95,14 +95,14 @@ oracledb.getConnection(
                         // This will only show 'Chris' because inserting 'Alison' is not commited by default.
                         // Uncomment the isAutoCommit option above and you will see both rows
                         console.log(result.rows);
-                        
+
                         connection1.execute(
                           "DROP TABLE test",
                           function(err)
                           {
                             if (err) { console.error(err.message); return; }
                             console.log("Table dropped");
-                            
+
                             connection2.release(
                               function(err)
                               {
@@ -112,12 +112,12 @@ oracledb.getConnection(
                                   {
                                     if (err) { console.error(err.message); return; }
                                   });
-                                
+
                               });
                           });
                       });
                   });
               });
-          }); 
+          });
       });
   });

examples/rowlimit.js

@@ -22,6 +22,9 @@
  *   Shows ways to limit the number of records fetched by queries.
  *   Uses Oracle's sample HR schema.
  *
+ *   Scripts to create the HR schema can be found at:
+ *   https://github.com/oracle/db-sample-schemas
+ *
  *   By default, node-oracledb has a maxRows attribute that limits the
  *   number of records fetched from a query to 100.  Although
  *   adjusting maxRows can be used to control the number of rows

examples/select1.js

@@ -22,6 +22,9 @@
  *   Executes a basic query.
  *   Uses Oracle's sample HR schema.
  *
+ *   Scripts to create the HR schema can be found at:
+ *   https://github.com/oracle/db-sample-schemas
+ *
  *****************************************************************************/
 
 var oracledb = require('oracledb');
@@ -48,9 +51,21 @@ oracledb.getConnection(
       {
         if (err) {
           console.error(err.message);
+          doRelease(connection);
           return;
         }
-        console.log(result.rows);
         console.log(result.metaData);
+        console.log(result.rows);
+        doRelease(connection);
       });
   });
+
+function doRelease(connection)
+{
+  connection.release(
+    function(err) {
+      if (err) {
+        console.error(err.message);
+      }
+    });
+}

examples/select2.js

@@ -22,15 +22,18 @@
  *   Executes queries to show array and object output formats.
  *   Uses Oracle's sample HR schema.
  *
- *****************************************************************************/
+ *   Scripts to create the HR schema can be found at:
+ *   https://github.com/oracle/db-sample-schemas
+ *
+ *  *****************************************************************************/
 
 var oracledb = require('oracledb');
 var dbConfig = require('./dbconfig.js');
 
 // Properties are applicable to all connections and SQL executions.
 // They can also be set or overridden at the individual execute() call level
 //
-// This script sets outFormat in the execute() call but it could be set here instead
+// This script sets outFormat in the execute() call but it could be set here instead:
 // oracledb.outFormat = oracledb.OBJECT;
 
 oracledb.getConnection(
@@ -54,6 +57,7 @@ oracledb.getConnection(
       {
         if (err) {
           console.error(err.message);
+          doRelease(connection);
           return;
         }
         console.log("----- Cities beginning with 'S' (default ARRAY output format) --------");
@@ -66,24 +70,28 @@ oracledb.getConnection(
         + "ORDER BY city",
           {}, // A bind variable parameter is needed to disambiguate the following options parameter
               // otherwise you will get Error: ORA-01036: illegal variable name/number
-          {outFormat: oracledb.OBJECT}, // outFormat can be OBJECT and ARRAY.  The default is ARRAY
+          {outFormat: oracledb.OBJECT}, // outFormat can be OBJECT or ARRAY.  The default is ARRAY
           function(err, result)
           {
             if (err) {
               console.error(err.message);
+              doRelease(connection);
               return;
             }
             console.log("----- Cities beginning with 'S' (OBJECT output format) --------");
             console.log(result.rows);
 
-            connection.release(
-              function(err)
-              {
-                if (err) {
-                  console.error(err.message);
-                  return;
-                }
-              });
+            doRelease(connection);
           });
       });
   });
+
+function doRelease(connection)
+{
+  connection.release(
+    function(err) {
+      if (err) {
+        console.error(err.message);
+      }
+    });
+}

examples/selectjson.js

@@ -19,13 +19,13 @@
  *   selectjson.js
  *
  * DESCRIPTION
- *   Executes a query from a JSON table.  
+ *   Executes a query from a JSON table.
  *   Oracle Database 12.1.0.2 has extensive JSON datatype support.
- * 
+ *
  *   Use demo.sql to create the required table or do:
- * 
+ *
  *   DROP TABLE j_purchaseorder;
- * 
+ *
  *   CREATE TABLE j_purchaseorder
  *   (po_document VARCHAR2(4000) CONSTRAINT ensure_json CHECK (po_document IS JSON));
  *
@@ -46,16 +46,17 @@ oracledb.getConnection(
       console.error(err.message);
       return;
     }
-    
+
     var data = { "userId": 1, "userName": "Chris" };
     var s = JSON.stringify(data);
-    
+
     connection.execute(
       "INSERT INTO j_purchaseorder (po_document) VALUES (:bv)",
       [s],
       function (err) {
         if (err) {
           console.error(err.message);
+          doRelease(connection);
           return;
         }
         connection.execute(
@@ -64,10 +65,22 @@ oracledb.getConnection(
           {
             if (err) {
               console.error(err.message);
+              doRelease(connection);
               return;
             }
             js = JSON.parse(result.rows[0][0]);
             console.log(js.userId, js.userName);
+            doRelease(connection);
           });
       });
   });
+
+function doRelease(connection)
+{
+  connection.release(
+    function(err) {
+      if (err) {
+        console.error(err.message);
+      }
+    });
+}