node-red-contrib-mongodb4

A MongoDB driver node for Node-Red without limitations.

This package includes two nodes for node-red:

The Config Node

Connect to your local MongoDB Server or a MongoDB Atlas cluster.

The Flow Node

Execute a database or collection operation within your flow. This node was developed to use all the features of the native MongoDB driver without any limitations.

This node was inspired by other projects like node-red-contrib-mongodb3 or node-red-node-mongodb.

Installation

Navigate to your .node-red directory - typically ~/.node-red.

npm install --save --omit=dev node-red-contrib-mongodb4

Compatibility

The latest version of [email protected] is compatible with the following MongoDB server versions: 7.0, 6.0, 5.0, 4.4, 4.2, 4.0, 3.6

Node-RED >= v2.0.0,
NodeJS >= v14.20.1.

Upgrade to [email protected]

Version 2.x of this node-red node is now using the mongodb driver version 5.x.

Driver versions 5.x are not compatible with Node.js v12 or earlier. If you want to use this version of the driver, you must use Node.js v14.20.1 or greater.

The upgraded driver removes support for the Collection.insert(), Collection.update(), and Collection.remove() helper methods. The following list provides instructions on how to replace the functionality of the removed methods:

• Migrate from Collection.insert() to insertOne() or insertMany()
• Migrate from Collection.update() to updateOne() or updateMany()
• Migrate from Collection.remove() to deleteOne() or deleteMany()

Usage Example

Import the example flow to get a quick introduction how to use this node.
flow.json

The Configuration Node

Configuration node for MongoDB connection config. This node will create a MongoDB client, with a connection pool for operation nodes.

Simple Connection URI

• Protocol - mongodb or mongodb+srv

• Hostname - Hostname / IP to connect to MongoDB

• Port - Optional port number. In most cases 27017.

Advanced Connection URI

• URI - Define your own connection string in URI format. Read the docs: Connection String in URI Format

Authentication (optional)

• Username - Username for authentication.

• Password - Password for authentication.

• AuthMech - Specify the authentication mechanism that MongoDB will use to authenticate the connection. This will only be used in combination with username and password.

• AuthSource - Specify the database name associated with the user’s credentials.

Application

• Database - A MongoDB database name is required.

• Application Name - The name of the application that created this MongoClient instance. MongoDB 3.4 and newer will print this value in the server log upon establishing each connection. It is also recorded in the slow query log and profile collections.

If this field is unspecified, the client node will create a app name for you. That looks like this: nodered-azmr5z97. The prefix nodered is static. azmr5z97 is a random connection pool id, created on runtime start-up, config-node update and full deployment.

The current app name of a config node is logged to the node-red runtime log.

Check the current db connections with this query:

db.currentOp(true).inprog.reduce((accumulator, connection) => {
    const appName = connection.appName || "unknown";
    accumulator[appName] = (accumulator[appName] || 0) + 1;
    accumulator.totalCount ++;
    return accumulator;
  }, {totalCount: 0})

TLS (optional)

• TLS CA File (path) - Specifies the location of a local .pem file that contains the root certificate chain from the Certificate Authority. This file is used to validate the certificate presented by the mongod/mongos instance.

• TLS Certificate Key File (path) - Specifies the location of a local .pem file that contains either the client's TLS/SSL certificate and key or only the client's TLS/SSL key when tlsCertificateFile is used to provide the certificate.

• TLS Certificate Key Filepassword (string) - Specifies the password to de-crypt the TLS certificate.

• TLS-Insecure - Disables various certificate validations. THIS IS REALLY NOT SECURE.

Connect Options

• ConnectTimeoutMS - Specifies the amount of time, in milliseconds, to wait to establish a single TCP socket connection to the server before raising an error.

• SocketTimeoutMS - To make sure that the driver correctly closes the socket in these cases, set the SocketTimeoutMS option. When a MongoDB process times out, the driver will close the socket. We recommend that you select a value for socketTimeoutMS that is two to three times as long as the expected duration of the slowest operation that your application executes.

If you set the value of ConnectTimeoutMS or SocketTimeoutMS to 0, your application will use the operating system's default socket timeout value.

• MinPoolSize / MaxPoolsize - Specifies the minimun and maximum number of connections the driver should create in its connection pool. This count includes connections in use.

