Class: Db

Methods

addUser(username, password, options, callback){Promise}

lib/db.js, line 1362

Add a user to the database.

Name	Type	Default	Description
username	string		The username.
password	string		The password.
options	object	null	optional Optional settings. Name Type Default Description w number | string null optional The write concern. wtimeout number null optional The write concern timeout. j boolean false optional Specify a journal write concern. customData object null optional Custom data associated with the user (only Mongodb 2.6 or higher) roles Array.<object> null optional Roles associated with the created user (only Mongodb 2.6 or higher)
callback	Db~resultCallback		optional The command result callback

Returns:

Promise if no callback passed

Examples

// An example of adding a user to the database.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Add a user to the database
  db.addUser('user', 'name', function(err, result) {
    test.equal(null, err);

    // Remove the user from the db
    db.removeUser('user', function(err, result) {
      test.equal(null, err);

      db.close();
    });
  });
});

// An example of adding a user to the database using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Add a user to the database
  db.addUser('user', 'name').then(function(result) {

    // Remove the user from the db
    db.removeUser('user').then(function(result) {
      db.close();
    });
  });
});

// An example of adding a user to the database using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');
  // Add a user to the database
  yield db.addUser('user', 'name');

  // Remove the user from the db
  yield db.removeUser('user');
  db.close();
});

admin(){Admin}

lib/db.js, line 404

Return the Admin db instance

Returns:

the new Admin db instance

Example

// Example showing how to access the Admin database for admin level operations.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Use the admin database for the operation
  var adminDb = db.admin()
  test.ok(adminDb != null);

  db.close();
});

authenticate(username, password, options, callback){Promise}

lib/db.js, line 1488

Authenticate a user against the server.

Name	Type	Default	Description
username	string		The username.
password	string		optional The password.
options	object	null	optional Optional settings. Name Type Default Description authMechanism string MONGODB-CR optional The authentication mechanism to use, GSSAPI, MONGODB-CR, MONGODB-X509, PLAIN
callback	Db~resultCallback		optional The command result callback

Deprecated

• This method will no longer be available in the next major release 3.x as MongoDB 3.6 will only allow auth against users in the admin db and will no longer allow multiple credentials on a socket. Please authenticate using MongoClient.connect with auth credentials.

Returns:

Promise if no callback passed

Examples

// An example of using the authenticate command.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Add a user to the database
  db.addUser('user2', 'name', function(err, result) {
    test.equal(null, err);

    // Authenticate
    db.authenticate('user2', 'name', function(err, result) {
      test.equal(true, result);

      // Remove the user from the db
      db.removeUser('user2', function(err, result) {
        test.equal(null, err);

        db.close();
      });
    });
  });
});

// An example of using the authenticate command with a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Add a user to the database
  db.addUser('user2', 'name').then(function(result) {

    // Authenticate
    db.authenticate('user2', 'name').then(function(result) {
      test.equal(true, result);

      // Remove the user from the db
      db.removeUser('user2').then(function(result) {
        db.close();
      });
    });
  });
});

// An example of using the authenticate command with a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');
  // Add a user to the database
  yield db.addUser('user2', 'name');

  // Authenticate
  var result = yield db.authenticate('user2', 'name');
  test.equal(true, result);

  // Remove the user from the db
  yield db.removeUser('user2');
  db.close();
});

close(force, callback){Promise}

lib/db.js, line 363

Close the db and its underlying connections

Name	Type	Description
force	boolean	Force close, emitting no events
callback	Db~noResultCallback	optional The result callback

Returns:

Promise if no callback passed

Examples

// An example that shows how to force close a db connection so it cannot be reused.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Fetch a collection
  var collection = db.collection('shouldCorrectlyFailOnRetryDueToAppCloseOfDb');

  // Insert a document
  collection.insertOne({a:1}, {w:1}, function(err, result) {
    test.equal(null, err);

    // Force close the connection
    db.close(true, function(err, result) {
      // Attemp to insert should fail now with correct message 'db closed by application'
      collection.insertOne({a:2}, {w:1}, function(err, result) {
        test.ok(err != null);

        db.close();
      });
    });
  });
});

// An example of a simple single server db connection and close function

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Close the connection with a callback that is optional
  db.close(function(err, result) {
    test.equal(null, err);

  });
});

// An example that shows how to force close a db connection so it cannot be reused using a Promise..

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Fetch a collection
  var collection = db.collection('shouldCorrectlyFailOnRetryDueToAppCloseOfDb_with_promise');
  // Insert a document
  collection.insertOne({a:1}, {w:1}).then(function(result) {

    // Force close the connection
    db.close(true).then(function() {
      // Attemp to insert should fail now with correct message 'db closed by application'
      collection.insertOne({a:2}, {w:1}).then(function(result) {
      }).catch(function(err) {
        db.close();
      });
    });
  });
});

// An example of a simple single server db connection and close function using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Close the connection with a callback that is optional
  db.close().then(function(result) {
  });
});

// An example that shows how to force close a db connection so it cannot be reused using a Generator and the co module..

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');

  // Fetch a collection
  var collection = db.collection('shouldCorrectlyFailOnRetryDueToAppCloseOfDb_with_generators');
  // Insert a document
  yield collection.insertOne({a:1}, {w:1});

  // Force close the connection
  yield db.close(true)

  try {
    // Attemp to insert should fail now with correct message 'db closed by application'
    yield collection.insertOne({a:2}, {w:1});
  } catch(err) {
    db.close();
  }
});

collection(name, options, callback){Collection}

lib/db.js, line 440

Fetch a specific collection (containing the actual collection information). If the application does not use strict mode you can
can use it without a callback in the following way: var collection = db.collection('mycollection');

Name	Type	Default	Description
name	string		the collection name we wish to access.
options	object	null	optional Optional settings. Name Type Default Description w number | string null optional The write concern. wtimeout number null optional The write concern timeout. j boolean false optional Specify a journal write concern. raw boolean false optional Return document results as raw BSON buffers. pkFactory object null optional A primary key factory object for generation of custom _id keys. readPreference ReadPreference | string null optional The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST). serializeFunctions boolean false optional Serialize functions on any object. strict boolean false optional Returns an error if the collection does not exist readConcern object null optional Specify a read concern for the collection. (only MongoDB 3.2 or higher supported) Name Type Default Description level object 'local' optional Specify a read concern level for the collection operations, one of [local|majority]. (only MongoDB 3.2 or higher supported)
callback	Db~collectionResultCallback		The collection result callback

Returns:

the new Collection instance if not in strict mode

Examples

