13
Getting Started with MongoDB and Node.js
You can use several modules to access MongoDB from your Node.js applications. The MongoDB group adopted the MongoDB Node.js driver as the standard method. This driver provides all the functionality and is similar to the native commands available in the MongoDB shell client.
This chapter focuses on getting you started accessing MongoDB from your Node.js applications. You learn how to install the MongoDB Node.js driver and use it to connect to the MongoDB databases. Several sections also cover the processes of creating, accessing, and manipulating databases and collections from your Node.js applications.
Adding the MongoDB Driver to Node.js
The first step in implementing MongoDB access from your Node.js applications is to add the MongoDB driver to your application project. The MongoDB Node.js driver is the officially supported native Node.js driver for MongoDB. It has by far the best implementation and is sponsored by MongoDB.
This book cannot cover all the details about the driver. For additional information, go to http://mongodb.github.io/node-mongodb-native/ to read the documentation for the MongoDB Node.js driver. The documentation is reasonably organized although a bit rough around the edges.
Thanks to the Node.js modular framework, adding the MongoDB Node.js driver to your project is a simple npm command. From your project root directory, execute the following command using a console prompt:
npm install mongodb
A node_modules directory is created if it is not already there, and the mongodb driver module is installed under it. Once that is done, your Node.js application files can use the require('mongodb') command to access the mongodb module functionality.
Connecting to MongoDB from Node.js
Once you have installed the mongodb module using the npm command, you can begin accessing MongoDB from your Node.js applications by opening up a connection to the MongoDB server. The connection acts as your interface to create, update, and access data in the MongoDB database.
Accessing MongoDB is best done through the MongoClient class in the mongodb module. This class provides two main methods to create connections to MongoDB. One is to create an instance of the MongoClient object and then use that object to create and manage the MongoDB connection. The other method uses a connection string to connect. Either of these options works well.
Understanding the Write Concern
Before connecting to and updating data on a MongoDB server, you need to decide what level of write concern you want to implement on your connection. Write concern describes the guarantee that the MongoDB connection provides when reporting on the success of a write operation. The strength of the write concern determines the level of guarantee.
A stronger write concern tells MongoDB to wait until the write has successfully been written to disk completely before responding back, whereas a weaker write concern may only wait until MongoDB has successfully scheduled the change to be written before responding back. The downside of stronger write concerns is speed. The stronger a write concern, the longer MongoDB waits to respond to the client connection, thus making write requests slower.
From a MongoDB driver connection perspective, the write concern can be set to one of the levels listed in Table 13.1. This level is set on the server connection and applies to all connections to the server. If a write error is detected, then an error is returned in the callback function of the write request.
Table 13.1 Write concern levels for MongoDB connections
Level |
Description |
|
Ignores network errors. |
|
No write acknowledgement is required. |
|
Write acknowledgement is requested. |
|
Write acknowledgement is requested across primary and one secondary server in the replica set. |
|
Write acknowledgement is requested across a majority of servers in the replica set. |
Connecting to MongoDB from Node.js Using the MongoClient Object
Using a MongoClient object to connect to MongoDB involves creating an instance of the client, opening a connection to the database, authenticating to the database if necessary, and then handling logout and closure as needed.
To connect to MongoDB via a MongoClient object, first create an instance of the MongoClient object using the following syntax:
var client = new MongoClient();
After you have created the MongoClient, you still need to open a connection to the MongoDB server database using the connect(url, options, callback) method. The url is composed of several components listed in Table 13.2. The following syntax is used for these options:
mongodb://[username:password@]host[:port][/[database][?options]]
For example, to connect to a MongoDB database named MyDB on a host named MyDBServer on port 8088, you would use the following URL:
client.connect('mongodb://MyDBServer:8088/MyDB');
Table 13.2 MongoClient connection url components
Option |
Description |
|
Specifies that this string is using a MongoDB connection format. |
|
(Optional) Specifies the user name to use when authenticating. |
|
(Optional) Specifies the password to use when authenticating. |
|
Specifies the host name or address of the MongoDB server. You can specify multiple |
|
Specifies the port to use when connecting to the MongoDB server. Default is |
|
Specifies the database name to connect to. Default is |
|
Specifies the |
In addition to the connection url information, you can also provide an options object that specifies how the MongoClient object creates and manages the connection to MongoDB. This options object is the second parameter to the connect() method.
For example, the following code shows connecting to MongoDB with a reconnect interval of 500 and a connection timeout of 1000 milliseconds:
client.connect ('mongodb://MyDBServer:8088/MyDB',
{ connectTimeoutMS: 1000,
reconnectInterval: 500 },
function(err, db){ . . . });
Table 13.3 lists the most important settings in the options object that you can set when defining the MongoClient object. The callback method is called back with an error as the first parameter if the connection fails or with a MongoClient object as the second parameter if the connection is successful.
Table 13.3 Options used to create the server object for the MongoClient
Option |
Description |
|
Specifies which read preference to use when reading objects from a replica set. Setting the read preference allows you to optimize read operations. For example, read only from secondary servers to free up primary.
|
|
A Boolean that, when true, specifies that the connection uses SSL. The |
|
Specifies the number of connections to use in the connection pool for the server. Default is |
|
Specifies the amount of time in milliseconds that the server waits between retries. |
|
A Boolean that, when |
|
Sets the read concern for the collection. |
|
Sets the write concern. (See Table 13.1.) |
|
Sets the timeout value of the write concern. |
|
Sets the number of times the server attempts to reconnect. |
|
A Boolean that specifies a no-delay socket. |
|
Specifies the keepalive amount for the socket. |
|
Specifies the amount of time in milliseconds for the connection to wait before timing out. |
|
Specifies the amount of time in milliseconds for a socket send to wait before timing out. |
The callback function accepts an error as the first parameter, and a Db object instance as the second parameter. If an error occurs, the Db object instance will be null; otherwise, you can use it to access the database because the connection will already be created and authenticated.
While in the callback function, you can access the MongoDB database using the Db object passed in as the second parameter. When you are finished with the connection, call close() on the Db object to close the connection.
Listing 13.1 shows an example of using the connection url method. The connection is specified on line 4. Notice that the callback function is passed a Db object that is already authenticated, so no authentication is necessary.
Listing 13.1 db_connect_url.js: Connecting to MongoDB using a connection url
01 var MongoClient = require('mongodb').MongoClient,
02 Server = require('mongodb').Server;
03 var client = new MongoClient();
04 client.connect('mongodb://dbadmin:test@localhost:27017/testDB',
05 { poolSize: 5, reconnectInterval: 500 },
06 function(err, db) {
07 if (err){
08 console.log("Connection Failed Via Client Object.");
09 } else {
10 console.log("Connected Via Client Object . . .");
11 db.logout(function(err, result) {
12 if(!err){
13 console.log("Logged out Via Client Object . . .");
14 }
15 db.close();
16 console.log("Connection closed . . .");
17 });
18 }
Listing 13.1 Output db_connect_url.js: Connecting to MongoDB using a connection url
Connected Via Client Object ... Logged out Via Client Object ... Connection closed ...
Alternatively, you can create the connection and use the db object to authenticate using the username and password parameters. This allows you to connect to MongoDB without including all parameters in the url. In Listing 13.2, this is shown on line 4, where we connect to the database without the username, password, and database specified in the url. Then on line 10 we connect to the testDB database, and on line 13 we authenticate using the username and password.
Listing 13.2 db_connect_object.js: Authenticating using the db object
01 var MongoClient = require('mongodb').MongoClient,
02 Server = require('mongodb').Server;
03 var client = new MongoClient();
04 client.connect('mongodb://localhost:27017'),
05 { poolSize: 5, reconnectInterval: 500, },
06 function(err, db) {
07 if (err){
08 console.log("Connection Failed Via Client Object.");
09 } else {
10 var db = db.db("testDB");
11 } if (db){
12 console.log("Connected Via Client Object . . .");
13 db.authenticate("dbadmin", "test", function(err, results){
14 if (err){
15 console.log("Authentication failed . . .");
16 db.close();
17 console.log("Connection closed . . .");
18 } else {
19 console.log("Authenticated Via Client Object . . .");
20 db.logout(function(err, result) {
21 if(!err){
22 console.log("Logged out Via Client Object . . .");
23 }
24 db.close();
25 console.log("Connection closed . . .");
26 });
27 }
28 });
29 }
30 }
Listing 13.2 Output db_connect_object.js: Authenticating using the db object
Connected Via Client Object . . . Authenticated Via Client Object . . . Logged out Via Client Object . . . Connection closed . . .
Understanding the Objects Used in the MongoDB Node.js Driver
The MongoDB Node.js driver works heavily from structured objects to interact with the database. You have already seen how the MongoClient object provides interactions to connect to the database. Other objects represent interactions with the database, collection, administrative functions, and cursors.
The following sections discuss each of these objects and provide the fundamentals that you need to use to implement database functionality in your Node.js applications. You get more exposure to these objects and methods in the next few chapters as well.
Understanding the Db Object
The Db object inside the MongoDB driver provides access to databases. It acts as a representation of the database allowing you to do things like connect, add users, and access collections. You use Db objects heavily to gain and maintain access to databases that you are interacting with in MongoDB.
A Db object is typically created when you connect to the database as described in the previous section. Table 13.4 lists the methods that can be called once you have a Db object.
Table 13.4 Methods on the Db object
Method |
Description |
|
Connects to the database. The function(error, db){} |
|
Creates a new instance of the |
|
Closes the connection to the database. The function(error, results){} |
|
Returns an instance of an |
|
Retrieves a function(err, cursor){} |
|
Returns a list of the collection names for this database. The function(err, names){} |
Retrieves information about a collection and creates an instance of a function(err, collection){} |
|
|
Retrieves information about all collections in this database and creates an instance of a function(err, collections){} |
|
Logs the user out from the database. The function(error, results){} |
|
Authenticates as a user to this database. You can use this to switch between users while accessing the database. The function(error, results){} |
|
Adds a user to this database. The currently authenticated user needs user administration rights to add the user. The function(error, results){} |
|
Removes a user from the database. The callback function accepts an function(error, results){} |
|
Creates a new collection in the database. The function(error, results){} |
|
Deletes the collection specified by collection name from the database. The function(error, results){} |
|
Renames a collection in the database. The function(error, results){} |
|
Deletes this database from MongoDB. The function(error, results){} |
Understanding the Admin Object
The Admin object is used to perform certain administrative functions on a MongoDB database. The Admin object represents a connection specifically to the admin database and provides functionality not included in the Db object.
The Admin object can be created using the admin() method on an instance of the Db object or by passing a Db object into the constructor. For example, both of the following work fine:
var adminDb = db.admin() var adminDb = new Admin(db)
Table 13.5 lists the important administration methods that can be called from an Admin object. These methods allow you to perform tasks such as ping the MongoDB server, add and remove users from the admin database, and list databases.
Table 13.5 Methods on the Admin object
Method |
Description |
|
Retrieves status information from the MongoDB server. The function(error, status){} |
|
Pings the MongoDB server. This is useful since you can use your Node.js apps to monitor the server connection to MongoDB. The function(error, results){} |
|
Retrieves a list of databases from the server. The callback function accepts an function(error, results){} |
|
Same as for |
|
Same as for |
|
Same as for |
|
Same as for |
Understanding the Collection Object
The Collection object represents a collection in the MongoDB database. You use the collection object to access items in the collection, add documents, query documents, and much more.
A Collection object can be created using the collection() method on an instance of the Db object or by passing a Db object and collection name into the constructor. The collection should already be created on the MongoDB server previously or using the createCollection() method on the Db object. For example, both of the following work fine:
var collection = db.collection()
var collection = new Collection(db, "myCollection")
db.createCollection("newCollection", function(err, collection){ }
Table 13.6 lists the basic methods that can be called from a Collection object. These methods allow you to add and modify documents in the collection, find documents, and delete the collection.
Table 13.6 Basic methods on the Collection object
Method |
Description |
|
Inserts one or more documents into the collection. The function(error, results){} |
|
Deletes documents from the collection. The function(error, results){} |
|
Renames the collection to function(error, results){} |
|
Saves the document specified in the function(error, results){} |
Updates the documents that match the function(error, results){} |
|
|
Creates a function(error, cursor){} |
|
Same as |
|
Performs modifications on documents that match the function(error, results){} |
|
Removes documents that match the function(error, results){} |
|
Creates a list of distinct values for a specific document function(error, values){} |
|
Counts the number of documents in a collection. If a function(error, count){} |
Drops the current collection. The function(error, results){} |
|
|
Retrieves the function(error, stats){} |
Understanding the Cursor Object
When you perform certain operations on MongoDB using the MongoDB Node.js driver, the results come back as a Cursor object. The Cursor object acts as a pointer that can be iterated on to access a set of objects in the database. For example, when you use find(), the actual documents are not returned in the callback function but a Cursor object instead. You can then use the Cursor object to read the items in the results.
Because the Cursor object can be iterated on, an index to the current location is kept internally. That way you can read items one at a time. Keep in mind that some operations only affect the current item in the Cursor and increment the index. Other operations affect all items at the current index forward.
To give you an overview, Table 13.7 lists the basic methods that can be called on the Cursor object. These methods allow you to add and modify documents in the collection, find documents, and delete the collection.
Table 13.7 Basic methods on the Cursor Object
Method |
Description |
|
Iterates on each item in the function(err, item){} |
|
Iterates through the items in the function(err, items){} |
|
Returns the next object in the function(err, item){} |
Resets the |
|
|
Determines the number of items represented by the cursor. The function(err, count){} |
|
Sorts the items represented by the function(err, sortedCursor){} |
|
Closes the |
|
Returns |
Accessing and Manipulating Databases
A great feature of the MongoDB Node.js driver is that it provides the ability to create and manage databases from your Node.js applications. For most installations, you design and implement your databases once and then do not touch them again. However, sometimes it is handy to be able to dynamically create and delete databases.
Listing Databases
To list the databases in your system, you use the listDatabases() method on an Admin object. That means that you need to create an instance of an Admin object first. The list of databases is returned as the second parameter to the callback function and is a simple array of database objects.
The following code shows an example of creating an Admin object and then using it to get a list of the databases on the MongoDB server:
MongoClient.connect("mongodb://localhost/admin", function(err, db) {
var adminDB = db.admin();
adminDB.listDatabases(function(err, databases){
console.log("Before Add Database List: ");
console.log(databases);
});
});
Creating a Database
Just as with the MongoDB shell, there is no explicit method for creation of databases. Databases are created automatically whenever a collection or document is added to them. Therefore, to create a new database all you need to do is to use the db() method on the Db object provided by the MongoClient connection to create a new Db object instance. Then call createCollection() on the new Db object instance to create the database.
The following code shows an example of creating a new database named newDB after connecting to the server:
var MongoClient = require('mongodb').MongoClient;
MongoClient.connect("mongodb://localhost/", function(err, db) {
var newDB = db.db("newDB");
newDB.createCollection("newCollection", function(err, collection){
if(!err){
console.log("New Database and Collection Created");
}
});
});
Deleting a Database
To delete a database from MongoDB, you need to get a Db object instance that points to that database. Then call the dropDatabase() method on that object. It may take a while for MongoDB to finalize the deletion. If you need to verify that the deletion occurred, you can use a timeout to wait for the database delete to occur. For example:
newDB.dropDatabase(function(err, results){
<handle database delete here>
});
Creating, Listing, and Deleting Databases Example
To help solidify your understanding of database operations, Listing 13.3 illustrates the full process of creating, listing, and deleting databases. A connection is made to the MongoDB server, and then in lines 4–7 a listing of the current databases is shown. Then in lines 8 and 9, a new database is created by calling createCollection(). Inside the createCollection() callback handler, the databases are listed again to verify creation.
In lines 15–32 the database is deleted using dropDatabase(). Notice that inside the dropDatabase() callback a setTimeout() timer is implemented to wait for a number of seconds before checking the list of databases to verify that the database was deleted.
Listing 13.3 db_create_list_delete.js: Creating, listing, and deleting databases using the MongoDB Node.js driver
01 var MongoClient = require('mongodb').MongoClient;
02 MongoClient.connect("mongodb://localhost/", function(err, db) {
03 var adminDB = db.admin();
04 adminDB.listDatabases(function(err, databases){
05 console.log("Before Add Database List: ");
06 console.log(databases);
07 });
08 var newDB = db.db("newDB");
09 newDB.createCollection("newCollection", function(err, collection){
10 if(!err){
11 console.log("New Database and Collection Created");
12 adminDB.listDatabases(function(err, databases){
13 console.log("After Add Database List: ");
14 console.log(databases);
15 db.db("newDB").dropDatabase(function(err, results){
16 if(!err){
17 console.log("Database dropped.");
18 setTimeout(function() {
19 adminDB.listDatabases(function(err, results){
20 var found = false;
21 for(var i = 0; i < results.databases.length; i++) {
22 if(results.databases[i].name == "newDB") found = true;
23 }
24 if (!found){
25 console.log("After Delete Database List: ");
26 console.log(results);
27 }
28 db.close();
29 });
30 }, 15000);
31 }
32 });
33 });
34 }
35 });
36 });
Listing 13.3 Output db_create_list_delete.js: Creating, listing, and deleting databases using the MongoDB Node.js driver
New Database and Collection Created
After Add Database List:
{ databases:
[ { name: 'admin', sizeOnDisk: 155648, empty: false },
{ name: 'astro', sizeOnDisk: 73728, empty: false },
{ name: 'local', sizeOnDisk: 73728, empty: false },
{ name: 'newDB', sizeOnDisk: 8192, empty: false },
{ name: 'testDB', sizeOnDisk: 8192, empty: false },
{ name: 'words', sizeOnDisk: 565248, empty: false } ],
totalSize: 884736,
ok: 1 }
After Delete Database List:
{ databases:
[ { name: 'admin', sizeOnDisk: 155648, empty: false },
{ name: 'astro', sizeOnDisk: 73728, empty: false },
{ name: 'local', sizeOnDisk: 73728, empty: false },
{ name: 'testDB', sizeOnDisk: 8192, empty: false },
{ name: 'words', sizeOnDisk: 565248, empty: false } ],
totalSize: 876544,
ok: 1 }
Database dropped.
Getting the Status of the MongoDB Server
Another great feature of the Admin object is the ability to get status information about the MongoDB server. This information includes the host name, version, uptime, open cursors, and much more. You can use this information to determine the health and status of the MongoDB server and then make adjustments in your code to handle problem situations.
To display the status of the MongoDB server, you use the serverStatus() method on the Admin object. Listing 13.4 illustrates creating the Admin object and then calling serverStatus() and displaying the results.
Listing 13.4 db_status.js: Retrieving and displaying the MongoDB server status
1 var MongoClient = require('mongodb').MongoClient;
2 MongoClient.connect("mongodb://localhost/test", function(err, db) {
3 var adminDB = db.admin();
4 adminDB.serverStatus(function(err, status){
5 console.log(status);
6 db.close();
7 });
8 });
Listing 13.4 Output db_status.js: Retrieving and displaying the MongoDB server status
version: '3.4.2', process: 'mongod', pid: 2612, uptime: 44775, uptimeMillis: 44774694, uptimeEstimate: 44774, localTime: 2017-08-11T19:02:25.086Z, asserts: { regular: 0, warning: 0, msg: 0, user: 0, rollovers: 0 }, connections: { current: 1, available: 999999, totalCreated: 8 }, extra_info:
Accessing and Manipulating Collections
A common task for heavily used Node.js installations is the dynamic manipulation of collections. For example, some larger installations give each large customer a separate collection, so as customers sign on or leave, the collections need to be added and deleted. The MongoDB Node.js driver provides easy-to-use methods on the Db and Collection objects that allow you to manipulate the collections on a database.
Listing Collections
To list the collections in a database, you need to start with a Db object that points to the database you want to use. Then you call the collections() method on the Db object. For example:
var newDB = db.db("newDB");
newDB.collections(function(err, collections){})
The collections() method returns an array of objects that contains the names of the collections, for example:
[ { name: 'newDB.system.indexes' },
{ name: 'newDB.newCollection',
options: { create: 'newCollection' } } ]
The resulting value of the collectionList parameter would be an array of Collection objects.
Creating Collections
You have already seen the process of creating a collection. You simply use the createCollection() method on the Db object. For example:
var newDB = db.db("newDB");
newDB.createCollection("newCollection", function(err, collection){ })
The value of the collection parameter of the callback is a Collection object. You can then use this object to perform tasks such as manipulate the collection or add documents.
Deleting Collections
You can delete a collection in two ways: First, you can call dropCollection(name) on the Db object, and second, you can call the drop() method on the collection object, which is sometimes more convenient; for instance, when you are iterating through a list of Collection objects.
The following shows both methods:
var myDB = db.db("myDB ");
myDB.dropCollection("collectionA", function(err, results){ })
myDB.collection("collectionB", function(err, collB){
collB.drop();
})
Collection Creation, Listing, and Deleting Example
To illustrate the process of creating, listing, and deleting collections, Listing 13.5 makes a series of chained callbacks that list the collections, create a new collection, and then delete it. The code is basic and easy to follow.
Listing 13.5 collection_create_list_delete.js: Creating, retrieving, and deleting collections on a MongoDB database
01 var MongoClient = require('mongodb').MongoClient;
02 MongoClient.connect("mongodb://localhost/", function(err, db) {
03 var newDB = db.db("newDB");
04 newDB.collections(function(err, collectionNames){
05 console.log("Initial collections: ");
06 console.log(collectionNames);
07 newDB.createCollection("newCollection", function(err, collection){
08 newDB.collections(function(err, collectionNames){
09 console.log("Collections after creation: ");
10 console.log(collectionNames);
11 newDB.dropCollection("newCollection", function(err, results){
12 newDB.collections(function(err, collectionNames){
13 console.log("Collections after deletion: ");
14 console.log(collectionNames);
15 db.close();
16 });
17 });
18 });
19 });
20 });
21 });
Listing 13.5 Output collection_create_list_delete.js: Creating, retrieving, and deleting collections on a MongoDB database
Initial collections:
[]
Collections after creation:
[ Collection {
s:
{ pkFactory: [Object],
db: [Object],
topology: [Object],
dbName: 'newDB',
options: [Object],
namespace: 'newDB.newCollection',
readPreference: [Object],
slaveOk: true,
serializeFunctions: undefined,
raw: undefined,
promoteLongs: undefined,
promoteValues: undefined,
promoteBuffers: undefined,
internalHint: null,
collectionHint: null,
name: 'newCollection',
promiseLibrary: [Function: Promise],
readConcern: undefined } } ]
Collections after deletion:
[]
Getting Collection Information
Another useful feature of the Collection object is the ability to get the statistics for a particular collection. The statistics can give you an idea of how big the collection is, both in number of documents as well as size on disk. You may want to add code that periodically checks the statistics of your collections to determine whether they need to be cleaned up.
Listing 13.6 shows how to access the statistics for a collection by calling the stats() method on the Collection object.
Listing 13.6 collection_stat.js: Retrieving and displaying the stats for a collection
01 var MongoClient = require('mongodb').MongoClient;
02 MongoClient.connect("mongodb://localhost/", function(err, db) {
03 var newDB = db.db("newDB");
04 newDB.createCollection("newCollection", function(err, collection){
05 collection.stats(function(err, stats){
06 console.log(stats);
07 db.close();
08 });
09 });
10 });
Listing 13.6 Output collection_stat.js: Retrieving and displaying the stats for a collection
{ ns: 'newDB.newCollection',
size: 0,
count: 0,
storageSize: 4096,
capped: false,
wiredTiger:
{ metadata: { formatVersion: 1 },
creationString:
type: 'file',
uri: 'statistics:table:collection-4-8106062778677821448',
Summary
The MongoDB Node.js driver is the officially supported native method for accessing MongoDB from Node.js applications. It is simple to install and easy to incorporate into your Node.js applications. In this chapter you see the various methods and options to connect to a MongoDB database using the MongoClient class. You also got to see and work with the Db, Admin, Collection, and Cursor classes.
The examples in this chapter took you through creating, viewing, and deleting databases dynamically from your Node.js applications. You also learned how to create, access, and delete collections.
Next
In the next chapter, you work with MongoDB documents. You learn the methods to insert documents into a collection and how to access them. You also learn how to manipulate and delete documents using several different methods.