Mongo Client Driver

Objective

SOAJS provides a MongoDB connector to communicate with the database. The Connector is capable of connecting to Static and Multitenant Databases and offers a simple interface to execute DB operations.

Connection Type	Description
Standalone	Creates a connection to a database in mongo.
Multitenant	Creates a connection to a database in mongo based on the tenant code retrieved from the req.soajs.tenant.code. More information on request at this page.

Connecting to a Database

The database configuration is located in the registry and can be retrieved via req.soajs.registry.

This information is then passed on to the Connector so that the later can communicate with Mongo DB.

The following snippet shows the location of both static and multitenant database configurations inside the registry.

Registry section for Database Configuration

"coreDB": {
    "staticdb": {
      "prefix": "",
      "credentials": { /*...*/ },
      "servers": [ /*...*/ ],
      "URLParam": { /*...*/ },
      "extraParam": { /*...*/ },
      "name": "staticdb"
    }
},
"tenantMetaDB": {
    "multitenantdb": {
      "prefix": "",
      "credentials": { /*...*/ },
      "servers": [ /*...*/ ],
      "URLParam": { /*...*/ },
      "extraParam": { /*...*/ },
      "name": "#TENANT_NAME#_multitenantdb"
    }
}

Standalone Databases

The below examples shows how to connect to staticdb who is a static database from the list above, and retrieve some records. The configuration of this database is located under coreDB object:

Connecting to a Standalone Database

//require soajs and initialize a service
var soajs = require('soajs');
var soajsModules = require("soajs.core.module");

var service = new soajs.server.service({...});
service.init(function(){

    //add an api
    service.get("/someAPIroute", function(req, res){

        //fetch the db configuraiton
        var dbConfig = req.soajs.registry.coreDB.staticdb;

        //create a new connection
        var mongo_connector = new soajsModules.mongo(dbConfig);

        //get records from collection
        mongo_connector.find('mycollection', {}, function(error, records){ ..... });

    });

    service.start();
});

Multitenant Databases

Multitenant databases names are dependent on the tenant code: %TENANT_CODE% + dbName.
Therefore additional steps are required to establish a connection to these databases.

Get the Registry DB Info => req.soajs.registry.tenantMetaDB
Get the Tenant Code => req.soajs.tenant.code
Build the DB Configuration using => req.soajs.meta.tenantDB
Connect to Mongo by providing the DB Configuration

The below examples shows how to connect to a multitenant database multitenantdb from the list above, and retrieve some records:

Connecting to a Multitenant Database

//require soajs and initialize a service
var soajs = require('soajs');
var soajsModules = require("soajs.core.module");

var service = new soajs.server.service({...});
service.init(function(){

    //add an api
    service.get("/someAPIroute", function(req, res){

        //fetch the registry info
        var dbRegistry = req.soajs.registry.tenantMetaDB;

        //fetch the tenant code
        var tenantCode = req.soajs.tenant.code;

        //build the db configuration for multitenant databases
        var dbConfig = req.soajs.meta.tenantDB(dbRegistry, "multitenantdb", tenantCode);

        //create a new connection
        var mongo_connector = new soajsModules.mongo(dbConfig);

        //get records from collection
        mongo_connector.find('mycollection', {}, function(error, records){ ..... });

    });

    service.start();
});

Database Operations

SOAJS Mongo Driver allows you to perform database operations to store, retrieve and remove information from the database.
The below table list the available operations and their usage:

Insert

insert object/array of data in the database collection

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
record_to_insert	1	array of objects OR object	true
versioning	2	boolean	false
callback	3	function	true

with versioning

mongo.insert(collection_name, record, true, function(error, response){ ... });

without versioning

mongo.insert(collection_name, record, function(error, response){ ... });

save

save a db record back in the database collection or creates a new one.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
db_record	1	an existing db record	true
versioning	2	boolean	false
callback	3	function	true

command with versioning

mongo.save(collection_name, record, true, function(error, response){ ... });

command without versioning

mongo.save(collection_name, record, function(error, response){ ... });

update

updates a db record in the database collection.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
criteria	1	object to match records against	true
updates	2	object containing the update operation	true
options	3	additional options used by native MongoDB driver	false
versioning	4	boolean	false
callback	5	function	true