// An example of retrieving a collection from a db using the collection function.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Grab a collection without a callback no safe mode
  var col1 = db.collection('test_correctly_access_collections');

  // Grab a collection with a callback but no safe operation
  db.collection('test_correctly_access_collections', function(err, col2) {
    test.equal(null, err);

    // Grab a collection with a callback in safe mode, ensuring it exists (should fail as it's not created)
    db.collection('test_correctly_access_collections', {strict:true}, function(err, col3) {
      test.ok(err != null);

      // Create the collection
      db.createCollection('test_correctly_access_collections', function(err, result) {

        // Retry to get the collection, should work as it's now created
        db.collection('test_correctly_access_collections', {strict:true}, function(err, col3) {
          test.equal(null, err);

          db.close();
        });
      });
    });
  });
});

// An example of retrieving a collection from a db using the collection function with a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Grab a collection without a callback no safe mode
  var col1 = db.collection('test_correctly_access_collections_with_promise');
  // Grab a collection with a callback but no safe operation
  db.collection('test_correctly_access_collections_with_promise', function(err, col2) {

    // Grab a collection with a callback in safe mode, ensuring it exists (should fail as it's not created)
    db.collection('test_correctly_access_collections_with_promise', {strict:true}, function(err, col3) {
      // Create the collection
      db.createCollection('test_correctly_access_collections_with_promise').then(function(err, result) {

        // Retry to get the collection, should work as it's now created
        db.collection('test_correctly_access_collections_with_promise', {strict:true}, function(err, col3) {
          db.close();
        });
      });
    });
  });
});

collections(callback){Promise}

lib/db.js, line 957

Fetch all collections for the current db.

Name	Type	Description
callback	Db~collectionsResultCallback	optional The results callback

Returns:

Promise if no callback passed

Examples

// An example of retrieving all collections for a db as Collection objects

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Create the collection
  var collection = db.collection('test_correctly_access_collections2');
  // Retry to get the collection, should work as it's now created
  db.collections(function(err, collections) {
    test.equal(null, err);
    test.ok(collections.length > 0);

    db.close();
  });
});

// An example of retrieving all collections for a db as Collection objects using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Create the collection
  var collection = db.collection('test_correctly_access_collections2_with_promise');
  // Retry to get the collection, should work as it's now created
  db.collections().then(function(collections) {
    test.ok(collections.length > 0);

    db.close();
  });
});

// An example of retrieving all collections for a db as Collection objects using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');
  // Create the collection
  var collection = db.collection('test_correctly_access_collections2_with_generators');
  // Retry to get the collection, should work as it's now created
  var collections = yield db.collections();
  test.ok(collections.length > 0);

  db.close();
});

command(command, options, callback){Promise}

lib/db.js, line 329

Execute a command

Name	Type	Default	Description
command	object		The command hash
options	object	null	optional Optional settings. Name Type Default Description readPreference ReadPreference | string null optional The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
callback	Db~resultCallback		optional The command result callback

Returns:

Promise if no callback passed

Examples

// A simple example executing a command against the server.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Execute ping against the server
  db.command({ping:1}, function(err, result) {
    test.equal(null, err);

    db.close();
  });
});

// A simple example executing a command against the server using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Execute ping against the server
  db.command({ping:1}).then(function(result) {
    db.close();
  });
});

// A simple example executing a command against the server using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');
  // Execute ping against the server
  yield db.command({ping:1});
  db.close();
});

createCollection(name, options, callback){Promise}

lib/db.js, line 581

Create a new collection on a server with the specified options. Use this to create capped collections.
More information about command options available at https://www.mongodb.com/docs/manual/reference/command/create/

Name	Type	Default	Description
name	string		the collection name we wish to access.
options	object	null	optional Optional settings. Name Type Default Description w number | string null optional The write concern. wtimeout number null optional The write concern timeout. j boolean false optional Specify a journal write concern. raw boolean false optional Return document results as raw BSON buffers. pkFactory object null optional A primary key factory object for generation of custom _id keys. readPreference ReadPreference | string null optional The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST). serializeFunctions boolean false optional Serialize functions on any object. strict boolean false optional Returns an error if the collection does not exist capped boolean false optional Create a capped collection. autoIndexId boolean true optional Create an index on the _id field of the document, True by default on MongoDB 2.2 or higher off for version < 2.2. size number null optional The size of the capped collection in bytes. max number null optional The maximum number of documents in the capped collection. flags number null optional Optional. Available for the MMAPv1 storage engine only to set the usePowerOf2Sizes and the noPadding flag. storageEngine object null optional Allows users to specify configuration to the storage engine on a per-collection basis when creating a collection on MongoDB 3.0 or higher. validator object null optional Allows users to specify validation rules or expressions for the collection. For more information, see Document Validation on MongoDB 3.2 or higher. validationLevel string null optional Determines how strictly MongoDB applies the validation rules to existing documents during an update on MongoDB 3.2 or higher. validationAction string null optional Determines whether to error on invalid documents or just warn about the violations but allow invalid documents to be inserted on MongoDB 3.2 or higher. indexOptionDefaults object null optional Allows users to specify a default configuration for indexes when creating a collection on MongoDB 3.2 or higher. viewOn string null optional The name of the source collection or view from which to create the view. The name is not the full namespace of the collection or view; i.e. does not include the database name and implies the same database as the view to create on MongoDB 3.4 or higher. pipeline array null optional An array that consists of the aggregation pipeline stage. create creates the view by applying the specified pipeline to the viewOn collection or view on MongoDB 3.4 or higher. collation object null optional Specify collation (MongoDB 3.4 or higher) settings for update operation (see 3.4 documentation for available fields).
callback	Db~collectionResultCallback		optional The results callback

Returns:

Promise if no callback passed

Examples

// A simple example showing the creation of a collection.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Create a capped collection with a maximum of 1000 documents
  db.createCollection("a_simple_collection", {capped:true, size:10000, max:1000, w:1}, function(err, collection) {
    test.equal(null, err);

    // Insert a document in the capped collection
    collection.insertOne({a:1}, {w:1}, function(err, result) {
      test.equal(null, err);

      db.close();
    });
  });
});

// A simple example showing the listening to a capped collection

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Create a capped collection with a maximum of 1000 documents
  db.createCollection("a_simple_collection_2", {capped:true, size:100000, max:10000, w:1}, function(err, collection) {
    test.equal(null, err);

    var docs = [];
    for(var i = 0; i < 1000; i++) docs.push({a:i});

    // Insert a document in the capped collection
    collection.insertMany(docs, {w:1}, function(err, result) {

      // Start date
      var s = new Date();
      var total = 0;

      // Get the cursor
      var cursor = collection.find({})
        .addCursorFlag('tailable', true)
        .addCursorFlag('awaitData', true);

      cursor.on('data', function() {
        total = total + 1;

        if(total == 1000) {
          cursor.kill();
        }
      });

      cursor.on('end', function() {
        db.close();
      });
    });
  });
});

// A simple example showing the creation of a collection using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Create a capped collection with a maximum of 1000 documents
  db.createCollection("a_simple_collection_with_promise", {capped:true, size:10000, max:1000, w:1}).then(function(collection) {

    // Insert a document in the capped collection
    collection.insertOne({a:1}, {w:1}).then(function(result) {
      db.close();
    });
  });
});

