Admin()

Constructor

Allows the user to access the admin functionality of MongoDB

class Admin()

Arguments:

• db (object) – Current db instance we wish to perform Admin operations on.

Returns:

function Constructor for Admin type.

buildInfo

Retrieve the server information for the current instance of the db client

buildInfo(callback)

Arguments:

• callback (function) – this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from buildInfo or null if an error occured.

Returns:

null Returns no result

Examples

Retrieve the buildInfo for the current MongoDB instance

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
// Establish connection to db
db.open(function(err, db) {

  // Use the admin database for the operation
  var adminDb = db.admin();

  // Add the new user to the admin database
  adminDb.addUser('admin3', 'admin3', function(err, result) {

    // Authenticate using the newly added user
    adminDb.authenticate('admin3', 'admin3', function(err, result) {
      assert.ok(result);

      // Retrive the build information for the MongoDB instance
      adminDb.buildInfo(function(err, info) {
        assert.ok(err == null);

        adminDb.removeUser('admin3', function(err, result) {
          assert.ok(result);

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

serverStatus

Retrieve this db’s server status.

serverStatus(callback)

Arguments:

• callback (function) – this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from serverStatus or null if an error occured.

Returns:

null

Examples

Retrieve the current server Info

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
// Establish connection to db
db.open(function(err, db) {

  // Grab a collection object
  var collection = db.collection('test');

  // Force the creation of the collection by inserting a document
  // Collections are not created until the first document is inserted
  collection.insert({'a':1}, {w: 1}, function(err, doc) {

    // Use the admin database for the operation
    var adminDb = db.admin();

    // Add the new user to the admin database
    adminDb.addUser('admin13', 'admin13', function(err, result) {

      // Authenticate using the newly added user
      adminDb.authenticate('admin13', 'admin13', function(err, result) {

        // Retrive the server Info
        adminDb.serverStatus(function(err, info) {
          assert.equal(null, err);
          assert.ok(info != null);

          adminDb.removeUser('admin13', function(err, result) {
            assert.ok(result);

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

profilingLevel

Retrieve the current profiling Level for MongoDB

profilingLevel(callback)

Arguments:

• callback (function) – this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from profilingLevel or null if an error occured.

Returns:

null Returns no result

Examples

Retrieve the current profiling level set for the MongoDB instance

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
// Establish connection to db
db.open(function(err, db) {

  // Grab a collection object
  var collection = db.collection('test');

  // Force the creation of the collection by inserting a document
  // Collections are not created until the first document is inserted
  collection.insert({'a':1}, {w: 1}, function(err, doc) {

    // Use the admin database for the operation
    var adminDb = db.admin();

    // Add the new user to the admin database
    adminDb.addUser('admin5', 'admin5', function(err, result) {

      // Authenticate using the newly added user
      adminDb.authenticate('admin5', 'admin5', function(err, replies) {

        // Retrive the profiling level
        adminDb.profilingLevel(function(err, level) {

          adminDb.removeUser('admin5', function(err, result) {
            assert.ok(result);

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

ping

Ping the MongoDB server and retrieve results

ping(callback)

Arguments:

• callback (function) – this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from ping or null if an error occured.

Returns:

null Returns no result

Examples

An example of how to add a user to the admin database

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
// Establish connection to db
db.open(function(err, db) {

  // Use the admin database for the operation
  var adminDb = db.admin();

  // Add the new user to the admin database
  adminDb.addUser('admin9', 'admin9', function(err, result) {

    // Authenticate using the newly added user
    adminDb.authenticate('admin9', 'admin9', function(err, result) {
      assert.ok(result);

      // Ping the server
      adminDb.ping(function(err, pingResult) {
        assert.equal(null, err);

        adminDb.removeUser('admin9', function(err, result) {
          assert.ok(result);

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

authenticate

Authenticate against MongoDB

authenticate(username, password, callback)

Arguments:

• username (string) – The user name for the authentication.
• password (string) – The password for the authentication.
• callback (function) – this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from authenticate or null if an error occured.

Returns:

null Returns no result

Examples

Authenticate against MongoDB Admin user

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
db.open(function(err, db) {
  // Grab a collection object
  var collection = db.collection('test');

  // Force the creation of the collection by inserting a document
  // Collections are not created until the first document is inserted
  collection.insert({'a':1}, {w:1}, function(err, doc) {

    // Use the admin database for the operation
    var adminDb = db.admin();

    // Add the new user to the admin database
    adminDb.addUser('admin2', 'admin2', function(err, result) {

      // Authenticate using the newly added user
      adminDb.authenticate('admin2', 'admin2', function(err, result) {
        assert.ok(result);

        adminDb.removeUser('admin2', function(err, result) {
          assert.ok(result);

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

logout

Logout current authenticated user

logout([options], callback)

Arguments:

• [options] (object) – Optional parameters to the command.
• callback (function) – this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from logout or null if an error occured.

Returns:

null Returns no result

Examples

An example of how add a user, authenticate and logout

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
// Establish connection to db
db.open(function(err, db) {

  // Use the admin database for the operation
  var adminDb = db.admin();

  // Add the new user to the admin database
  adminDb.addUser('admin10', 'admin10', function(err, result) {

    // Authenticate using the newly added user
    adminDb.authenticate('admin10', 'admin10', function(err, result) {
      assert.ok(result);

      // Logout the user
      adminDb.logout(function(err, result) {
        assert.equal(true, result);

        adminDb.removeUser('admin10', function(err, result) {
          assert.ok(result);

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

addUser

Add a user to the MongoDB server, if the user exists it will overwrite the current password

Options

• w, {Number/String, > -1 || ‘majority’ || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = ‘majority’ or tag acknowledges the write
• wtimeout, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
• fsync, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
• j, (Boolean, default:false) write waits for journal sync before returning

addUser(username, password[, options], callback)

Arguments:

• username (string) – The user name for the authentication.
• password (string) – The password for the authentication.
• [options] (object) – additional options during update.
• callback (function) – this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from addUser or null if an error occured.

Returns:

null Returns no result

Examples

An example of how to add a user to the admin database

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
// Establish connection to db
db.open(function(err, db) {

  // Use the admin database for the operation
  var adminDb = db.admin();

  // Add the new user to the admin database
  adminDb.addUser('admin11', 'admin11', function(err, result) {

    // Authenticate using the newly added user
    adminDb.authenticate('admin11', 'admin11', function(err, result) {
      assert.ok(result);

      adminDb.removeUser('admin11', function(err, result) {
        assert.ok(result);

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

removeUser

Remove a user from the MongoDB server

Options

• w, {Number/String, > -1 || ‘majority’ || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = ‘majority’ or tag acknowledges the write
• wtimeout, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
• fsync, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
• j, (Boolean, default:false) write waits for journal sync before returning

removeUser(username[, options], callback)

Arguments:

• username (string) – The user name for the authentication.
• [options] (object) – additional options during update.
• callback (function) – this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from removeUser or null if an error occured.

Returns:

null Returns no result

Examples

An example of how to remove a user from the admin database

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
// Establish connection to db
db.open(function(err, db) {

  // Use the admin database for the operation
  var adminDb = db.admin();

  // Add the new user to the admin database
  adminDb.addUser('admin12', 'admin12', function(err, result) {

    // Authenticate using the newly added user
    adminDb.authenticate('admin12', 'admin12', function(err, result) {
      assert.ok(result);

      // Remove the user
      adminDb.removeUser('admin12', function(err, result) {
        assert.equal(null, err);
        assert.equal(true, result);

        // Authenticate using the removed user should fail
        adminDb.authenticate('admin12', 'admin12', function(err, result) {
          assert.ok(err != null);
          assert.ok(!result);

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

setProfilingLevel

Set the current profiling level of MongoDB

setProfilingLevel(level, callback)

Arguments:

• level (string) – The new profiling level (off, slow_only, all)
• callback (function) – this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from setProfilingLevel or null if an error occured.

Returns:

null Returns no result

Examples

An example of how to use the setProfilingInfo Use this command to set the Profiling level on the MongoDB server

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
// Establish connection to db
db.open(function(err, db) {

  // Grab a collection object
  var collection = db.collection('test');

  // Force the creation of the collection by inserting a document
  // Collections are not created until the first document is inserted
  collection.insert({'a':1}, {w: 1}, function(err, doc) {

    // Use the admin database for the operation
    var adminDb = db.admin();

    // Add the new user to the admin database
    adminDb.addUser('admin6', 'admin6', function(err, result) {

      // Authenticate using the newly added user
      adminDb.authenticate('admin6', 'admin6', function(err, replies) {

        // Set the profiling level to only profile slow queries
        adminDb.setProfilingLevel('slow_only', function(err, level) {

          // Retrive the profiling level and verify that it's set to slow_only
          adminDb.profilingLevel(function(err, level) {
            assert.equal('slow_only', level);

            // Turn profiling off
            adminDb.setProfilingLevel('off', function(err, level) {

              // Retrive the profiling level and verify that it's set to off
              adminDb.profilingLevel(function(err, level) {
                assert.equal('off', level);

                // Set the profiling level to log all queries
                adminDb.setProfilingLevel('all', function(err, level) {

                  // Retrive the profiling level and verify that it's set to all
                  adminDb.profilingLevel(function(err, level) {
                    assert.equal('all', level);

                    // Attempt to set an illegal profiling level
                    adminDb.setProfilingLevel('medium', function(err, level) {
                      assert.ok(err instanceof Error);
                      assert.equal("Error: illegal profiling level value medium", err.message);

                      adminDb.removeUser('admin6', function(err, result) {
                        assert.ok(result);

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

profilingInfo

Retrive the current profiling information for MongoDB

profilingInfo(callback)

Arguments:

• callback (function) – this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from profilingInfo or null if an error occured.

Returns:

null Returns no result

Examples

An example of how to use the profilingInfo Use this command to pull back the profiling information currently set for Mongodb

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
// Establish connection to db
db.open(function(err, db) {

  // Grab a collection object
  var collection = db.collection('test');

  // Force the creation of the collection by inserting a document
  // Collections are not created until the first document is inserted
  collection.insert({'a':1}, {w: 1}, function(doc) {

    // Use the admin database for the operation
    var adminDb = db.admin();

    // Add the new user to the admin database
    adminDb.addUser('admin7', 'admin7', function(err, result) {

      // Authenticate using the newly added user
      adminDb.authenticate('admin7', 'admin7', function(err, replies) {

        // Set the profiling level to all
        adminDb.setProfilingLevel('all', function(err, level) {

          // Execute a query command
          collection.find().toArray(function(err, items) {

            // Turn off profiling
            adminDb.setProfilingLevel('off', function(err, level) {

              // Retrive the profiling information
              adminDb.profilingInfo(function(err, infos) {
                assert.ok(infos.constructor == Array);
                assert.ok(infos.length >= 1);
                assert.ok(infos[0].ts.constructor == Date);
                assert.ok(infos[0].millis.constructor == Number);

                adminDb.removeUser('admin7', function(err, result) {
                  assert.ok(result);

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

command

Execute a db command against the Admin database

command(command[, options], callback)

Arguments:

• command (object) – A command object {ping:1}.
• [options] (object) – Optional parameters to the command.
• callback (function) – this will be called after executing this method. The command always return the whole result of the command as the second parameter.

Returns:

null Returns no result

Examples

Retrieve the buildInfo using the command function

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
// Establish connection to db
db.open(function(err, db) {

  // Use the admin database for the operation
  var adminDb = db.admin();

  // Add the new user to the admin database
  adminDb.addUser('admin4', 'admin4', function(err, result) {

    // Authenticate using the newly added user
    adminDb.authenticate('admin4', 'admin4', function(err, result) {
      assert.ok(result);

      // Retrive the build information using the admin command
      adminDb.command({buildInfo:1}, function(err, info) {
        assert.ok(err == null);

        adminDb.removeUser('admin4', function(err, result) {
          assert.ok(result);

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

validateCollection

Validate an existing collection

validateCollection(collectionName[, options], callback)

Arguments:

• collectionName (string) – The name of the collection to validate.
• [options] (object) – Optional parameters to the command.
• callback (function) – this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from validateCollection or null if an error occured.

Returns:

null Returns no result

Examples

An example of how to use the validateCollection command Use this command to check that a collection is valid (not corrupt) and to get various statistics.

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
// Establish connection to db
db.open(function(err, db) {

  // Grab a collection object
  var collection = db.collection('test');

  // Force the creation of the collection by inserting a document
  // Collections are not created until the first document is inserted
  collection.insert({'a':1}, {w: 1}, function(err, doc) {

    // Use the admin database for the operation
    var adminDb = db.admin();

    // Add the new user to the admin database
    adminDb.addUser('admin8', 'admin8', function(err, result) {

      // Authenticate using the newly added user
      adminDb.authenticate('admin8', 'admin8', function(err, replies) {

        // Validate the 'test' collection
        adminDb.validateCollection('test', function(err, doc) {

          // Pre 1.9.1 servers
          if(doc.result != null) {
            assert.ok(doc.result != null);
            assert.ok(doc.result.match(/firstExtent/) != null);
          } else {
            assert.ok(doc.firstExtent != null);
          }

          adminDb.removeUser('admin8', function(err, result) {
            assert.ok(result);

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

listDatabases

List the available databases

listDatabases(callback)

Arguments:

• callback (function) – this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from listDatabases or null if an error occured.

Returns:

null Returns no result

Examples

An example of listing all available databases.

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
// Establish connection to db
db.open(function(err, db) {

  // Use the admin database for the operation
  var adminDb = db.admin();

  // List all the available databases
  adminDb.listDatabases(function(err, dbs) {
    assert.equal(null, err);
    assert.ok(dbs.databases.length > 0);

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

replSetGetStatus

Get ReplicaSet status

replSetGetStatus(callback)

Arguments:

• callback (function) – this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from replSetGetStatus or null if an error occured.

Returns:

null

Examples

Retrieve the current replicaset status if the server is running as part of a replicaset

var Db = require('mongodb').Db,
    MongoClient = require('mongodb').MongoClient,
    Server = require('mongodb').Server,
    ReplSetServers = require('mongodb').ReplSetServers,
    ObjectID = require('mongodb').ObjectID,
    Binary = require('mongodb').Binary,
    GridStore = require('mongodb').GridStore,
    Grid = require('mongodb').Grid,
    Code = require('mongodb').Code,
    BSON = require('mongodb').pure().BSON,
    assert = require('assert');

var db = new Db('test', new Server('localhost', 27017));
// Establish connection to db
db.open(function(err, db) {

  // Grab a collection object
  var collection = db.collection('test');

  // Force the creation of the collection by inserting a document
  // Collections are not created until the first document is inserted
  collection.insert({'a':1}, {w: 1}, function(err, doc) {

    // Use the admin database for the operation
    var adminDb = db.admin();

    // Add the new user to the admin database
    adminDb.addUser('admin14', 'admin14', function(err, result) {
      assert.equal(null, err);
      assert.ok(result != null);

      // Authenticate using the newly added user
      adminDb.authenticate('admin14', 'admin14', function(err, result) {
        assert.equal(null, err);
        assert.equal(true, result);

        // Retrive the server Info, returns error if we are not
        // running a replicaset
        adminDb.replSetGetStatus(function(err, info) {

          adminDb.removeUser('admin14', function(err, result) {
            assert.equal(null, err);
            assert.ok(result);

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