command with versioning

mongo.update(collection_name, criteria, updates, options, true, function(error, response){ ... });

command without versioning

mongo.update(collection_name, criteria, updates, options, function(error, response){ ... });

getVersions

returns all the versions of a record from the database.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
recordId	1	id of a database record	true
callback	2	function	true

command

mongo.getVersions(collection_name, recordId, function(error, records){ ... });

clearVersions

removes all the versions of a record from the database.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
recordId	1	id of a database record	true
callback	2	function	true

command

mongo.clearVersions(collection_name, recordId, function(error){ ... });

find

finds records in the database collection.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
criteria	1	object to match records against	false
fields	2	specify optional fields to return only	false
options	3	specify optional operations: sort, limit...	false
callback	4	function	true

command

mongo.find(collection_name, criteria, fields, options, function(error, response){ ... });

findStream

finds records in the database collection and returns them as a Stream

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
criteria	1	object to match records against	false
fields	2	specify optional fields to return only	false
options	3	specify optional operations: sort, limit...	false
callback	4	function	true

command

mongo.findStream(collection_name, criteria, fields, options, function(error, Stream){ ... });

findOne

finds one record in the database collection.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
criteria	1	object to match records against	false
fields	2	specify optional fields to return only	false
callback	3	function	true

command

mongo.findOne(collection_name, criteria, fields. function(error, response){ ... });

remove

removes records from the database collection.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
criteria	1	object to match records against	false
callback	2	function	true

command

mongo.remove(collection_name, criteria, function(error){ ... });

count

returns the count of records from the database collection.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
criteria	1	object to match records against	false
callback	2	function	true

command

mongo.count(collection_name, criteria, function(error, count){ ... });

distinct

returns distinct values for a specific field the database collection.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
field	1	the name of the field	true
callback	2	function	true

command

mongo.distinct(collection_name, field, function(error, values){ ... });

distinctStream

returns distinct values for a specific field the database collection as a stream.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
field	1	the name of the field	true
criteria	2	criteria to match against	false
options	3	additional group options	false
callback	4	function	true

command

mongo.distinctStream(collection_name, field, criteria, options, function(error, stream){ ... });

aggregate

aggregates data in a collection based on the given criteria.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
options	1	Object containing aggregation criteria	true
callback	2	function	true

command

mongo.aggregate(collection_name, options, function(error, values){ ... });

aggregateStream

aggregates data in a collection based on the given criteria and returns the response as a stream.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
options	1	Object containing aggregation criteria	true
callback	2	function	true

command

mongo.aggregateStream(collection_name, options, function(error, stream){ ... });

getCollection

returns a pointer to the collection.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
callback	1	function	true

command

mongo.getCollection(collection_name, function(error, collection){ ... });

createIndex

Indexes the given collection.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
keys	1	object containing the indexes	true
options	2	additional optional options: unique, sparse...	true
callback	3	function	true

Command

mongo.createIndex(collection_name, keys, options, function(error){ ... });

ensureIndex (Deprecated)

Indexes the given collection.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
keys	1	object containing the indexes	true
options	2	additional optional options: unique, sparse...	true
callback	3	function	true

command

mongo.ensureIndex(collection_name, keys, options, function(error){ ... });

dropCollection

drops a collection.

Parameters

Parameter	Order	Type	Mandatory
collection_name	0	string	true
callback	1	function	true

command

mongo.dropCollection(collection_name, function(error){ ... });

dropDatabase

drops the database.

Parameters

Parameter	Order	Type	Mandatory
callback	0	function	true

command

mongo.dropDatabase(function(error){ ... });

flushDb

Flush the connection to the database.

Parameters

Parameter	Order	Type	Mandatory
N/A

command

mongo.flushDb();

closeDb

closes the connection to the database.

Parameters

Parameter	Order	Type	Mandatory
N/A

command

mongo.closeDb();

getMongoDB

returns a reference to the database connector

Parameters

Parameter	Order	Type	Mandatory
callback	0	function	true

command

mongo.getMongoDB(function(error, dbRef){ ... });