// A simple example showing the listening to a capped collection using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Create a capped collection with a maximum of 1000 documents
  db.createCollection("a_simple_collection_2_with_promise", {capped:true, size:100000, max:10000, w:1}).then(function(collection) {
    var docs = [];
    for(var i = 0; i < 1000; i++) docs.push({a:i});

    // Insert a document in the capped collection
    collection.insertMany(docs, {w:1}).then(function(result) {
      // Start date
      var s = new Date();
      var total = 0;

      // Get the cursor
      var cursor = collection.find({a: {$gte:0}})
        .addCursorFlag('tailable', true)
        .addCursorFlag('awaitData', true)

      cursor.on('data', function(d) {
        total = total + 1;

        if(total == 1000) {
          cursor.kill();
        }
      });

      cursor.on('end', function() {
        console.dir(new Date().getTime() - s.getTime())
        test.ok((new Date().getTime() - s.getTime()) > 1000);

        db.close();
      });
    });
  });
});

// A simple example showing the creation of a collection using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');
  // Create a capped collection with a maximum of 1000 documents
  var collection = yield db.createCollection("a_simple_collection_with_generators", {capped:true, size:10000, max:1000, w:1});

  // Insert a document in the capped collection
  yield collection.insertOne({a:1}, {w:1});
  db.close();
});

// A simple example showing the listening to a capped collection using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');
  // Create a capped collection with a maximum of 1000 documents
  var collection = yield db.createCollection("a_simple_collection_2_with_generators", {capped:true, size:100000, max:10000, w:1});
  var docs = [];
  for(var i = 0; i < 1000; i++) docs.push({a:i});

  // Insert a document in the capped collection
  yield collection.insertMany(docs, {w:1});
  // Start date
  var s = new Date();
  var total = 0;

  // Get the cursor
  var cursor = collection.find({})
    .addCursorFlag('tailable', true)
    .addCursorFlag('awaitData', true)

  cursor.on('data', function() {
    total = total + 1;

    if(total == 1000) {
      cursor.kill();
    }
  });

  cursor.on('end', function() {
    db.close();
  });
});

createIndex(name, fieldOrSpec, options, callback){Promise}

lib/db.js, line 1037

Creates an index on the db and collection collection.

Name	Type	Default	Description
name	string		Name of the collection to create the index on.
fieldOrSpec	string | object		Defines the index.
options	object	null	optional Optional settings. Name Type Default Description w number | string null optional The write concern. wtimeout number null optional The write concern timeout. j boolean false optional Specify a journal write concern. unique boolean false optional Creates an unique index. sparse boolean false optional Creates a sparse index. background boolean false optional Creates the index in the background, yielding whenever possible. dropDups boolean false optional A unique index cannot be created on a key that has pre-existing duplicate values. If you would like to create the index anyway, keeping the first document the database indexes and deleting all subsequent documents that have duplicate value min number null optional For geospatial indexes set the lower bound for the co-ordinates. max number null optional For geospatial indexes set the high bound for the co-ordinates. v number null optional Specify the format version of the indexes. expireAfterSeconds number null optional Allows you to expire data on indexes applied to a data (MongoDB 2.2 or higher) name number null optional Override the autogenerated index name (useful if the resulting name is larger than 128 bytes) partialFilterExpression object null optional Creates a partial index based on the given filter object (MongoDB 3.2 or higher)
callback	Db~resultCallback		optional The command result callback

Returns:

Promise if no callback passed

Examples

// A more complex createIndex using a compound unique index in the background and dropping duplicated documents

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection we want to drop later
  var collection = db.collection('more_complex_index_test');
  // Insert a bunch of documents for the index
  collection.insertMany([{a:1, b:1}
    , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {w:1}, function(err, result) {
    test.equal(null, err);

    // Create an index on the a field
    db.createIndex('more_complex_index_test', {a:1, b:1}
      , {unique:true, background:true, w:1}, function(err, indexName) {

      // Show that duplicate records got dropped
      collection.find({}).toArray(function(err, items) {
        test.equal(null, err);
        test.equal(4, items.length);

        // Perform a query, with explain to show we hit the query
        collection.find({a:2}).explain(function(err, explanation) {
          test.equal(null, err);
          test.ok(explanation != null);

          db.close();
        });
      })
    });
  });
});

// A more complex createIndex using a compound unique index in the background and dropping duplicated documents using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection we want to drop later
  var collection = db.collection('more_complex_index_test_with_promise');
  // Insert a bunch of documents for the index
  collection.insertMany([{a:1, b:1}
    , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {w:1}).then(function(result) {

    // Create an index on the a field
    db.createIndex('more_complex_index_test_with_promise', {a:1, b:1}
      , {unique:true, background:true, w:1}).then(function(indexName) {

      // Show that duplicate records got dropped
      collection.find({}).toArray().then(function(items) {
        test.equal(4, items.length);

        // Perform a query, with explain to show we hit the query
        collection.find({a:2}).explain().then(function(explanation) {
          test.ok(explanation != null);

          db.close();
        });
      })
    });
  });
});

// A more complex createIndex using a compound unique index in the background and dropping duplicated documents using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');

  // Create a collection we want to drop later
  var collection = db.collection('more_complex_index_test_with_generators');
  // Insert a bunch of documents for the index
  yield collection.insertMany([{a:1, b:1}
    , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {w:1});

  // Create an index on the a field
  yield db.createIndex('more_complex_index_test_with_generators', {a:1, b:1}
    , {unique:true, background:true, w:1});

  // Show that duplicate records got dropped
  var items = yield collection.find({}).toArray();
  test.equal(4, items.length);

  // Perform a query, with explain to show we hit the query
  var explanation = yield collection.find({a:2}).explain();
  test.ok(explanation != null);

  db.close();
});

db(name, options){Db}

lib/db.js, line 1188

Create a new Db instance sharing the current socket connections. Be aware that the new db instances are
related in a parent-child relationship to the original instance so that events are correctly emitted on child
db instances. Child db instances are cached so performing db('db1') twice will return the same instance.
You can control these behaviors with the options noListener and returnNonCachedInstance.

Name	Type	Default	Description
name	string		The name of the database we want to use.
options	object	null	optional Optional settings. Name Type Default Description noListener boolean false optional Do not make the db an event listener to the original connection. returnNonCachedInstance boolean false optional Control if you want to return a cached instance or have a new one created

Examples

// Simple example connecting to two different databases sharing the socket connections below.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Reference a different database sharing the same connections
  // for the data transfer
  var secondDb = db.db("integration_tests_2");

  // Fetch the collections
  var multipleColl1 = db.collection("multiple_db_instances");
  var multipleColl2 = secondDb.collection("multiple_db_instances");

  // Write a record into each and then count the records stored
  multipleColl1.insertOne({a:1}, {w:1}, function(err, result) {
    multipleColl2.insertOne({a:1}, {w:1}, function(err, result) {

      // Count over the results ensuring only on record in each collection
      multipleColl1.count(function(err, count) {
        test.equal(1, count);

        multipleColl2.count(function(err, count) {
          test.equal(1, count);

          db.close();
        });
      });
    });
  });
});

