Add support for DB 21 JSON internal storage type OSON

Author: cjbj

.gitignore

@@ -7,6 +7,7 @@ core
 GPATH
 GRTAGS
 GTAGS
+oracle_private/specs/*.pdf
 
 # macOS Ignores
 .DS_Store

CHANGELOG.md

@@ -1,8 +1,6 @@
 # Change Log
 
-## node-oracledb v5.1.0-dev (DD Mon YYYY)
-
-**This release is under development**
+## node-oracledb v5.1.0 (8 Dec 2020)
 
 - Added
   [`oracledb.dbObjectAsPojo`](https://oracle.github.io/node-oracledb/doc/api.html#propdbobjpojo)
@@ -13,6 +11,9 @@
   objects" or kept as database-backed objects.  This option also applies to
   output `BIND_OUT` bind variables.
 
+- Enhanced JSON support to work with Oracle Database 21's native JSON storage
+  format.  A new type `oracledb.DB_TYPE_JSON` was added.
+
 - Numeric suffixes are now added to duplicate SELECT column names when using
   `oracledb.OUT_FORMAT_OBJECT` mode, allowing all columns to be represented in
   the JavaScript object.

binding.gyp

@@ -11,6 +11,7 @@
              "src/njsConnection.c",
              "src/njsDbObject.c",
              "src/njsErrors.c",
+             "src/njsJsonBuffer.c",
              "src/njsLob.c",
              "src/njsModule.c",
              "src/njsOracleDb.c",
@@ -36,6 +37,7 @@
              "odpi/src/dpiGlobal.c",
              "odpi/src/dpiHandleList.c",
              "odpi/src/dpiHandlePool.c",
+             "odpi/src/dpiJson.c",
              "odpi/src/dpiLob.c",
              "odpi/src/dpiMsgProps.c",
              "odpi/src/dpiObjectAttr.c",

doc/api.md

@@ -97,7 +97,7 @@ File Name                                                 | Description
 [`select1.js`](select1.js)                                | Executes a basic query without using a connection pool or ResultSet
 [`select2.js`](select2.js)                                | Executes queries to show array and object output formats
 [`selectgeometry.js`](selectgeometry.js)                  | Insert and query Oracle Spatial geometries
-[`selectjson.js`](selectjson.js)                          | Shows some JSON features of Oracle Database
+[`selectjson.js`](selectjson.js)                          | Shows some JSON features of Oracle Database 21c
 [`selectjsonblob.js`](selectjsonblob.js)                  | Shows how to use a BLOB as a JSON column store
 [`selectobject.js`](selectobject.js)                      | Insert and query a named Oracle database object
 [`selectnestedcursor.js`](selectnestedcursor.js)          | Shows selecting from a nested cursor

examples/README.md

@@ -1,4 +1,4 @@
-/* Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -19,91 +19,111 @@
  *   selectjson.js
  *
  * DESCRIPTION
- *   Shows some JSON features of Oracle Database 12c.
- *
- *   Requires at least Oracle Database 12.1.0.2, which has extensive JSON datatype support.
+ *   Shows some JSON features of Oracle Database 21c.
  *   See https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=ADJSN
  *
+ *   For JSON with older databases see selectjsonblob.js
+ *
+ *   This example requires node-oracledb 5.1 or later.
+ *
  *   This example uses Node 8's async/await syntax.
  *
  *****************************************************************************/
 
 const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 
