Add Oracle Database Sharding support

Author: cjbj

CHANGELOG.md

@@ -8,6 +8,9 @@
   [`connection.clientInfo`](https://oracle.github.io/node-oracledb/doc/api.html#propconnclientinfo)
   and [`connection.dbOp`](https://oracle.github.io/node-oracledb/doc/api.html#propconndbop).
 
+- Added support for [Oracle
+  Sharding](https://oracle.github.io/node-oracledb/doc/api.html#sharding).
+
 - Fixed a [regression](https://github.com/oracle/node-oracledb/issues/1152) when
   binding dates with alternative JavaScript frameworks.
 

doc/api.md

@@ -20,6 +20,7 @@
 'use strict';
 
 const nodbUtil = require('./util.js');
+const util = require('util');
 
 // This version of node-oracledb works with Node.js 8.16, 10.16 or
 // later.  The test stops hard-to-interpret runtime errors and crashes
@@ -94,6 +95,12 @@ class OracleDb {
     this.createPool = nodbUtil.promisify(oracleDbInst, createPool);
   }
 
+  // temporary method for determining if an object is a date until
+  // napi_is_date() can be used (when N-API v5 can be used)
+  _isDate(val) {
+    return util.isDate(val);
+  }
+
   // retrieves a pool from the pool cache (synchronous method)
   getPool(poolAlias) {
     let pool;

lib/oracledb.js

@@ -21,6 +21,7 @@
 
 const EventEmitter = require('events');
 const nodbUtil = require('./util.js');
+const util = require('util');
 
 // completeConnectionRequest does the actual work of getting a connection from
 // a pool. It's abstracted out so it can be called from getConnection and
@@ -480,6 +481,12 @@ class Pool extends EventEmitter {
     this.terminate = this.close;
   }
 
+  // temporary method for determining if an object is a date until
+  // napi_is_date() can be used (when N-API v5 can be used)
+  _isDate(val) {
+    return util.isDate(val);
+  }
+
 }
 
 

lib/pool.js

@@ -28,6 +28,8 @@
 // methods used internally
 static bool njsBaton_completeAsyncHelper(njsBaton *baton, napi_env env,
         napi_value *callback, napi_value *callingObj);
+static void njsBaton_freeShardingKeys(uint8_t *numShardingKeyColumns,
+        dpiShardingKeyColumn **shardingKeyColumns);
 
 
 //-----------------------------------------------------------------------------
@@ -359,10 +361,39 @@ void njsBaton_free(njsBaton *baton, napi_env env)
     }
     NJS_FREE_AND_CLEAR(baton->callbackArgs);
 
+    // free sharding and super sharding keys
+    njsBaton_freeShardingKeys(&baton->numShardingKeyColumns,
+            &baton->shardingKeyColumns);
+    njsBaton_freeShardingKeys(&baton->numSuperShardingKeyColumns,
+            &baton->superShardingKeyColumns);
+
     free(baton);
 }
 
 
+//-----------------------------------------------------------------------------
+// njsBaton_freeShardingKeys()
+//   To clean up array of ShardingKeys
+//-----------------------------------------------------------------------------
+void njsBaton_freeShardingKeys(uint8_t *numShardingKeyColumns,
+        dpiShardingKeyColumn **shardingKeyColumns)
+{
+    dpiShardingKeyColumn *shards = *shardingKeyColumns;
+    uint32_t i;
+
+    for (i = 0; i < *numShardingKeyColumns; i++) {
+        if (shards[i].oracleTypeNum == DPI_ORACLE_TYPE_VARCHAR &&
+                shards[i].value.asBytes.ptr) {
+            free(shards[i].value.asBytes.ptr);
+            shards[i].value.asBytes.ptr = NULL;
+        }
+    }
+    free(shards);
+    *numShardingKeyColumns = 0;
+    *shardingKeyColumns = NULL;
+}
+
+
 //-----------------------------------------------------------------------------
 // njsBaton_getBoolFromArg()
 //   Gets a boolean value from the specified JavaScript object property, if
@@ -540,6 +571,109 @@ uint32_t njsBaton_getNumOutBinds(njsBaton *baton)
 }
 
 
+//-----------------------------------------------------------------------------
+// njsBaton_getShardingKeyColumnsFromArg()
+//   Gets an array of sharding key columns from the specified JavaScript object
+// property, if possible. If the given property is undefined, no error is set
+// and the value is left untouched; otherwise, if the value is not an array,
+// the error is set on the baton.
+//-----------------------------------------------------------------------------
+bool njsBaton_getShardingKeyColumnsFromArg(njsBaton *baton, napi_env env,
+        napi_value *args, int argIndex, const char *propertyName,
+        uint8_t *numShardingKeyColumns,
+        dpiShardingKeyColumn **shardingKeyColumns)
+{
+    napi_value asNumber, value, element;
+    dpiShardingKeyColumn *shards;
+    napi_valuetype valueType;
+    uint32_t arrLen, i;
+    size_t numBytes;
+    bool check;
+
+    // validate parameter
+    if (!njsBaton_getValueFromArg(baton, env, args, argIndex, propertyName,
+            napi_object, &value, NULL))
+        return false;
+    if (!value)
+        return true;
+    NJS_CHECK_NAPI(env, napi_is_array(env, value, &check))
+    if (!check)
+        return njsBaton_setError(baton, errNonArrayProvided);
+
+    // allocate space for sharding key columns; if array is empty, nothing
+    // further to do!
+    NJS_CHECK_NAPI(env, napi_get_array_length(env, value, &arrLen))
+    if (arrLen == 0)
+        return true;
+    shards = calloc(arrLen, sizeof(dpiShardingKeyColumn));
+    if (!shards)
+        return njsBaton_setError(baton, errInsufficientMemory);
+    *shardingKeyColumns = shards;
+    *numShardingKeyColumns = (uint8_t)arrLen;
+
+    // process each element
+    for (i = 0; i < arrLen; i++) {
+        NJS_CHECK_NAPI(env, napi_get_element(env, value, i, &element))
+        NJS_CHECK_NAPI(env, napi_typeof(env, element, &valueType))
+
+        // handle strings
+        if (valueType == napi_string) {
+            shards[i].nativeTypeNum = DPI_NATIVE_TYPE_BYTES;
+            shards[i].oracleTypeNum = DPI_ORACLE_TYPE_VARCHAR;
+            if (!njsUtils_copyStringFromJS(env, element,
+                    &shards[i].value.asBytes.ptr, &numBytes))
+                return false;
+            shards[i].value.asBytes.length = (uint32_t) numBytes;
+            continue;
+        }
+
+        // handle numbers
+        if (valueType == napi_number) {
+            shards[i].nativeTypeNum = DPI_NATIVE_TYPE_DOUBLE;
+            shards[i].oracleTypeNum = DPI_ORACLE_TYPE_NUMBER;
+            NJS_CHECK_NAPI(env, napi_get_value_double(env, element,
+                    &shards[i].value.asDouble));
+            continue;
+        }
+
+        // handle objects
+        if (valueType == napi_object) {
+
+            // handle buffers
+            NJS_CHECK_NAPI(env, napi_is_buffer(env, element, &check))
+            if (check) {
+                shards[i].nativeTypeNum = DPI_NATIVE_TYPE_BYTES;
+                shards[i].oracleTypeNum = DPI_ORACLE_TYPE_RAW;
+                NJS_CHECK_NAPI(env, napi_get_buffer_info(env, element,
+                        (void*) &shards[i].value.asBytes.ptr, &numBytes))
+                shards[i].value.asBytes.length = (uint32_t) numBytes;
+                continue;
+            }
+
+            // handle dates
+            if (!njsBaton_isDate(baton, env, element, &check))
+                return false;
+            if (check) {
+                shards[i].nativeTypeNum = DPI_NATIVE_TYPE_DOUBLE;
+                shards[i].oracleTypeNum = DPI_ORACLE_TYPE_DATE;
+                NJS_CHECK_NAPI(env, napi_coerce_to_number(env, element,
+                        &asNumber))
+                NJS_CHECK_NAPI(env, napi_get_value_double(env, asNumber,
+                        &shards[i].value.asDouble))
+                continue;
+            }
+
+        }
+
+        // no support for other types
+        return njsBaton_setError(baton, errInvalidPropertyValueInParam,
+                propertyName, argIndex + 1);
+    }
+
+    return true;
+}
+
+
 //-----------------------------------------------------------------------------
 // njsBaton_getSodaDocument()
 //   Examines the passed object. If it is a SODA document object, a reference
@@ -836,7 +970,13 @@ bool njsBaton_isDate(njsBaton *baton, napi_env env, napi_value value,
 {
     napi_value isDateObj;
 
-    NJS_CHECK_NAPI(env, napi_call_function(env, baton->jsConnection,
+    if (!baton->jsIsDateObj) {
+        NJS_CHECK_NAPI(env, napi_get_reference_value(env, baton->jsCallingObj,
+                &baton->jsIsDateObj))
+        NJS_CHECK_NAPI(env, napi_get_named_property(env, baton->jsIsDateObj,
+                "_isDate", &baton->jsIsDateMethod))
+    }
+    NJS_CHECK_NAPI(env, napi_call_function(env, baton->jsIsDateObj,
             baton->jsIsDateMethod, 1, &value, &isDateObj))
     NJS_CHECK_NAPI(env, napi_get_value_bool(env, isDateObj, isDate))
     return true;
@@ -918,21 +1058,10 @@ void njsBaton_reportError(njsBaton *baton, napi_env env)
 // njsBaton_setConstructors()
 //   Sets the constructors on the baton.
 //-----------------------------------------------------------------------------
-bool njsBaton_setConstructors(njsBaton *baton, napi_env env, bool canBind)
+bool njsBaton_setConstructors(njsBaton *baton, napi_env env)
 {
     napi_value global;
 
-    // if binding is possible, get the connection (which is the calling object)
-    // and acquire the method used for determining if a value is a date; this
-    // is needed until such time as napi_is_date() is available for all LTS
-    // releases
-    if (canBind) {
-        NJS_CHECK_NAPI(env, napi_get_reference_value(env, baton->jsCallingObj,
-                &baton->jsConnection))
-        NJS_CHECK_NAPI(env, napi_get_named_property(env, baton->jsConnection,
-                "_isDate", &baton->jsIsDateMethod))
-    }
-
     // acquire the Date constructor
     NJS_CHECK_NAPI(env, napi_get_global(env, &global))
     NJS_CHECK_NAPI(env, napi_get_named_property(env, global, "Date",

src/njsBaton.c

@@ -600,7 +600,7 @@ static bool njsConnection_executePostAsync(njsBaton *baton, napi_env env,
     napi_value implicitResults;
 
     // create constructors used for various types that might be returned
-    if (!njsBaton_setConstructors(baton, env, true))
+    if (!njsBaton_setConstructors(baton, env))
         return false;
 
     // create result object
@@ -693,7 +693,7 @@ static bool njsConnection_executeProcessArgs(njsBaton *baton,
             (void**) &baton->fetchAsStringTypes,
             &baton->numFetchAsStringTypes))
         return false;
-    if (!njsBaton_setConstructors(baton, env, true))
+    if (!njsBaton_setConstructors(baton, env))
         return false;
 
     // get SQL from first argument
@@ -888,7 +888,7 @@ static bool njsConnection_executeManyProcessArgs(njsBaton *baton,
 {
     // setup defaults and define constructors for use in various checks
     baton->autoCommit = baton->oracleDb->autoCommit;
-    if (!njsBaton_setConstructors(baton, env, true))
+    if (!njsBaton_setConstructors(baton, env))
         return false;
 
     // get SQL from first argument

src/njsConnection.c

@@ -60,7 +60,7 @@ static const char *njsErrorMessages[] = {
     "NJS-046: pool alias \"%s\" already exists in the connection pool cache", // errPoolWithAliasAlreadyExists
     "NJS-047: pool alias \"%s\" not found in connection pool cache", // errPoolWithAliasNotFound
     "NJS-052: invalid data type at array index %d for bind position %d", // errIncompatibleTypeArrayIndexBind
-    "NJS-053: array value expected, a non-array value provided", //errNonArrayProvided
+    "NJS-053: an array value was expected", //errNonArrayProvided
     "NJS-055: binding by position and name cannot be mixed", // errMixedBind
     "NJS-056: maxSize must be specified and not zero for bind position %u", // errMissingMaxSizeByPos
     "NJS-057: maxSize must be specified and not zero for bind \"%.*s\"", // errMissingMaxSizeByName

src/njsErrors.c

@@ -423,6 +423,7 @@ struct njsBaton {
     // integer values
     uint32_t poolMin;
     uint32_t poolMax;
+    uint32_t poolMaxPerShard;
     uint32_t poolIncrement;
     uint32_t poolTimeout;
     int32_t poolPingInterval;
@@ -472,17 +473,24 @@ struct njsBaton {
     // subscriptions (no free required)
     njsSubscription *subscription;
 
+    // sharding (requires free)
+    dpiShardingKeyColumn *shardingKeyColumns;
+    dpiShardingKeyColumn *superShardingKeyColumns;
+    uint8_t  numShardingKeyColumns;
+    uint8_t  numSuperShardingKeyColumns;
+
     // references that are held (requires free)
     napi_ref jsBuffer;
     napi_ref jsCallingObj;
     napi_ref jsCallback;
     napi_ref jsSubscription;
 
     // values required to check if a value is a date; this is only used when
-    // binding data in connection.execute() and connection.executeMany();
-    // this can be replaced with calls to napi_is_date() when it is available
-    // for all LTS releases
-    napi_value jsConnection;
+    // binding data in connection.execute() and connection.executeMany() and
+    // when managing sharding keys (when getting a connection); this can be
+    // replaced with calls to napi_is_date() when it is available for all LTS
+    // releases
+    napi_value jsIsDateObj;
     napi_value jsIsDateMethod;
 
     // constructors
@@ -573,6 +581,7 @@ struct njsOracleDb {
     uint32_t fetchArraySize;
     uint32_t poolMin;
     uint32_t poolMax;
+    uint32_t poolMaxPerShard;
     uint32_t poolIncrement;
     uint32_t poolTimeout;
     uint32_t lobPrefetchSize;
@@ -614,6 +623,7 @@ struct njsPool {
     njsOracleDb *oracleDb;
     uint32_t poolMin;
     uint32_t poolMax;
+    uint32_t poolMaxPerShard;
     uint32_t poolIncrement;
     uint32_t poolTimeout;
     uint32_t stmtCacheSize;
@@ -783,6 +793,9 @@ bool njsBaton_getFetchInfoFromArg(njsBaton *baton, napi_env env,
 bool njsBaton_getIntFromArg(njsBaton *baton, napi_env env, napi_value *args,
         int argIndex, const char *propertyName, int32_t *result, bool *found);
 uint32_t njsBaton_getNumOutBinds(njsBaton *baton);
+bool njsBaton_getShardingKeyColumnsFromArg(njsBaton *baton, napi_env env,
+        napi_value *args, int argIndex, const char *propertyName,
+        uint8_t *numShardKeys, dpiShardingKeyColumn **shards);
 bool njsBaton_getSodaDocument(njsBaton *baton, njsSodaDatabase *db,
         napi_env env, napi_value obj, dpiSodaDoc **handle);
 bool njsBaton_getStringFromArg(njsBaton *baton, napi_env env, napi_value *args,
@@ -808,7 +821,7 @@ bool njsBaton_queueWork(njsBaton *baton, napi_env env, const char *methodName,
         bool (*afterWorkCallback)(njsBaton*, napi_env, napi_value*),
         unsigned int numCallbackArgs);
 void njsBaton_reportError(njsBaton *baton, napi_env env);
-bool njsBaton_setConstructors(njsBaton *baton, napi_env env, bool canBind);
+bool njsBaton_setConstructors(njsBaton *baton, napi_env env);
 bool njsBaton_setError(njsBaton *baton, int errNum, ...);
 bool njsBaton_setErrorDPI(njsBaton *baton);