// Simple example connecting to two different databases sharing the socket connections below using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Reference a different database sharing the same connections
  // for the data transfer
  var secondDb = db.db("integration_tests_2");

  // Fetch the collections
  var multipleColl1 = db.collection("multiple_db_instances_with_promise");
  var multipleColl2 = secondDb.collection("multiple_db_instances_with_promise");

  // Write a record into each and then count the records stored
  multipleColl1.insertOne({a:1}, {w:1}).then(function(result) {
    multipleColl2.insertOne({a:1}, {w:1}).then(function(result) {

      // Count over the results ensuring only on record in each collection
      multipleColl1.count().then(function(count) {
        test.equal(1, count);

        multipleColl2.count().then(function(count) {
          test.equal(1, count);

          db.close();
        });
      });
    });
  });
});

// Simple example connecting to two different databases sharing the socket connections below using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');
  // Reference a different database sharing the same connections
  // for the data transfer
  var secondDb = db.db("integration_tests_2");

  // Fetch the collections
  var multipleColl1 = db.collection("multiple_db_instances_with_generators");
  var multipleColl2 = secondDb.collection("multiple_db_instances_with_generators");

  // Write a record into each and then count the records stored
  yield multipleColl1.insertOne({a:1}, {w:1});
  yield multipleColl2.insertOne({a:1}, {w:1})

  // Count over the results ensuring only on record in each collection
  var count = yield multipleColl1.count();
  test.equal(1, count);

  var count = yield multipleColl2.count();
  test.equal(1, count);

  db.close();
});

dropCollection(name, callback){Promise}

lib/db.js, line 841

Drop a collection from the database, removing it permanently. New accesses will create a new collection.

Name	Type	Description
name	string	Name of collection to drop
callback	Db~resultCallback	optional The results callback

Returns:

Promise if no callback passed

Examples

// A simple example creating, dropping a collection and then verifying that the collection is gone.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Execute ping against the server
  db.command({ping:1}, function(err, result) {
    test.equal(null, err);

    // Create a capped collection with a maximum of 1000 documents
    db.createCollection("a_simple_create_drop_collection", {capped:true, size:10000, max:1000, w:1}, function(err, collection) {
      test.equal(null, err);

      // Insert a document in the capped collection
      collection.insertOne({a:1}, {w:1}, function(err, result) {
        test.equal(null, err);

        // Drop the collection from this world
        db.dropCollection("a_simple_create_drop_collection", function(err, result) {
          test.equal(null, err);

          // Verify that the collection is gone
          db.listCollections({name:"a_simple_create_drop_collection"}).toArray(function(err, names) {
            test.equal(0, names.length);

            db.close();
          });
        });
      });
    });
  });
});

// A simple example creating, dropping a collection and then verifying that the collection is gone using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Execute ping against the server
  db.command({ping:1}).then(function(result) {

    // Create a capped collection with a maximum of 1000 documents
    db.createCollection("a_simple_create_drop_collection_with_promise", {capped:true, size:10000, max:1000, w:1}).then(function(collection) {

      // Insert a document in the capped collection
      collection.insertOne({a:1}, {w:1}).then(function(result) {

        // Drop the collection from this world
        db.dropCollection("a_simple_create_drop_collection_with_promise").then(function(result) {

          // Verify that the collection is gone
          db.listCollections({name:"a_simple_create_drop_collection_with_promise"}).toArray().then(function(names) {
            test.equal(0, names.length);

            db.close();
          });
        });
      });
    });
  });
});

// A simple example creating, dropping a collection and then verifying that the collection is gone using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');
  // Execute ping against the server
  yield db.command({ping:1});

  // Create a capped collection with a maximum of 1000 documents
  var collection = yield db.createCollection("a_simple_create_drop_collection_with_generators", {capped:true, size:10000, max:1000, w:1});

  // Insert a document in the capped collection
  yield collection.insertOne({a:1}, {w:1});

  // Drop the collection from this world
  yield db.dropCollection("a_simple_create_drop_collection_with_generators");

  // Verify that the collection is gone
  var names = yield db.listCollections({name:"a_simple_create_drop_collection_with_generators"}).toArray();
  test.equal(0, names.length);

  db.close();
});

dropDatabase(callback){Promise}

lib/db.js, line 891

Drop a database, removing it permanently from the server.

Name	Type	Description
callback	Db~resultCallback	optional The results callback

Returns:

Promise if no callback passed

Examples

// An examples showing the dropping of a database

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection
  var collection = db.collection('more_index_information_test_1');
  // Insert a bunch of documents for the index
  collection.insertMany([{a:1, b:1}, {a:1, b:1}
    , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {w:1}, function(err, result) {
    test.equal(null, err);

    // Let's drop the database
    db.dropDatabase(function(err, result) {
      test.equal(null, err);

      // Wait two seconds to let it replicate across
      setTimeout(function() {
        // Get the admin database
        db.admin().listDatabases(function(err, dbs) {
          // Grab the databases
          dbs = dbs.databases;
          // Did we find the db
          var found = false;

          // Check if we have the db in the list
          for(var i = 0; i < dbs.length; i++) {
            if(dbs[i].name == 'integration_tests_to_drop') found = true;
          }

          // We should not find the databases
          if(process.env['JENKINS'] == null) test.equal(false, found);

          db.close();
        });
      }, 2000);
    });
  });
});

// An examples showing the dropping of a database using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection
  var collection = db.collection('more_index_information_test_1_with_promise');
  // Insert a bunch of documents for the index
  collection.insertMany([{a:1, b:1}, {a:1, b:1}
    , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {w:1}).then(function(result) {

    // Let's drop the database
    db.dropDatabase().then(function(result) {

      // Wait two seconds to let it replicate across
      setTimeout(function() {
        // Get the admin database
        db.admin().listDatabases().then(function(dbs) {
          // Grab the databases
          dbs = dbs.databases;
          // Did we find the db
          var found = false;

          // Check if we have the db in the list
          for(var i = 0; i < dbs.length; i++) {
            if(dbs[i].name == 'integration_tests_to_drop') found = true;
          }

          // We should not find the databases
          if(process.env['JENKINS'] == null) test.equal(false, found);

          db.close();
        });
      }, 2000);
    });
  });
});