+oracledb.extendedMetaData = true;
+
 async function run() {
 
   let connection;
 
   try {
+
     connection = await oracledb.getConnection(dbConfig);
 
-    if (connection.oracleServerVersion < 1201000200) {
-      throw new Error('This example only works with Oracle Database 12.1.0.2 or greater');
+    if (connection.oracleServerVersion < 2100000000) {
+      throw new Error('This example requires Oracle Database 21.1 or later. Try selectjsonblob.js.');
     }
 
-    const stmts = [
-      `DROP TABLE no_purchaseorder`,
+    console.log('1. Creating Table');
 
-      // Note if your applications always insert valid JSON, you may delete
-      // the IS JSON check to remove its additional validation overhead.
-      `CREATE TABLE no_purchaseorder (po_document VARCHAR2(4000) CHECK (po_document IS JSON))`
-    ];
+    try {
+      await connection.execute(`DROP TABLE no_purchaseorder`);
+    } catch(e) {
+      if (e.errorNum != 942)
+        console.error(e);
+    }
 
-    for (const s of stmts) {
-      try {
-        await connection.execute(s);
-      } catch(e) {
-        if (e.errorNum != 942)
-          console.error(e);
-      }
+    connection.execute(`CREATE TABLE no_purchaseorder (po_document JSON)`);
+
+    console.log('2. Inserting Data');
+
+    const inssql = `INSERT INTO no_purchaseorder (po_document) VALUES (:bv)`;
+    const data = { "userId": 1, "userName": "Anna", "location": "Australia" };
+    if (oracledb.oracleClientVersion >= 2100000000) {
+      await connection.execute(inssql, { bv: { val: data, type: oracledb.DB_TYPE_JSON } });
+    } else {
+      // With older client versions, insert as a JSON string
+      const s = JSON.stringify(data);
+      const b = Buffer.from(s, 'utf8');
+      await connection.execute(inssql, { bv: { val: b } });
     }
 
-    let result;
+    let result, j;
 
-    console.log('Inserting Data');
-    const data = { "userId": 1, "userName": "Chris", "location": "Australia" };
-    const s = JSON.stringify(data);
-    await connection.execute(
-      `INSERT INTO no_purchaseorder (po_document) VALUES (:bv)`,
-      [s], // bind the JSON string for inserting into the JSON column.
-      { autoCommit: true }
-    );
+    console.log('3. Selecting JSON stored in a column');
 
-    console.log('1. Selecting JSON stored in a VARCHAR2 column');
     result = await connection.execute(
       `SELECT po_document
        FROM no_purchaseorder
-       WHERE JSON_EXISTS (po_document, '$.location')`
+       WHERE JSON_EXISTS (po_document, '$.location')
+       OFFSET 0 ROWS FETCH NEXT 1 ROWS ONLY`
     );
-    const js = JSON.parse(result.rows[0][0]);  // just show first record
-    console.log('Query results: ', js);
+    if (result.metaData[0].fetchType == oracledb.DB_TYPE_JSON) {
+      j = result.rows[0][0];
+    } else {
+      // Oracle Client libraries < 21 will return a BLOB
+      const d = await result.rows[0][0].getData();
+      j = await JSON.parse(d);
+    }
+    console.log('Query results: ', j);
+
+    console.log('4. Using JSON_VALUE to extract a value from a JSON column');
 
-    console.log('2. Using JSON_VALUE to extract a value from a JSON column');
     result = await connection.execute(
       `SELECT JSON_VALUE(po_document, '$.location')
-       FROM no_purchaseorder`
+       FROM no_purchaseorder
+       OFFSET 0 ROWS FETCH NEXT 1 ROWS ONLY`
     );
     console.log('Query results: ', result.rows[0][0]);  // just show first record
 
-    if (connection.oracleServerVersion < 1202000000) {
-      throw new Error('These examples only work with Oracle Database 12.2 or greater');
-    }
+    console.log('5. Using dot-notation to extract a value from a JSON column');
 
-    console.log('3. Using dot-notation to extract a value from a JSON column');
     result = await connection.execute(
       `SELECT po.po_document.location
-       FROM no_purchaseorder po`
+       FROM no_purchaseorder po
+       OFFSET 0 ROWS FETCH NEXT 1 ROWS ONLY`
     );
-    console.log('Query results: ', result.rows[0][0]);  // just show first record
+    if (result.metaData[0].fetchType == oracledb.DB_TYPE_JSON) {
+      j = result.rows[0][0];
+    } else {
+      // Oracle Client libraries < 21 will return a BLOB
+      const d = await result.rows[0][0].getData();
+      j = await JSON.parse(d);
+    }
+    console.log('Query results: ', j);
+
+    console.log('6. Using JSON_OBJECT to extract relational data as JSON');
 
-    console.log('4. Using JSON_OBJECT to extract relational data as JSON');
     result = await connection.execute(
       `SELECT JSON_OBJECT('key' IS d.dummy) dummy
        FROM dual d`
     );
-    for (let row of result.rows)
-      console.log(row[0]);
+    for (let row of result.rows) {
+      console.log('Query results: ', row[0]);
+    }
 
   } catch (err) {
     console.error(err);

examples/selectjson.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -19,12 +19,13 @@
  *   selectjsonblob.js
  *
  * DESCRIPTION
- *   Executes sample insert and query statements using a JSON column with BLOB storage.
+ *   Shows how to use a BLOB as a JSON column store.
  *
- *   Requires Oracle Database 12.1.0.2, which has extensive JSON datatype support.
- *   See https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=ADJSN
+ *   Note: with Oracle Database 21c using the new JSON type is recommended
+ *   instead, see selectjson.js
  *
- *   This example requires node-oracledb 1.13 or later.
+ *   Requires Oracle Database 12.1.0.2 or later.
+ *   See https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=ADJSN
  *
  *   This example uses Node 8's async/await syntax.
  *
@@ -33,6 +34,8 @@
 const oracledb = require('oracledb');
 const dbConfig = require('./dbconfig.js');
 
+oracledb.extendedMetaData = true;
+
 async function run() {
 
   let connection;
@@ -42,58 +45,81 @@ async function run() {
     connection = await oracledb.getConnection(dbConfig);
 
     if (connection.oracleServerVersion < 1201000200) {
-      throw new Error('This example only works with Oracle Database 12.1.0.2 or greater');
+      throw new Error('Using JSON requires Oracle Database 12.1.0.2 or later');
     }
 
-    const stmts = [
-      `DROP TABLE no_purchaseorder_b`,
+    console.log('1. Creating Table');
 
-      `CREATE TABLE no_purchaseorder_b (po_document BLOB CHECK (po_document IS JSON)) LOB (po_document) STORE AS (CACHE)`
-    ];
+    try {
+      await connection.execute(`DROP TABLE no_purchaseorder_b`);
+    } catch(e) {
+      if (e.errorNum != 942)
+        console.error(e);
+    }
 
-    for (const s of stmts) {
-      try {
-        await connection.execute(s);
-      } catch(e) {
-        if (e.errorNum != 942)
-          console.error(e);
-      }
+    await connection.execute(
+      `CREATE TABLE no_purchaseorder_b
+           (po_document BLOB CHECK (po_document IS JSON)) LOB (po_document) STORE AS (CACHE)`);
+
+    console.log('2. Inserting Data');
+
+    const inssql = `INSERT INTO no_purchaseorder_b (po_document) VALUES (:bv)`;
+    const data = { "userId": 1, "userName": "Anna", "location": "Australia" };
+
+    if (oracledb.oracleClientVersion >= 2100000000 && connection.oracleServerVersion >= 2100000000 ) {
+      // Take advantage of direct binding of JavaScript objects
+      await connection.execute(inssql, { bv: { val: data, type: oracledb.DB_TYPE_JSON } });
+    } else {
+      // Insert the data as a JSON string
+      const s = JSON.stringify(data);
+      const b = Buffer.from(s, 'utf8');
+      await connection.execute(inssql, { bv: { val: b } });
     }
 
-    let result;
+    console.log('3. Selecting JSON stored in a BLOB column');
 
-    console.log('Inserting Data');
-    const data = { "userId": 2, "userName": "Bob", "location": "USA" };
-    const s = JSON.stringify(data);
-    const b = Buffer.from(s, 'utf8');
-    await connection.execute(
-      `INSERT INTO no_purchaseorder_b (po_document) VALUES (:lobbv)`,
-      { lobbv: b }
-    );
+    let result, j;
 
-    console.log('Selecting JSON stored in a BLOB column:');
     result = await connection.execute(
       `SELECT po_document
        FROM no_purchaseorder_b
-       WHERE JSON_EXISTS (po_document, '$.location')`,
-      [],
-      { fetchInfo: { "PO_DOCUMENT": { type: oracledb.BUFFER } } }  // Fetch as a Buffer instead of a Stream
+       WHERE JSON_EXISTS (po_document, '$.location')
+       OFFSET 0 ROWS FETCH NEXT 1 ROWS ONLY`
     );
-    if (result.rows.length === 0)
-      throw new Error('No results');
-    console.log(result.rows[0][0].toString('utf8'));
+    const d = await result.rows[0][0].getData();
+    j = await JSON.parse(d);
+    console.log('Query results: ', j);
+
+    console.log('4. Using JSON_VALUE to extract a value from a JSON column');
 
-    console.log('Selecting a JSON value using "dotted" notation:');
-    if (connection.oracleServerVersion < 1202000000) {
-      throw new Error('This example only works with Oracle Database 12.2 or greater');
-    }
     result = await connection.execute(
-      `SELECT pob.po_document.location
-       FROM no_purchaseorder_b pob`
+      `SELECT JSON_VALUE(po_document, '$.location')
+       FROM no_purchaseorder_b
+       OFFSET 0 ROWS FETCH NEXT 1 ROWS ONLY`
     );
-    if (result.rows.length === 0)
-      throw new Error('No results');
-    console.log(result.rows[0][0]);
+    console.log('Query results: ', result.rows[0][0]);  // just show first record
+
+    if (connection.oracleServerVersion >= 1202000000) {
+
+      console.log('5. Using dot-notation to extract a value from a JSON column');
+
+      result = await connection.execute(
+        `SELECT po.po_document.location
+         FROM no_purchaseorder_b po
+         OFFSET 0 ROWS FETCH NEXT 1 ROWS ONLY`
+      );
+      console.log('Query results: ', result.rows[0][0]);
+
+      console.log('6. Using JSON_OBJECT to extract relational data as JSON');
+
+      result = await connection.execute(
+        `SELECT JSON_OBJECT('key' IS d.dummy) dummy
+         FROM dual d`
+      );
+      for (let row of result.rows) {
+        console.log('Query results: ', row[0]);
+      }
+    }
 
   } catch (err) {
     console.error(err);

examples/selectjsonblob.js

@@ -2351,7 +2351,8 @@ static bool njsConnection_scanExecuteBinds(njsBaton *baton, napi_env env,
         // specified by the application; for OUT binds, the value from the
         // application must be accepted as is as there is no way to
         // validate it
-        if (var->varTypeNum != DPI_ORACLE_TYPE_OBJECT) {
+        if (var->varTypeNum != DPI_ORACLE_TYPE_OBJECT &&
+                var->varTypeNum != DPI_ORACLE_TYPE_JSON) {
 
             NJS_CHECK_NAPI(env, napi_is_array(env, bindValue, &check))
             if (check) {

odpi

@@ -84,6 +84,8 @@ static const char *njsErrorMessages[] = {
     "NJS-075: only one of connectString and connectionString can be used", // errDblConnectionString
     "NJS-076: connection request rejected. Pool queue length queueMax %d reached", // errQueueMax
     "NJS-077: Oracle Client library has already been initialized", // errClientLibAlreadyInitialized
+    "NJS-078: unsupported data type %u in JSON value", // errUnsupportedDataTypeInJson
+    "NJS-079: cannot convert from JavaScript value to JSON value", // errConvertToJsonValue
 };