• MaxIdleTimeMS - Specifies the amount of time, in milliseconds, a connection can be idle before it's closed. Specifying 0 means no minimum.

More Options

• Options (JSON) - MongoDB Driver 4 MongoClient supports more options. Feel free to overwrite all client options with your own. Read the docs: MongoClientOptions

Connection Pools

Each configuration node has his own connection pool with a default max poolsize of 100 connection at a given time. More parallel connections / operations will be queued and processed synchronous. In this scenario slow operations will delay fast operations. You can create more separat connection pools with more configuration nodes. More Information

The Flow Node

Execute MongoDB collection operations with this node.

Inputs / Options

• Connection (mongodb-client) - Select a MongoDB database server connection.

• Mode | msg.mode (string) - Decide if you want to run a collection or db operation {'collection', 'db'}

• Collection | msg.collection (string) - MongoDB database collection.

• Operation | msg.operation (string) - Run a collection or database operation.

Common collection operations are find, findOne, insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany, aggregate and more.

insert, update and delete are deprecated and not supported by the latest mongodb driver version. Read the upgrade instructions for more information.

Common database operations are command, ping, stats and more.

• msg.payload (array) - Pass the CRUD operation arguments as message payload. Message payload has to be array type to pass multiple function arguments to a driver operation.

Example insertOne:

msg.payload = [{name: 'Anna', age: 1}];

Example find:

// find query argument
const query = {
  age: 22
};
// find option argument
const options = {
  sort: {name: 1},
  projection: {name: 1},
  limit: 10,
  skip: 2
};
// payload for mongodb4 node
msg.payload = [query, options];
return msg;

The payload array will be passed as function arguments for the MongoDB driver collection operation : collection.find({age: 22}, {sort: {...}})

Another example for an aggregation call:

// aggregation pipeline
const pipeline = [{
    $sort:{age: 1}
}, {
    $project: {
        name: 1
    }
},{
    $limit: 10
}];
// optional: aggregate options
const options = {
    allowDiskUse: true
};
// payload for mongodb4 node
msg.payload = [pipeline, options];
return msg;

In a simple aggregation call you have an array inside array like msg.payload = [pipeline]. This might be confusing, but I haven't found a better solution for that.

• Output - For find and aggregate operation. Choose toArray or forEach output type.

• MaxTimeMS - MaxTimeMS Specifies the maximum amount of time the server should wait for an operation to complete after it has reached the server. If an operation runs over the specified time limit, it returns a timeout error. Prevent long-running operations from slowing down the server by specifying a timeout value. Specifying 0 means no timeout.

• Handle document _id (deprecated) - With this feature enabled, the operation node will search for _id fields of type string to convert them into document _id of type ObjectId. Be aware that not every _id field has to be a ObjectId field. Use this feature only if necessary. A better solution is to use explicit BSON types in your query (Read: How to use BSON Types).

The default MongoDB document identifier has to be of type ObjectId. This means the native driver expects query arguments like: msg.payload = [{_id: new ObjectId("624b527d08e23628e99eb963")}]

This mongodb node can handle this for you. If the string is a valid ObjectId, it will be translated into a real ObjectId before executed by the native driver. So this will work: msg.payload = [{_id: "624b527d08e23628e99eb963"}] ...and this will also work: msg.payload = [{_id: {$in: ["624b527d08e23628e99eb963"]}}]

More information about collection operations

Collection-API v5.9

Payload Output

The node will output the database driver response as message payload. The operations aggregate and find can output with toArray or forEach.

How to use BSON data types with this Node

You can use BSON types with this node.

First enable "mongodb" in your function global context. Add this to your settings.js file - typically this file located in ~/.node-red:

functionGlobalContext: {
    mongodb: require("node-red-contrib-mongodb4/node_modules/mongodb")
},

This kind of require statement ensures that we use the BSON types from the mongodb driver used in this node. Otherwise we could run into compatibilty issues.

You can now use BSON types in your function node like so:

// get BSON types
const {ObjectId, Double, Timestamp} = global.get("mongodb");
// write your query
msg.payload = [{
    _id: new ObjectId() , 
    value: new Double(1.4), 
    ts: new Timestamp()
}];
// send them to the mongodb node
return msg;

More general driver information

Visit the MongoDB Driver Docs