// An examples showing the dropping of a database using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');

  // Create a collection
  var collection = db.collection('more_index_information_test_1_with_generators');
  // Insert a bunch of documents for the index
  yield collection.insertMany([{a:1, b:1}, {a:1, b:1}
    , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {w:1});

  // Let's drop the database
  yield db.dropDatabase();

  // Wait two seconds to let it replicate across
  setTimeout(function() {
    co(function*() {
      // Get the admin database
      var dbs = yield db.admin().listDatabases();
      // Grab the databases
      dbs = dbs.databases;
      // Did we find the db
      var found = false;

      // Check if we have the db in the list
      for(var i = 0; i < dbs.length; i++) {
        if(dbs[i].name == 'integration_tests_to_drop') found = true;
      }

      // We should not find the databases
      if(process.env['JENKINS'] == null) test.equal(false, found);

      db.close();
    });
  }, 2000);
});

ensureIndex(name, fieldOrSpec, options, callback){Promise}

lib/db.js, line 1126

Ensures that an index exists, if it does not it creates it

Name	Type	Default	Description
name	string		The index name
fieldOrSpec	string | object		Defines the index.
options	object	null	optional Optional settings. Name Type Default Description w number | string null optional The write concern. wtimeout number null optional The write concern timeout. j boolean false optional Specify a journal write concern. unique boolean false optional Creates an unique index. sparse boolean false optional Creates a sparse index. background boolean false optional Creates the index in the background, yielding whenever possible. dropDups boolean false optional A unique index cannot be created on a key that has pre-existing duplicate values. If you would like to create the index anyway, keeping the first document the database indexes and deleting all subsequent documents that have duplicate value min number null optional For geospatial indexes set the lower bound for the co-ordinates. max number null optional For geospatial indexes set the high bound for the co-ordinates. v number null optional Specify the format version of the indexes. expireAfterSeconds number null optional Allows you to expire data on indexes applied to a data (MongoDB 2.2 or higher) name number null optional Override the autogenerated index name (useful if the resulting name is larger than 128 bytes)
callback	Db~resultCallback		optional The command result callback

Deprecated

• since version 2.0

Returns:

Promise if no callback passed

Examples

// A more complex ensureIndex using a compound unique index in the background and dropping duplicated documents.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection we want to drop later
  var collection = db.collection('more_complex_ensure_index_db_test');
  // Insert a bunch of documents for the index
  collection.insertMany([{a:1, b:1}
    , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {w:1}, function(err, result) {
    test.equal(null, err);

    // Create an index on the a field
    db.ensureIndex('more_complex_ensure_index_db_test', {a:1, b:1}
      , {unique:true, background:true, w:1}, function(err, indexName) {

      // Show that duplicate records got dropped
      collection.find({}).toArray(function(err, items) {
        test.equal(null, err);
        test.equal(4, items.length);

        // Perform a query, with explain to show we hit the query
        collection.find({a:2}).explain(function(err, explanation) {
          test.equal(null, err);
          test.ok(explanation != null);

          db.close();
        });
      })
    });
  });
});

// A more complex ensureIndex using a compound unique index in the background and dropping duplicated documents using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection we want to drop later
  var collection = db.collection('more_complex_ensure_index_db_test_with_promise');
  // Insert a bunch of documents for the index
  collection.insertMany([{a:1, b:1}
    , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {w:1}).then(function(result) {

    // Create an index on the a field
    db.ensureIndex('more_complex_ensure_index_db_test_with_promise', {a:1, b:1}
      , {unique:true, background:true, w:1}).then(function(indexName) {

      // Show that duplicate records got dropped
      collection.find({}).toArray().then(function(items) {
        test.equal(4, items.length);

        // Perform a query, with explain to show we hit the query
        collection.find({a:2}).explain().then(function(explanation) {
          test.ok(explanation != null);

          db.close();
        });
      })
    });
  });
});

// A more complex ensureIndex using a compound unique index in the background and dropping duplicated documents using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');

  // Create a collection we want to drop later
  var collection = db.collection('more_complex_ensure_index_db_test_with_generators');
  // Insert a bunch of documents for the index
  yield collection.insertMany([{a:1, b:1}
    , {a:2, b:2}, {a:3, b:3}, {a:4, b:4}], {w:1});

  // Create an index on the a field
  yield db.ensureIndex('more_complex_ensure_index_db_test_with_generators', {a:1, b:1}
    , {unique:true, background:true, w:1});

  // Show that duplicate records got dropped
  var items = yield collection.find({}).toArray();
  test.equal(4, items.length);

  // Perform a query, with explain to show we hit the query
  var explanation = yield collection.find({a:2}).explain();
  test.ok(explanation != null);

  db.close();
});

eval(code, parameters, options, callback){Promise}

lib/db.js, line 778

Evaluate JavaScript on the server

Name	Type	Default	Description
code	Code		JavaScript to execute on server.
parameters	object | array		The parameters for the call.
options	object	null	optional Optional settings. Name Type Default Description nolock boolean false optional Tell MongoDB not to block on the evaluation of the javascript.
callback	Db~resultCallback		optional The results callback

Deprecated

• Eval is deprecated on MongoDB 3.2 and forward

Returns:

Promise if no callback passed

Examples

// A whole bunch of examples on how to use eval on the server.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  var numberOfTests = 10;

  var tests_done = function() {
    numberOfTests = numberOfTests - 1;

    if(numberOfTests == 0) {
      db.close();
    }
  }

  // Evaluate a function on the server with the parameter 3 passed in
  db.eval('function (x) {return x;}', [3], function(err, result) {
    test.equal(3, result); tests_done();

    // Evaluate a function on the server with the parameter 3 passed in no lock aquired for eval
    // on server
    db.eval('function (x) {return x;}', [3], {nolock:true}, function(err, result) {
      test.equal(3, result); tests_done();
    });

    // Evaluate a function on the server that writes to a server collection
    db.eval('function (x) {db.test_eval.save({y:x});}', [5], {readPreference: ReadPreference.PRIMARY}, function(err, result) {
      setTimeout(function() {
        // Locate the entry
        db.collection('test_eval', function(err, collection) {
          collection.findOne(function(err, item) {
            test.equal(5, item.y); tests_done();

            // Evaluate a function with 2 parameters passed in
            db.eval('function (x, y) {return x + y;}', [2, 3], function(err, result) {
              test.equal(5, result); tests_done();

              // Evaluate a function with no parameters passed in
              db.eval('function () {return 5;}', function(err, result) {
                test.equal(5, result); tests_done();

                // Evaluate a statement
                db.eval('2 + 3;', function(err, result) {
                  test.equal(5, result); tests_done();

                  // Evaluate a statement using the code object
                  db.eval(new Code("2 + 3;"), function(err, result) {
                    test.equal(5, result); tests_done();

                    // Evaluate a statement using the code object including a scope
                    db.eval(new Code("return i;", {'i':2}), function(err, result) {
                      test.equal(2, result); tests_done();

                      // Evaluate a statement using the code object including a scope
                      db.eval(new Code("i + 3;", {'i':2}), function(err, result) {
                        test.equal(5, result); tests_done();

                        // Evaluate an illegal statement
                        db.eval("5 ++ 5;", function(err, result) {
                          test.ok(err instanceof Error);
                          test.ok(err.message != null);
                          tests_done();
                          // Let's close the db
                          // db.close();
                        });
                      });
                    });
                  });
                });
              });
            });
          });
        });
      }, 1000);
    });
  });
});

