Added a method connection.isHealthy()

Author: cjbj

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 **This release is under development and information may be incomplete**
 
+
+- Added a [`connection.isHealthy()`](https://oracle.github.io/node-oracledb/doc/api.html#ishealthy)
+  function to perform a local connection health check
+
 - Fixed numeric suffix feature (for duplicate SELECT column names when using
   `oracledb.OUT_FORMAT_OBJECT` mode) when the column name is also a JavaScript
   property or method name.

doc/api.md

@@ -1,4 +1,4 @@
-// Copyright (c) 2016, 2021, Oracle and/or its affiliates. All rights reserved
+// Copyright (c) 2016, 2022, Oracle and/or its affiliates. All rights reserved
 
 //-----------------------------------------------------------------------------
 //
@@ -453,7 +453,6 @@ async function tpcRollback(xid) {
 }
 
 
-
 // define class
 class Connection extends EventEmitter {
 
@@ -541,6 +540,18 @@ class Connection extends EventEmitter {
     return (this._getSodaDatabase());
   }
 
+  //--------------------------------------------------------------------------
+  //  isHealthy()
+  //    To get the health status of the connection.
+  //  NOTE: if this function returns false, the application must close the
+  //        connection obect.
+  //        This is a synchronous call.
+  //---------------------------------------------------------------------------
+  isHealthy() {
+    return this._isHealthy();
+  }
+
+
   // The queryStream function is similar to execute except that it immediately
   // returns a QueryStream.
   queryStream(sql, binding, options) {

lib/connection.js

@@ -37,6 +37,7 @@ static NJS_NAPI_METHOD(njsConnection_getDbObjectClass);
 static NJS_NAPI_METHOD(njsConnection_getQueue);
 static NJS_NAPI_METHOD(njsConnection_getSodaDatabase);
 static NJS_NAPI_METHOD(njsConnection_getStatementInfo);
+static NJS_NAPI_METHOD(njsConnection_isHealthy);
 static NJS_NAPI_METHOD(njsConnection_ping);
 static NJS_NAPI_METHOD(njsConnection_rollback);
 static NJS_NAPI_METHOD(njsConnection_shutdown);
@@ -156,6 +157,8 @@ static const napi_property_descriptor njsClassProperties[] = {
             NULL, napi_default, NULL },
     { "_getStatementInfo", NULL, njsConnection_getStatementInfo, NULL,
             NULL, NULL, napi_default, NULL },
+    { "_isHealthy", NULL, njsConnection_isHealthy, NULL, NULL, NULL,
+            napi_default, NULL },
     { "_ping", NULL, njsConnection_ping, NULL, NULL, NULL, napi_default,
             NULL },
     { "_rollback", NULL, njsConnection_rollback, NULL, NULL, NULL,
@@ -2108,6 +2111,28 @@ bool njsConnection_newFromBaton(njsBaton *baton, napi_env env,
 }
 
 
+//-----------------------------------------------------------------------------
+// njsConnection_isHealthy()
+//   Get the Health status - whether the current connection is usable or not
+//   NOTE: If this function returns FALSE, conn.close() has to be called
+//-----------------------------------------------------------------------------
+static napi_value njsConnection_isHealthy(napi_env env,
+        napi_callback_info info)
+{
+    int              value = 0;
+    napi_value       connObj;
+    njsConnection    *conn;
+
+    if (njsUtils_validateArgs(env, info, 0, NULL, &connObj,
+            (njsBaseInstance **)&conn)) {
+        if (conn->handle) {
+            dpiConn_getIsHealthy(conn->handle, &value);
+        }
+    }
+    return njsUtils_convertToBoolean(env, value);
+}
+
+
 //-----------------------------------------------------------------------------
 // njsConnection_ping()
 //   Ping the database to see if it is "alive".

src/njsConnection.c

@@ -0,0 +1,53 @@
+/* Copyright (c) 2022, 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.
+ *
+ * The node-oracledb test suite uses 'mocha'.
+ * See LICENSE.md for relevant licenses.
+ *
+ * NAME
+ *   261. connHealthy.js
+ *
+ * DESCRIPTION
+ *   Test cases for connecton.isHealthy()
+ *
+ *****************************************************************************/
+'use strict';
+
+const oracledb = require('oracledb');
+const assert   = require('assert');
+const dbconfig = require('./dbconfig.js');
+
+describe('261. connHealthy.js', function() {
+
+  describe('261.1 connection health on stand alone connections', function() {
+    it('261.1.1 connection health on good connection', async function() {
+      const conn = await oracledb.getConnection(dbconfig);
+      const isHealthy = conn.isHealthy();
+      assert.strictEqual(isHealthy, true);
+      await conn.close();
+    });
+
+    it('261.1.2 connection health on closed connection', async function() {
+      const conn = await oracledb.getConnection(dbconfig);
+      await conn.close();
+      const isHealthy = conn.isHealthy();
+      assert.strictEqual(isHealthy, false);
+    });
+
+  });
+
+});

test/connHealthy.js

@@ -5291,3 +5291,8 @@ oracledb.OUT_FORMAT_OBJECT and resultSet =  true
 
 260. tpcResume.js
     260.1 TPC suspend and resume
+
+261. connHealthy.js
+    261.1 connection health on stand alone connections
+        261.1.1 connection health on good connection
+        261.1.2 connection health on closed connection

test/list.txt

@@ -247,3 +247,4 @@ spec:
   - test/keepInStmtCache.js
   - test/tpc.js
   - test/tpcResume.js
+  - test/connHealthy.js