Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
mg-dbx - npm Package Compare versions
Comparing version 1.3.9 to 1.4.10
@@ -5,3 +5,3 @@ { | ||
| "description": "High speed Synchronous and Asynchronous access to M-like databases from Node.js.", | ||
| "version": "1.3.9", | ||
| "version": "1.4.10", | ||
| "maintainers": "Chris Munt <cmunt@mgateway.com>", | ||
@@ -8,0 +8,0 @@ "homepage": "https://github.com/chrisemunt/mg-dbx", |
327
README.md
@@ -6,9 +6,21 @@ # mg-dbx | ||
| Chris Munt <cmunt@mgateway.com> | ||
| 26 February 2020, M/Gateway Developments Ltd [http://www.mgateway.com](http://www.mgateway.com) | ||
| 6 May 2020, M/Gateway Developments Ltd [http://www.mgateway.com](http://www.mgateway.com) | ||
| * Verified to work with Node.js v8 to v13. | ||
| * Verified to work with Node.js v8 to v14. | ||
| * [Release Notes](#RelNotes) can be found at the end of this document. | ||
| ## Pre-requisites | ||
| Contents | ||
| * [Pre-requisites](#PreReq") | ||
| * [Installing mg-dbx](#Install) | ||
| * [Connecting to the database](#Connect) | ||
| * [Invocation of database commands](#DBCommands) | ||
| * [Invocation of database functions](#DBFunctions) | ||
| * [Direct access to InterSystems classes (IRIS and Cache)](#DBClasses) | ||
| * [Direct access to SQL: MGSQL and InterSystems SQL (IRIS and Cache)](#DBSQL) | ||
| * [Using Node.js/V8 worker threads](#Threads) | ||
| * [License](#License) | ||
| ## <a name="PreReq"></a> Pre-requisites | ||
| **mg-dbx** is a Node.js addon written in C++. It is distributed as C++ source code and the NPM installation procedure will expect a C++ compiler to be present on the target system. | ||
@@ -41,3 +53,3 @@ | ||
| ## Installing mg-dbx | ||
| ## <a name="Install"></a> Installing mg-dbx | ||
@@ -50,4 +62,66 @@ Assuming that Node.js is already installed and a C++ compiler is available to the installation process: | ||
| ## Documentation | ||
| ### Installing the M support routines | ||
| The M support routines are required for: | ||
| * Direct access to SQL. | ||
| * The Merge command under YottaDB. | ||
| Two M routines need to be installed (%zmgsi and %zmgsis). These can be found in the GitHub source code repository ([https://github.com/chrisemunt/mg-dbx](https://github.com/chrisemunt/mg-dbx)) | ||
| #### Installation for YottaDB | ||
| The instructions given here assume a standard 'out of the box' installation of **YottaDB** deployed in the following location: | ||
| /usr/local/lib/yottadb/r122 | ||
| The primary default location for routines: | ||
| /root/.yottadb/r1.22_x86_64/r | ||
| Copy all the routines (i.e. all files with an 'm' extension) held in the GitHub **/yottadb** directory to: | ||
| /root/.yottadb/r1.22_x86_64/r | ||
| Change directory to the following location and start a **YottaDB** command shell: | ||
| cd /usr/local/lib/yottadb/r122 | ||
| ./ydb | ||
| Link all the **zmgsi** routines and check the installation: | ||
| do ylink^%zmgsi | ||
| do ^%zmgsi | ||
| M/Gateway Developments Ltd - Service Integration Gateway | ||
| Version: 3.2; Revision 7 (5 May 2020) | ||
| Note that the version of **zmgsi** is successfully displayed. | ||
| Finally, add the following lines to the interface file (**cm.ci** in the example used in the db.open() method). | ||
| sqlemg: ydb_char_t * sqlemg^%zmgsis(I:ydb_char_t*, I:ydb_char_t *, I:ydb_char_t *) | ||
| sqlrow: ydb_char_t * sqlrow^%zmgsis(I:ydb_char_t*, I:ydb_char_t *, I:ydb_char_t *) | ||
| sqldel: ydb_char_t * sqldel^%zmgsis(I:ydb_char_t*, I:ydb_char_t *) | ||
| ifc_zmgsis: ydb_string_t * ifc^%zmgsis(I:ydb_string_t*, I:ydb_string_t *, I:ydb_string_t*) | ||
| #### Installation for other M systems | ||
| For InterSystems IRIS and Cache, log in to the Manager UCI and install the **zmgsi** routines held in either **/m/zmgsi\_cache.xml** or **/m/zmgsi\_iris.xml** as appropriate. | ||
| do $system.OBJ.Load("/m/zmgsi_cache.xml","ck") | ||
| Alternatively, for other M systems, log in to the Manager UCI and, using the %RI utility (or similar) load the **zmgsi** routines held in **/m/zmgsi.ro**. | ||
| Change to your development UCI and check the installation: | ||
| do ^%zmgsi | ||
| M/Gateway Developments Ltd - Service Integration Gateway | ||
| Version: 3.2; Revision 7 (5 May 2020) | ||
| ## <a name="Connect"></a> Connecting to the database | ||
| Most **mg-dbx** methods are capable of operating either synchronously or asynchronously. For an operation to complete asynchronously, simply supply a suitable callback as the last argument in the call. | ||
@@ -59,2 +133,8 @@ | ||
| And optionally (as required): | ||
| var mglobal = require('mg-dbx').mglobal; | ||
| var mcursor = require('mg-dbx').mcursor; | ||
| var mclass = require('mg-dbx').mclass; | ||
| ### Create a Server Object | ||
@@ -133,7 +213,23 @@ | ||
| ### Return the version of mg-dbx | ||
| var result = db.version(); | ||
| Example: | ||
| console.log("\nmg-dbx Version: " + db.version()); | ||
| ### Close database connection | ||
| db.close(); | ||
| ### Invocation of database commands | ||
| #### Register a global name (and fixed key) | ||
| ## <a name="DBCommands"></a> Invocation of database commands | ||
| ### Register a global name (and fixed key) | ||
| global = new mglobal(db, <global_name>[, <fixed_key>]); | ||
| Or: | ||
| global = db.mglobal(<global_name>[, <fixed_key>]); | ||
@@ -145,3 +241,3 @@ | ||
| #### Set a record | ||
| ### Set a record | ||
@@ -160,3 +256,3 @@ Synchronous: | ||
| #### Get a record | ||
| ### Get a record | ||
@@ -175,3 +271,3 @@ Synchronous: | ||
| #### Delete a record | ||
| ### Delete a record | ||
@@ -191,3 +287,3 @@ Synchronous: | ||
| #### Check whether a record is defined | ||
| ### Check whether a record is defined | ||
@@ -207,3 +303,3 @@ Synchronous: | ||
| #### Parse a set of records (in order) | ||
| ### Parse a set of records (in order) | ||
@@ -226,3 +322,3 @@ Synchronous: | ||
| #### Parse a set of records (in reverse order) | ||
| ### Parse a set of records (in reverse order) | ||
@@ -245,3 +341,3 @@ Synchronous: | ||
| #### Increment the value of a global node | ||
| ### Increment the value of a global node | ||
@@ -261,3 +357,3 @@ Synchronous: | ||
| #### Lock a global node | ||
| ### Lock a global node | ||
@@ -279,3 +375,3 @@ Synchronous: | ||
| #### Unlock a (previously locked) global node | ||
| ### Unlock a (previously locked) global node | ||
@@ -295,4 +391,34 @@ Synchronous: | ||
| #### Reset a global name (and fixed key) | ||
| ### Merge (or copy) part of one global to another | ||
| In order to use the 'Merge' facility with YottaDB the M support routines should be installed. | ||
| Synchronous (merge from global2 to global1): | ||
| var result = <global1>.merge([<key1>,] <global2> [, <key2>]); | ||
| Asynchronous (merge from global2 to global1): | ||
| <global1>.defined([<key1>,] <global2> [, <key2>], callback(<error>, <result>)); | ||
| Example 1 (merge ^MyGlobal2 to ^MyGlobal1): | ||
| global1 = new mglobal(db, 'MyGlobal1'); | ||
| global2 = new mglobal(db, 'MyGlobal2'); | ||
| global1.merge(global2); | ||
| Example 2 (merge ^MyGlobal2(0) to ^MyGlobal1(1)): | ||
| global1 = new mglobal(db, 'MyGlobal1', 1); | ||
| global2 = new mglobal(db, 'MyGlobal2', 0); | ||
| global1.merge(global2); | ||
| Alternatively: | ||
| global1 = new mglobal(db, 'MyGlobal1'); | ||
| global2 = new mglobal(db, 'MyGlobal2'); | ||
| global1.merge(1, global2, 0); | ||
| ### Reset a global name (and fixed key) | ||
| <global>.reset(<global_name>[, <fixed_key>]); | ||
@@ -311,10 +437,13 @@ | ||
| ### Cursor based data retrieval | ||
| ## <a name="Cursors"></a> Cursor based data retrieval | ||
| This facility provides high-performance techniques for traversing records held in database globals. | ||
| #### Specifying the query | ||
| ### Specifying the query | ||
| The first task is to specify the 'query' for the global traverse. | ||
| query = new mcursor(db, {global: <global_name>, key: [<seed_key>]}[, <options>]); | ||
| Or: | ||
| query = db.mglobalquery({global: <global_name>, key: [<seed_key>]}[, <options>]); | ||
@@ -334,3 +463,3 @@ | ||
| #### Traversing the dataset | ||
| ### Traversing the dataset | ||
@@ -379,3 +508,3 @@ In key order: | ||
| #### Traversing the global directory (return a list of global names) | ||
| ### Traversing the global directory (return a list of global names) | ||
@@ -392,3 +521,3 @@ query = db.mglobalquery({global: <seed_global_name>}, {globaldirectory: true}); | ||
| ### Invocation of database functions | ||
| ## <a name="DBFunctions"></a> Invocation of database functions | ||
@@ -415,8 +544,11 @@ Synchronous: | ||
| ### Direct access to InterSystems classes (IRIS and Cache) | ||
| ## <a name="DBClasses"></a> Direct access to InterSystems classes (IRIS and Cache) | ||
| #### Invocation of a ClassMethod | ||
| ### Invocation of a ClassMethod | ||
| Synchronous: | ||
| result = new mclass(db, <class_name>, <classmethod_name>, <parameters>); | ||
| Or: | ||
| result = db.classmethod(<class_name>, <classmethod_name>, <parameters>); | ||
@@ -432,3 +564,3 @@ | ||
| #### Creating and manipulating instances of objects | ||
| ### Creating and manipulating instances of objects | ||
@@ -448,3 +580,3 @@ The following simple class will be used to illustrate this facility. | ||
| #### Create an entry for a new Person | ||
| ### Create an entry for a new Person | ||
@@ -463,3 +595,3 @@ person = db.classmethod("User.Person", "%New"); | ||
| #### Retrieve an entry for an existing Person | ||
| ### Retrieve an entry for an existing Person | ||
@@ -481,3 +613,3 @@ Retrieve data for object %Id of 1. | ||
| #### Reusing an object container | ||
| ### Reusing an object container | ||
@@ -495,60 +627,15 @@ Once created, it is possible to reuse containers holding previously instantiated objects using the **reset()** method. Using this technique helps to reduce memory usage in the Node.js environment. | ||
| ### Direct access to SQL: MGSQL and InterSystems SQL (IRIS and Cache) | ||
| ## <a name="DBSQL"></a> Direct access to SQL: MGSQL and InterSystems SQL (IRIS and Cache) | ||
| **mg-dbx** provides direct access to the Open Source MGSQL engine ([https://github.com/chrisemunt/mgsql](https://github.com/chrisemunt/mgsql)) and InterSystems SQL (IRIS and Cache). | ||
| In order to use this facility two M routines need to be installed (%zmgsi and %zmgsis). These can be found in the GitHub source code repository ([https://github.com/chrisemunt/mg-dbx](https://github.com/chrisemunt/mg-dbx)) | ||
| In order to use this facility the M support routines should be installed. | ||
| ### Specifying the SQL query | ||
| #### Installation for YottaDB | ||
| The first task is to specify the SQL query. | ||
| The instructions given here assume a standard 'out of the box' installation of **YottaDB** deployed in the following location: | ||
| query = new mcursor(db, {sql: <sql_statement>[, type: <sql_engine>]); | ||
| Or: | ||
| /usr/local/lib/yottadb/r122 | ||
| The primary default location for routines: | ||
| /root/.yottadb/r1.22_x86_64/r | ||
| Copy all the routines (i.e. all files with an 'm' extension) held in the GitHub **/yottadb** directory to: | ||
| /root/.yottadb/r1.22_x86_64/r | ||
| Change directory to the following location and start a **YottaDB** command shell: | ||
| cd /usr/local/lib/yottadb/r122 | ||
| ./ydb | ||
| Link all the **zmgsi** routines and check the installation: | ||
| do ylink^%zmgsi | ||
| do ^%zmgsi | ||
| M/Gateway Developments Ltd - Service Integration Gateway | ||
| Version: 3.2; Revision 3 (1 November 2019) | ||
| Note that the version of **zmgsi** is successfully displayed. | ||
| Finally, add the following lines to the interface file (**cm.ci** in the example used in the db.open() method). | ||
| sqlemg: ydb_char_t * sqlemg^%zmgsis(I:ydb_char_t*, I:ydb_char_t *, I:ydb_char_t *) | ||
| sqlrow: ydb_char_t * sqlrow^%zmgsis(I:ydb_char_t*, I:ydb_char_t *, I:ydb_char_t *) | ||
| sqldel: ydb_char_t * sqldel^%zmgsis(I:ydb_char_t*, I:ydb_char_t *) | ||
| #### Installation for other M systems | ||
| Log in to the Manager UCI and, using the %RI utility (or similar) load the **zmgsi** routines held in **/m/zmgsi.ro**. Change to your development UCI and check the installation: | ||
| do ^%zmgsi | ||
| M/Gateway Developments Ltd - Service Integration Gateway | ||
| Version: 3.2; Revision 3 (1 November 2019) | ||
| #### Specifying the SQL query | ||
| The first task is to specify the SQL query. | ||
| query = db.sql({sql: <sql_statement>[, type: <sql_engine>]); | ||
@@ -566,3 +653,3 @@ | ||
| #### Execute an SQL query | ||
| ### Execute an SQL query | ||
@@ -597,3 +684,3 @@ Synchronous: | ||
| #### Traversing the returned dataset (SQL 'select' queries) | ||
| ### Traversing the returned dataset (SQL 'select' queries) | ||
@@ -623,3 +710,3 @@ In result-set order: | ||
| #### SQL cleanup | ||
| ### SQL cleanup | ||
@@ -636,3 +723,3 @@ For 'select' queries that generate a result-set it is good practice to invoke the 'cleanup' method at the end to delete the result-set held in the database. | ||
| #### Reset an SQL container with a new SQL Query | ||
| ### Reset an SQL container with a new SQL Query | ||
@@ -648,18 +735,67 @@ Synchronous: | ||
| ### Return the version of mg-dbx | ||
| ## <a name="Threads"></a> Using Node.js/V8 worker threads | ||
| var result = db.version(); | ||
| **mg-dbx** functionality can now be used with Node.js/V8 worker threads. This enhancement is available with Node.js v12 (and later). | ||
| Example: | ||
| Use the following constructs for instantiating **mg-dbx** objects in multi-threaded applications: | ||
| console.log("\nmg-dbx Version: " + db.version()); | ||
| // Use: | ||
| var <global> = new mglobal(<db>, <global>); | ||
| // Instead of: | ||
| var <global> = <db>.mglobal(<global>); | ||
| // Use: | ||
| var <cursor> = new mcursor(<db>, <global_query>); | ||
| // Instead of: | ||
| var <cursor> = <db>.mglobalquery(<global_query>) | ||
| // Use: | ||
| var <class> = new mclass(<db>, <classmethod>); | ||
| // Instead of: | ||
| var <class> = <db>.classmethod(<classmethod>); | ||
| ### Close database connection | ||
| // Use: | ||
| var <sql> = new mcursor(<db>, <sqlquery>); | ||
| // Instead of: | ||
| var <sql> = <db>.sql(<sqlquery>); | ||
| db.close(); | ||
| ## License | ||
| The following scheme illustrates how **mg-dbx** should be used in threaded Node.js applications. | ||
| const { Worker, isMainThread, parentPort, threadId } = require('worker_threads'); | ||
| if (isMainThread) { | ||
| // start the threads | ||
| const worker1 = new Worker(__filename); | ||
| const worker2 = new Worker(__filename); | ||
| // process messages received from threads | ||
| worker1.on('message', (message) => { | ||
| console.log(message); | ||
| }); | ||
| worker2.on('message', (message) => { | ||
| console.log(message); | ||
| }); | ||
| } else { | ||
| var dbx = require('mg-dbx').dbx; | ||
| // And as required ... | ||
| var mglobal = require('mg-dbx').mglobal; | ||
| var mcursor = require('mg-dbx').mcursor; | ||
| var mclass = require('mg-dbx').mclass; | ||
| var db = new dbx(); | ||
| db.open(<parameters>); | ||
| var global = new mglobal(db, <global>); | ||
| // do some work | ||
| var result = db.close(); | ||
| // tell the parent that we're done | ||
| parentPort.postMessage("threadId=" + threadId + " Done"); | ||
| } | ||
| ## <a name="License"></a> License | ||
| Copyright (c) 2018-2020 M/Gateway Developments Ltd, | ||
@@ -717,5 +853,14 @@ Surrey UK. | ||
| * Verify that mg-dbx will build and work with Node.js v13.x.x. | ||
| * Verify that **mg-dbx** will build and work with Node.js v13.x.x. | ||
| * Suppress a number of benign 'cast-function-type' compiler warnings when building on the Raspberry Pi. | ||
| ### v1.3.9a (21 April 2020) | ||
| * Verify that **mg-dbx** will build and work with Node.js v14.x.x. | ||
| ### v1.4.11 (6 May 2020) | ||
| * Introduce support for Node.js/V8 worker threads (for Node.js v12.x.x. and later). | ||
| * See the section on 'Using Node.js/V8 worker threads'. | ||
| * Introduce support for the M Merge command. | ||
| * Correct a fault in the mcursor 'Reset' method. |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Native code
Supply chain riskContains native code (e.g., compiled binaries or shared libraries). Including native code can obscure malicious behavior.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by25.6%
3417184
- Number of package files
- increased by15.79%
22
- Number of lines in readme file
- increased by20.98%
836
Worsened metrics
- Number of medium supply chain risk alerts
- increased by16.67%
7
No dependency changes