// Defining and calling a system level javascript function (NOT recommended, http://www.mongodb.org/display/DOCS/Server-side+Code+Execution)

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Clean out the collection
  db.collection("system.js").deleteMany({}, {w:1}, function(err, result) {
    test.equal(null, err);

    // Define a system level function
    db.collection("system.js").insertOne({_id: "echo", value: new Code("function(x) { return x; }")}, {w:1}, function(err, result) {
      test.equal(null, err);

      db.eval("echo(5)", function(err, result) {
        test.equal(null, err);
        test.equal(5, result);

        db.close();
      });
    });
  });
});

// A whole bunch of examples on how to use eval on the server with a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  var numberOfTests = 10;

  var tests_done = function() {
    numberOfTests = numberOfTests - 1;

    if(numberOfTests == 0) {
      db.close();
    }
  }

  // Evaluate a function on the server with the parameter 3 passed in
  db.eval('function (x) {return x;}', [3]).then(function(result) {
    test.equal(3, result); tests_done();

    // Evaluate a function on the server with the parameter 3 passed in no lock aquired for eval
    // on server
    db.eval('function (x) {return x;}', [3], {nolock:true}).then(function(result) {
      test.equal(3, result); tests_done();
    });

    // Evaluate a function on the server that writes to a server collection
    db.eval('function (x) {db.test_eval_with_promise.save({y:x});}', [5], {readPreference: ReadPreference.PRIMARY}).then(function(result) {
      setTimeout(function() {
        // Locate the entry
        db.collection('test_eval_with_promise', function(err, collection) {
          collection.findOne().then(function(item) {
            test.equal(5, item.y); tests_done();

            // Evaluate a function with 2 parameters passed in
            db.eval('function (x, y) {return x + y;}', [2, 3]).then(function(result) {
              test.equal(5, result); tests_done();

              // Evaluate a function with no parameters passed in
              db.eval('function () {return 5;}').then(function(result) {
                test.equal(5, result); tests_done();

                // Evaluate a statement
                db.eval('2 + 3;').then(function(result) {
                  test.equal(5, result); tests_done();

                  // Evaluate a statement using the code object
                  db.eval(new Code("2 + 3;")).then(function(result) {
                    test.equal(5, result); tests_done();

                    // Evaluate a statement using the code object including a scope
                    db.eval(new Code("return i;", {'i':2})).then(function(result) {
                      test.equal(2, result); tests_done();

                      // Evaluate a statement using the code object including a scope
                      db.eval(new Code("i + 3;", {'i':2})).then(function(result) {
                        test.equal(5, result); tests_done();

                        // Evaluate an illegal statement
                        db.eval("5 ++ 5;").then(function(result) {
                        }).catch(function(err) {
                          test.ok(err instanceof Error);
                          test.ok(err.message != null);
                          tests_done();
                        });
                      });
                    });
                  });
                });
              });
            });
          });
        });
      }, 1000);
    });
  });
});

// Defining and calling a system level javascript function (NOT recommended, http://www.mongodb.org/display/DOCS/Server-side+Code+Execution) using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Clean out the collection
  db.collection("system.js").deleteMany({}, {w:1}).then(function(result) {

    // Define a system level function
    db.collection("system.js").insertOne({_id: "echo", value: new Code("function(x) { return x; }")}, {w:1}).then(function(result) {

      db.eval("echo(5)").then(function(result) {
        test.equal(5, result);

        db.close();
      });
    });
  });
});

// A whole bunch of examples on how to use eval on the server with a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');
  var numberOfTests = 10;

  var tests_done = function() {
    numberOfTests = numberOfTests - 1;

    if(numberOfTests == 0) {
      db.close();
    }
  }

  // Evaluate a function on the server with the parameter 3 passed in
  var result = yield db.eval('function (x) {return x;}', [3]);
  test.equal(3, result); tests_done();

  // Evaluate a function on the server with the parameter 3 passed in no lock aquired for eval
  // on server
  var result = yield db.eval('function (x) {return x;}', [3], {nolock:true})
  test.equal(3, result); tests_done();

  // Evaluate a function on the server that writes to a server collection
  var result = yield db.eval('function (x) {db.test_eval_with_generators.save({y:x});}', [5], {readPreference: ReadPreference.PRIMARY});
  setTimeout(function() {
    co(function*() {
      // Locate the entry
      var collection = db.collection('test_eval_with_generators');
      var item = yield collection.findOne();
      test.equal(5, item.y); tests_done();

      // Evaluate a function with 2 parameters passed in
      var result = yield db.eval('function (x, y) {return x + y;}', [2, 3]);
      test.equal(5, result); tests_done();

      // Evaluate a function with no parameters passed in
      var result = yield db.eval('function () {return 5;}');
      test.equal(5, result); tests_done();

      // Evaluate a statement
      var result = yield db.eval('2 + 3;');
      test.equal(5, result); tests_done();

      // Evaluate a statement using the code object
      var result = yield db.eval(new Code("2 + 3;"));
      test.equal(5, result); tests_done();

      // Evaluate a statement using the code object including a scope
      var result = yield db.eval(new Code("return i;", {'i':2}))
      test.equal(2, result); tests_done();

      // Evaluate a statement using the code object including a scope
      var result = yield db.eval(new Code("i + 3;", {'i':2}));
      test.equal(5, result); tests_done();

      try {
        // Evaluate an illegal statement
        yield db.eval("5 ++ 5;");
      } catch(err) {
        test.ok(err instanceof Error);
        test.ok(err.message != null);
        tests_done();
      }
    });
  }, 1000);
});

// Defining and calling a system level javascript function (NOT recommended, http://www.mongodb.org/display/DOCS/Server-side+Code+Execution) using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');

  // Clean out the collection
  yield db.collection("system.js").deleteMany({}, {w:1});

  // Define a system level function
  yield db.collection("system.js").insertOne({_id: "echo", value: new Code("function(x) { return x; }")}, {w:1});

  var result = yield db.eval("echo(5)");
  test.equal(5, result);

  db.close();
});

executeDbAdminCommand(command, options, callback){Promise}

lib/db.js, line 982

Runs a command on the database as admin.

Name	Type	Default	Description
command	object		The command hash
options	object	null	optional Optional settings. Name Type Default Description readPreference ReadPreference | string null optional The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
callback	Db~resultCallback		optional The command result callback

Returns:

Promise if no callback passed

indexInformation(name, options, callback){Promise}

lib/db.js, line 1541

Retrieves this collections index info.

Name	Type	Default	Description
name	string		The name of the collection.
options	object	null	optional Optional settings. Name Type Default Description full boolean false optional Returns the full raw index information. readPreference ReadPreference | string null optional The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
callback	Db~resultCallback		optional The command result callback

Returns:

Promise if no callback passed

listCollections(filter, options){CommandCursor}

lib/db.js, line 662

Get the list of all collection information for the specified db.

Name	Type	Default	Description
filter	object	{}	optional Query to filter collections by
options	object	null	optional Optional settings. Name Type Default Description batchSize number null optional The batchSize for the returned command cursor or if pre 2.8 the systems batch collection readPreference ReadPreference | string null optional The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).

Examples

// An example of retrieving the collections list for a database.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Get an empty db
  var db1 = db.db('listCollectionTestDb');
  // Create a collection
  var collection = db1.collection('shouldCorrectlyRetrievelistCollections');
  // Ensure the collection was created
  collection.insertOne({a:1}, function(err, r) {
    test.equal(null, err);

    // Return the information of a single collection name
    db1.listCollections({name: "shouldCorrectlyRetrievelistCollections"}).toArray(function(err, items) {
      test.equal(1, items.length);

      // Return the information of a all collections, using the callback format
      db1.listCollections().toArray(function(err, items) {
        test.ok(items.length >= 1);

        db.close();
      });
    });
  });
});

// An example of retrieving the collections list for a database using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Get an empty db
  var db1 = db.db('listCollectionTestDb2');
  // Create a collection
  var collection = db1.collection('shouldCorrectlyRetrievelistCollections_with_promise');
  // Ensure the collection was created
  collection.insertOne({a:1}).then(function(r) {

    // Return the information of a single collection name
    db1.listCollections({name: "shouldCorrectlyRetrievelistCollections_with_promise"}).toArray().then(function(items) {
      test.equal(1, items.length);

      // Return the information of a all collections, using the callback format
      db1.listCollections().toArray().then(function(items) {
        test.ok(items.length >= 1);

        db.close();
      });
    }).catch(function(err) {
      console.dir(err)
    });
  });
});

// An example of retrieving the collections list for a database using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');
  // Get an empty db
  var db1 = db.db('listCollectionTestDb2Generator');
  // Create a collection
  var collection = db1.collection('shouldCorrectlyRetrievelistCollections_with_generators');
  // Ensure the collection was created
  yield collection.insertOne({a:1});

  // Return the information of a single collection name
  var items = yield db1.listCollections({name: "shouldCorrectlyRetrievelistCollections_with_generators"}).toArray();
  test.equal(1, items.length);

  // Return the information of a all collections, using the callback format
  var items = yield db1.listCollections().toArray();
  test.ok(items.length >= 1);

  db.close();
});

logout(options, callback){Promise}

lib/db.js, line 1503

Logout user from server, fire off on all connections and remove all auth info

Name	Type	Default	Description
options	object	null	optional Optional settings. Name Type Default Description dbName string null optional Logout against different database than current.
callback	Db~resultCallback		optional The command result callback

Returns:

Promise if no callback passed

Examples

// An example of using the logout command for the database.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Add a user to the database
  db.addUser('user3', 'name', function(err, result) {
    test.equal(null, err);

    // Authenticate
    db.authenticate('user3', 'name', function(err, result) {
      test.equal(true, result);

      // console.log("--------- 0")
      // Logout the db
      db.logout(function(err, result) {
        // console.log("---------- 1")
        // console.dir(result)
        test.equal(true, result);

        // Remove the user
        db.removeUser('user3', function(err, result) {
          test.equal(true, result);

          db.close();
        });
      });
    });
  });
});

// An example of using the logout command for the database with a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Add a user to the database
  db.addUser('user3', 'name').then(function(result) {
    // console.log("============================================= 2")
    // console.dir(result)

    // Authenticate
    db.authenticate('user3', 'name').then(function(result) {
      // console.log("============================================= 3")
      test.equal(true, result);

      // Logout the db
      db.logout().then(function(result) {
        // console.log("============================================= 4")
        test.equal(true, result);

        // Remove the user
        db.removeUser('user3').then(function(result) {
          // console.log("============================================= 5")
          test.equal(true, result);

          db.close();
        }).catch(function(err) {  console.dir(err )})
      }).catch(function(err) {  console.dir(err )})
    }).catch(function(err) {  console.dir(err )})
  }).catch(function(err) {  console.dir(err )})
});

// An example of using the logout command for the database with a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');
  // Add a user to the database
  var result = yield db.addUser('user3', 'name')

  // Authenticate
  var result = yield db.authenticate('user3', 'name');
  test.equal(true, result);

  // Logout the db
  var result = yield db.logout()
  test.equal(true, result);

  // Remove the user
  var result = yield db.removeUser('user3');
  test.equal(true, result);

  db.close();
});

open(callback){Promise}

lib/db.js, line 249

Open the database

Name	Type	Description
callback	Db~openCallback	optional Callback

Returns:

Promise if no callback passed

Examples

// An example of a simple single server db connection

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  db.on('close', function() {
  })

  db.close();
});

// Simple replicaset connection setup, requires a running replicaset on the correct ports

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);
  p_db.close();
});

// Simple replicaset connection setup, requires a running replicaset on the correct ports using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  p_db.close();
});

removeUser(username, options, callback){Promise}

lib/db.js, line 1457

Remove a user from a database

Name	Type	Default	Description
username	string		The username.
options	object	null	optional Optional settings. Name Type Default Description w number | string null optional The write concern. wtimeout number null optional The write concern timeout. j boolean false optional Specify a journal write concern.
callback	Db~resultCallback		optional The command result callback

Returns:

Promise if no callback passed

Examples

// An example of removing a user.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Add a user to the database
  db.addUser('user', 'name', function(err, result) {
    test.equal(null, err);

    // Authenticate
    db.authenticate('user', 'name', function(err, result) {
      test.equal(true, result);

      // Logout the db
      db.logout(function(err, result) {
        test.equal(true, result);

        // Remove the user from the db
        db.removeUser('user', function(err, result) {

          // Authenticate
          db.authenticate('user', 'name', function(err, result) {
            test.equal(false, result);

            db.close();
          });
        });
      });
    });
  });
});

// An example of removing a user using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Add a user to the database
  db.addUser('user', 'name').then(function(result) {

    // Authenticate
    db.authenticate('user', 'name').then(function(result) {
      test.equal(true, result);

      // Logout the db
      db.logout().then(function(result) {
        test.equal(true, result);

        // Remove the user from the db
        db.removeUser('user').then(function(result) {

          // Authenticate
          db.authenticate('user', 'name').then(function(result) {
            test.equal(false, result);

            db.close();
          }).catch(function(err) {
            db.close();
          });
        });
      });
    });
  });
});

// An example of removing a user using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');

  // Add a user to the database
  yield db.addUser('user', 'name');

  // Authenticate
  var result = yield db.authenticate('user', 'name');
  test.equal(true, result);

  // Logout the db
  var result = yield db.logout();
  test.equal(true, result);

  // Remove the user from the db
  yield db.removeUser('user');

  try {
    // Authenticate
    var result = yield db.authenticate('user', 'name');
    assert.ok(false);
  } catch(err) {}

  db.close();
}).catch(function(err) {
  console.log(err.stack)
});

renameCollection(fromCollection, toCollection, options, callback){Promise}

lib/db.js, line 810

Rename a collection.

Name	Type	Default	Description
fromCollection	string		Name of current collection to rename.
toCollection	string		New name of of the collection.
options	object	null	optional Optional settings. Name Type Default Description dropTarget boolean false optional Drop the target name collection if it previously exists.
callback	Db~collectionResultCallback		optional The results callback

Returns:

Promise if no callback passed

Examples

// A simple example creating, dropping a collection and then verifying that the collection is gone.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  // Create a collection
  db.createCollection("simple_rename_collection", {w:1}, function(err, collection) {
    test.equal(null, err);

    // Insert a document in the collection
    collection.insertOne({a:1}, {w:1}, function(err, result) {
      test.equal(null, err);

      // Retrieve the number of documents from the collection
      collection.count(function(err, count) {
        test.equal(1, count);

        // Rename the collection
        db.renameCollection("simple_rename_collection", "simple_rename_collection_2", function(err, collection2) {
          test.equal(null, err);

          // Retrieve the number of documents from the collection
          collection2.count(function(err, count) {
            test.equal(1, count);

            // Verify that the collection is gone
            db.listCollections({name:"simple_rename_collection"}).toArray(function(err, names) {
              test.equal(0, names.length);

              // Verify that the new collection exists
              db.listCollections({name:"simple_rename_collection_2"}).toArray(function(err, names) {
                test.equal(1, names.length);

                db.close();
              });
            });
          });
        });
      });
    });
  });
});

// A simple example creating, dropping a collection and then verifying that the collection is gone.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Create a collection
  db.createCollection("simple_rename_collection_with_promise", {w:1}).then(function(collection) {

    // Insert a document in the collection
    collection.insertOne({a:1}, {w:1}).then(function(result) {

      // Retrieve the number of documents from the collection
      collection.count().then(function(count) {
        test.equal(1, count);

        // Rename the collection
        db.renameCollection("simple_rename_collection_with_promise", "simple_rename_collection_2_with_promise").then(function(collection2) {

          // Retrieve the number of documents from the collection
          collection2.count().then(function(count) {
            test.equal(1, count);

            // Verify that the collection is gone
            db.listCollections({name:"simple_rename_collection_with_promise"}).toArray().then(function(names) {
              test.equal(0, names.length);

              // Verify that the new collection exists
              db.listCollections({name:"simple_rename_collection_2_with_promise"}).toArray().then(function(names) {
                test.equal(1, names.length);

                db.close();
              });
            });
          });
        });
      });
    });
  });
});

// A simple example creating, dropping a collection and then verifying that the collection is gone.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');
  // Create a collection
  var collection = yield db.createCollection("simple_rename_collection_with_generators", {w:1});

  // Insert a document in the collection
  yield collection.insertOne({a:1}, {w:1});

  // Retrieve the number of documents from the collection
  var count = yield collection.count();
  test.equal(1, count);

  // Rename the collection
  var collection2 = yield db.renameCollection("simple_rename_collection_with_generators", "simple_rename_collection_2_with_generators");

  // Retrieve the number of documents from the collection
  var count = yield collection2.count();
  test.equal(1, count);

  // Verify that the collection is gone
  var names = yield db.listCollections({name:"simple_rename_collection_with_generators"}).toArray();
  test.equal(0, names.length);

  // Verify that the new collection exists
  var names = yield db.listCollections({name:"simple_rename_collection_2_with_generators"}).toArray();
  test.equal(1, names.length);

  db.close();
});

stats(options, callback){Promise}

lib/db.js, line 616

Get all the db statistics.

Name	Type	Default	Description
options	object	null	optional Optional settings. Name Type Default Description scale number null optional Divide the returned sizes by scale value.
callback	Db~resultCallback		optional The collection result callback

Returns:

Promise if no callback passed

Examples

// An example showing how to retrieve the db statistics

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  test.equal(null, err);

  db.stats(function(err, stats) {
    test.equal(null, err);
    test.ok(stats != null);

    db.close();
  })
});

// An example showing how to retrieve the db statistics using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  db.stats().then(function(stats) {
    test.ok(stats != null);

    db.close();
  })
});

// An example showing how to retrieve the db statistics using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');
  var stats = yield db.stats()
  test.ok(stats != null);

  db.close();
});

unref()

lib/db.js, line 1726

Unref all sockets

Type Definitions

collectionResultCallback(error, collection)

lib/db.js, line 410

The callback format for the collection method, must be used if strict is specified

Name	Type	Description
error	MongoError	An error instance representing the error during the execution.
collection	Collection	The collection instance.

collectionsResultCallback(error, collections)

lib/db.js, line 928

The callback format for the collections method.

Name	Type	Description
error	MongoError	An error instance representing the error during the execution.
collections	Array.<Collection>	An array of all the collections objects for the db instance.

noResultCallback(error, result)

lib/db.js, line 349

The callback format for results

Name	Type	Description
error	MongoError	An error instance representing the error during the execution.
result	null	Is not set to a value

openCallback(error, db)

lib/db.js, line 220

The callback format for the Db.open method

Name	Type	Description
error	MongoError	An error instance representing the error during the execution.
db	Db	The Db instance if the open method was successful.

resultCallback(error, result)

lib/db.js, line 283

The callback format for results

Name	Type	Description
error	MongoError	An error instance representing the error during the execution.
result	object	The result object if the command was executed successfully.

Events

authenticated

lib/db.js, line 1739

Db authenticated event

Emitted after all server members in the topology (single server, replicaset or mongos) have successfully authenticated.

Type:

• object

close

lib/db.js, line 1730

Db close event

Emitted after a socket closed against a single server or mongos proxy.

Type:

• MongoError

error

lib/db.js, line 1759

Db error event

Emitted after an error occurred against a single server or mongos proxy.

Type:

• MongoError

fullsetup

lib/db.js, line 1786

Db fullsetup event, emitted when all servers in the topology have been connected to at start up time.

• Server: Emitted when the driver has connected to the single server and has authenticated.
• ReplSet: Emitted after the driver has attempted to connect to all replicaset members.
• Mongos: Emitted after the driver has attempted to connect to all mongos proxies.

Type:

• Db

parseError

lib/db.js, line 1777

Db parseError event

The parseError event is emitted if the driver detects illegal or corrupt BSON being received from the server.

Type:

• MongoError

reconnect

lib/db.js, line 1748

Db reconnect event

• Server: Emitted when the driver has reconnected and re-authenticated.
• ReplicaSet: N/A
• Mongos: Emitted when the driver reconnects and re-authenticates successfully against a Mongos.

Type:

• object

timeout

lib/db.js, line 1768

Db timeout event

Emitted after a socket timeout occurred against a single server or mongos proxy.

Type:

• MongoError