Node.js MongoDB Driver API

Source: lib/admin.js

  1. "use strict";
  3. var toError = require('./utils').toError,
  4.   Define = require('./metadata'),
  5.   shallowClone = require('./utils').shallowClone,
  6.   assign = require('./utils').assign,
  7.   authenticate = require('./authenticate');
  9. /**
  10.  * @fileOverview The **Admin** class is an internal class that allows convenient access to
  11.  * the admin functionality and commands for MongoDB.
  12.  *
  13.  * **ADMIN Cannot directly be instantiated**
  14.  * @example
  15.  * var MongoClient = require('mongodb').MongoClient,
  16.  *   test = require('assert');
  17.  * // Connection url
  18.  * var url = 'mongodb://localhost:27017/test';
  19.  * // Connect using MongoClient
  20.  * MongoClient.connect(url, function(err, db) {
  21.  *   // Use the admin database for the operation
  22.  *   var adminDb = db.admin();
  23.  *
  24.  *   // List all the available databases
  25.  *   adminDb.listDatabases(function(err, dbs) {
  26.  *     test.equal(null, err);
  27.  *     test.ok(dbs.databases.length > 0);
  28.  *     db.close();
  29.  *   });
  30.  * });
  31.  */
  33. /**
  34.  * Create a new Admin instance (INTERNAL TYPE, do not instantiate directly)
  35.  * @class
  36.  * @return {Admin} a collection instance.
  37.  */
  38. var Admin = function(db, topology, promiseLibrary) {
  39.   if(!(this instanceof Admin)) return new Admin(db, topology);
  41.   // Internal state
  42.   this.s = {
  43.       db: db
  44.     , topology: topology
  45.     , promiseLibrary: promiseLibrary
  46.   }
  47. }
  49. var define = Admin.define = new Define('Admin', Admin, false);
  51. /**
  52.  * The callback format for results
  53.  * @callback Admin~resultCallback
  54.  * @param {MongoError} error An error instance representing the error during the execution.
  55.  * @param {object} result The result object if the command was executed successfully.
  56.  */
  58. /**
  59.  * Execute a command
  60.  * @method
  61.  * @param {object} command The command hash
  62.  * @param {object} [options=null] Optional settings.
  63.  * @param {(ReadPreference|string)} [options.readPreference=null] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
  64.  * @param {number} [options.maxTimeMS=null] Number of milliseconds to wait before aborting the query.
  65.  * @param {Admin~resultCallback} [callback] The command result callback
  66.  * @return {Promise} returns Promise if no callback passed
  67.  */
  68. Admin.prototype.command = function(command, options, callback) {
  69.   var self = this;
  70.   var args = Array.prototype.slice.call(arguments, 1);
  71.   callback = args.pop();
  72.   if(typeof callback != 'function') args.push(callback);
  73.   options = args.length ? args.shift() : {};
  75.   // Execute using callback
  76.   if(typeof callback == 'function') return this.s.db.executeDbAdminCommand(command, options, function(err, doc) {
  77.     return callback != null ? callback(err, doc) : null;
  78.   });
  80.   // Return a Promise
  81.   return new this.s.promiseLibrary(function(resolve, reject) {
  82.     self.s.db.executeDbAdminCommand(command, options, function(err, doc) {
  83.       if(err) return reject(err);
  84.       resolve(doc);
  85.     });
  86.   });
  87. }
  89. define.classMethod('command', {callback: true, promise:true});
  91. /**
  92.  * Retrieve the server information for the current
  93.  * instance of the db client
  94.  *
  95.  * @param {Admin~resultCallback} [callback] The command result callback
  96.  * @return {Promise} returns Promise if no callback passed
  97.  */
  98. Admin.prototype.buildInfo = function(callback) {
  99.   var self = this;
  100.   // Execute using callback
  101.   if(typeof callback == 'function') return this.serverInfo(callback);
  103.   // Return a Promise
  104.   return new this.s.promiseLibrary(function(resolve, reject) {
  105.     self.serverInfo(function(err, r) {
  106.       if(err) return reject(err);
  107.       resolve(r);
  108.     });
  109.   });
  110. }
  112. define.classMethod('buildInfo', {callback: true, promise:true});
  114. /**
  115.  * Retrieve the server information for the current
  116.  * instance of the db client
  117.  *
  118.  * @param {Admin~resultCallback} [callback] The command result callback
  119.  * @return {Promise} returns Promise if no callback passed
  120.  */
  121. Admin.prototype.serverInfo = function(callback) {
  122.   var self = this;
  123.   // Execute using callback
  124.   if(typeof callback == 'function') return this.s.db.executeDbAdminCommand({buildinfo:1}, function(err, doc) {
  125.     if(err != null) return callback(err, null);
  126.     callback(null, doc);
  127.   });
  129.   // Return a Promise
  130.   return new this.s.promiseLibrary(function(resolve, reject) {
  131.     self.s.db.executeDbAdminCommand({buildinfo:1}, function(err, doc) {
  132.       if(err) return reject(err);
  133.       resolve(doc);
  134.     });
  135.   });
  136. }
  138. define.classMethod('serverInfo', {callback: true, promise:true});
  140. /**
  141.  * Retrieve this db's server status.
  142.  *
  143.  * @param {Admin~resultCallback} [callback] The command result callback
  144.  * @return {Promise} returns Promise if no callback passed
  145.  */
  146. Admin.prototype.serverStatus = function(callback) {
  147.   var self = this;
  149.   // Execute using callback
  150.   if(typeof callback == 'function') return serverStatus(self, callback)
  152.   // Return a Promise
  153.   return new this.s.promiseLibrary(function(resolve, reject) {
  154.     serverStatus(self, function(err, r) {
  155.       if(err) return reject(err);
  156.       resolve(r);
  157.     });
  158.   });
  159. };
  161. var serverStatus = function(self, callback) {
  162.   self.s.db.executeDbAdminCommand({serverStatus: 1}, function(err, doc) {
  163.     if(err == null && doc.ok === 1) {
  164.       callback(null, doc);
  165.     } else {
  166.       if(err) return callback(err, false);
  167.       return callback(toError(doc), false);
  168.     }
  169.   });
  170. }
  172. define.classMethod('serverStatus', {callback: true, promise:true});
  174. /**
  175.  * Retrieve the current profiling Level for MongoDB
  176.  *
  177.  * @param {Admin~resultCallback} [callback] The command result callback
  178.  * @return {Promise} returns Promise if no callback passed
  179.  */
  180. Admin.prototype.profilingLevel = function(callback) {
  181.   var self = this;
  183.   // Execute using callback
  184.   if(typeof callback == 'function') return profilingLevel(self, callback)
  186.   // Return a Promise
  187.   return new this.s.promiseLibrary(function(resolve, reject) {
  188.     profilingLevel(self, function(err, r) {
  189.       if(err) return reject(err);
  190.       resolve(r);
  191.     });
  192.   });
  193. };
  195. var profilingLevel = function(self, callback) {
  196.   self.s.db.executeDbAdminCommand({profile:-1}, function(err, doc) {
  197.     if(err == null && doc.ok === 1) {
  198.       var was = doc.was;
  199.       if(was == 0) return callback(null, "off");
  200.       if(was == 1) return callback(null, "slow_only");
  201.       if(was == 2) return callback(null, "all");
  202.         return callback(new Error("Error: illegal profiling level value " + was), null);
  203.     } else {
  204.       err != null ? callback(err, null) : callback(new Error("Error with profile command"), null);
  205.     }
  206.   });
  207. }
  209. define.classMethod('profilingLevel', {callback: true, promise:true});
  211. /**
  212.  * Ping the MongoDB server and retrieve results
  213.  *
  214.  * @param {Admin~resultCallback} [callback] The command result callback
  215.  * @return {Promise} returns Promise if no callback passed
  216.  */
  217. Admin.prototype.ping = function(options, callback) {
  218.   var self = this;
  219.   var args = Array.prototype.slice.call(arguments, 0);
  220.   callback = args.pop();
  221.   if(typeof callback != 'function') args.push(callback);
  223.   // Execute using callback
  224.   if(typeof callback == 'function') return this.s.db.executeDbAdminCommand({ping: 1}, callback);
  226.   // Return a Promise
  227.   return new this.s.promiseLibrary(function(resolve, reject) {
  228.     self.s.db.executeDbAdminCommand({ping: 1}, function(err, r) {
  229.       if(err) return reject(err);
  230.       resolve(r);
  231.     });
  232.   });
  233. }
  235. define.classMethod('ping', {callback: true, promise:true});
  237. /**
  238.  * Authenticate a user against the server.
  239.  * @method
  240.  * @param {string} username The username.
  241.  * @param {string} [password] The password.
  242.  * @param {Admin~resultCallback} [callback] The command result callback
  243.  * @return {Promise} returns Promise if no callback passed
  244.  * @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.
  245.  */
  246. Admin.prototype.authenticate = function(username, password, options, callback) {
  247.   console.warn("Admin.prototype.authenticate 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.");
  248.   var finalArguments = [this.s.db];
  249.   if(typeof username == 'string') finalArguments.push(username);
  250.   if(typeof password == 'string') finalArguments.push(password);
  251.   if(typeof options == 'function') {
  252.     finalArguments.push({ authdb: 'admin' });
  253.     finalArguments.push(options);
  254.   } else {
  255.     finalArguments.push(assign({}, options, { authdb: 'admin' }));
  256.   }
  258.   if(typeof callback == 'function') finalArguments.push(callback);
  259.   // Execute authenticate method
  260.   return authenticate.apply(this.s.db, finalArguments);
  261. }
  263. define.classMethod('authenticate', {callback: true, promise:true});
  265. /**
  266.  * Logout user from server, fire off on all connections and remove all auth info
  267.  * @method
  268.  * @param {Admin~resultCallback} [callback] The command result callback
  269.  * @return {Promise} returns Promise if no callback passed
  270.  */
  271. Admin.prototype.logout = function(callback) {
  272.   var self = this;
  273.   // Execute using callback
  274.   if(typeof callback == 'function') return this.s.db.logout({dbName: 'admin'}, callback);
  276.   // Return a Promise
  277.   return new this.s.promiseLibrary(function(resolve, reject) {
  278.     self.s.db.logout({dbName: 'admin'}, function(err) {
  279.       if(err) return reject(err);
  280.       resolve(true);
  281.     });
  282.   });
  283. }
  285. define.classMethod('logout', {callback: true, promise:true});
  287. // Get write concern
  288. var writeConcern = function(options, db) {
  289.   options = shallowClone(options);
  291.   // If options already contain write concerns return it
  292.   if(options.w || options.wtimeout || options.j || options.fsync) {
  293.     return options;
  294.   }
  296.   // Set db write concern if available
  297.   if(db.writeConcern) {
  298.     if(options.w) options.w = db.writeConcern.w;
  299.     if(options.wtimeout) options.wtimeout = db.writeConcern.wtimeout;
  300.     if(options.j) options.j = db.writeConcern.j;
  301.     if(options.fsync) options.fsync = db.writeConcern.fsync;
  302.   }
  304.   // Return modified options
  305.   return options;
  306. }
  308. /**
  309.  * Add a user to the database.
  310.  * @method
  311.  * @param {string} username The username.
  312.  * @param {string} password The password.
  313.  * @param {object} [options=null] Optional settings.
  314.  * @param {(number|string)} [options.w=null] The write concern.
  315.  * @param {number} [options.wtimeout=null] The write concern timeout.
  316.  * @param {boolean} [options.j=false] Specify a journal write concern.
  317.  * @param {boolean} [options.fsync=false] Specify a file sync write concern.
  318.  * @param {object} [options.customData=null] Custom data associated with the user (only Mongodb 2.6 or higher)
  319.  * @param {object[]} [options.roles=null] Roles associated with the created user (only Mongodb 2.6 or higher)
  320.  * @param {Admin~resultCallback} [callback] The command result callback
  321.  * @return {Promise} returns Promise if no callback passed
  322.  */
  323. Admin.prototype.addUser = function(username, password, options, callback) {
  324.   var self = this;
  325.   var args = Array.prototype.slice.call(arguments, 2);
  326.   callback = args.pop();
  327.   if(typeof callback != 'function') args.push(callback);
  328.   options = args.length ? args.shift() : {};
  329.   options = options || {};
  330.   // Get the options
  331.   options = writeConcern(options, self.s.db)
  332.   // Set the db name to admin
  333.   options.dbName = 'admin';
  335.   // Execute using callback
  336.   if(typeof callback == 'function')
  337.     return self.s.db.addUser(username, password, options, callback);
  339.   // Return a Promise
  340.   return new this.s.promiseLibrary(function(resolve, reject) {
  341.     self.s.db.addUser(username, password, options, function(err, r) {
  342.       if(err) return reject(err);
  343.       resolve(r);
  344.     });
  345.   });
  346. }
  348. define.classMethod('addUser', {callback: true, promise:true});
  350. /**
  351.  * Remove a user from a database
  352.  * @method
  353.  * @param {string} username The username.
  354.  * @param {object} [options=null] Optional settings.
  355.  * @param {(number|string)} [options.w=null] The write concern.
  356.  * @param {number} [options.wtimeout=null] The write concern timeout.
  357.  * @param {boolean} [options.j=false] Specify a journal write concern.
  358.  * @param {boolean} [options.fsync=false] Specify a file sync write concern.
  359.  * @param {Admin~resultCallback} [callback] The command result callback
  360.  * @return {Promise} returns Promise if no callback passed
  361.  */
  362. Admin.prototype.removeUser = function(username, options, callback) {
  363.   var self = this;
  364.   var args = Array.prototype.slice.call(arguments, 1);
  365.   callback = args.pop();
  366.   if(typeof callback != 'function') args.push(callback);
  367.   options = args.length ? args.shift() : {};
  368.   options = options || {};
  369.   // Get the options
  370.   options = writeConcern(options, self.s.db)
  371.   // Set the db name
  372.   options.dbName = 'admin';
  374.   // Execute using callback
  375.   if(typeof callback == 'function')
  376.     return self.s.db.removeUser(username, options, callback);
  378.   // Return a Promise
  379.   return new this.s.promiseLibrary(function(resolve, reject) {
  380.     self.s.db.removeUser(username, options, function(err, r) {
  381.       if(err) return reject(err);
  382.       resolve(r);
  383.     });
  384.   });
  385. }
  387. define.classMethod('removeUser', {callback: true, promise:true});
  389. /**
  390.  * Set the current profiling level of MongoDB
  391.  *
  392.  * @param {string} level The new profiling level (off, slow_only, all).
  393.  * @param {Admin~resultCallback} [callback] The command result callback.
  394.  * @return {Promise} returns Promise if no callback passed
  395.  */
  396. Admin.prototype.setProfilingLevel = function(level, callback) {
  397.   var self = this;
  399.   // Execute using callback
  400.   if(typeof callback == 'function') return setProfilingLevel(self, level, callback);
  402.   // Return a Promise
  403.   return new this.s.promiseLibrary(function(resolve, reject) {
  404.     setProfilingLevel(self, level, function(err, r) {
  405.       if(err) return reject(err);
  406.       resolve(r);
  407.     });
  408.   });
  409. };
  411. var setProfilingLevel = function(self, level, callback) {
  412.   var command = {};
  413.   var profile = 0;
  415.   if(level == "off") {
  416.     profile = 0;
  417.   } else if(level == "slow_only") {
  418.     profile = 1;
  419.   } else if(level == "all") {
  420.     profile = 2;
  421.   } else {
  422.     return callback(new Error("Error: illegal profiling level value " + level));
  423.   }
  425.   // Set up the profile number
  426.   command['profile'] = profile;
  428.   self.s.db.executeDbAdminCommand(command, function(err, doc) {
  429.     if(err == null && doc.ok === 1)
  430.       return callback(null, level);
  431.     return err != null ? callback(err, null) : callback(new Error("Error with profile command"), null);
  432.   });
  433. }
  435. define.classMethod('setProfilingLevel', {callback: true, promise:true});
  437. /**
  438.  * Retrieve the current profiling information for MongoDB
  439.  *
  440.  * @param {Admin~resultCallback} [callback] The command result callback.
  441.  * @return {Promise} returns Promise if no callback passed
  442.  * @deprecated Query the system.profile collection directly.
  443.  */
  444. Admin.prototype.profilingInfo = function(callback) {
  445.   var self = this;
  447.   // Execute using callback
  448.   if(typeof callback == 'function') return profilingInfo(self, callback);
  450.   // Return a Promise
  451.   return new this.s.promiseLibrary(function(resolve, reject) {
  452.     profilingInfo(self, function(err, r) {
  453.       if(err) return reject(err);
  454.       resolve(r);
  455.     });
  456.   });
  457. };
  459. var profilingInfo = function(self, callback) {
  460.   try {
  461.     self.s.topology.cursor("admin.system.profile", { find: 'system.profile', query: {}}, {}).toArray(callback);
  462.   } catch (err) {
  463.     return callback(err, null);
  464.   }
  465. }
  467. define.classMethod('profilingLevel', {callback: true, promise:true});
  469. /**
  470.  * Validate an existing collection
  471.  *
  472.  * @param {string} collectionName The name of the collection to validate.
  473.  * @param {object} [options=null] Optional settings.
  474.  * @param {Admin~resultCallback} [callback] The command result callback.
  475.  * @return {Promise} returns Promise if no callback passed
  476.  */
  477. Admin.prototype.validateCollection = function(collectionName, options, callback) {
  478.   var self = this;
  479.   var args = Array.prototype.slice.call(arguments, 1);
  480.   callback = args.pop();
  481.   if(typeof callback != 'function') args.push(callback);
  482.   options = args.length ? args.shift() : {};
  483.   options = options || {};
  485.   // Execute using callback
  486.   if(typeof callback == 'function')
  487.     return validateCollection(self, collectionName, options, callback);
  489.   // Return a Promise
  490.   return new this.s.promiseLibrary(function(resolve, reject) {
  491.     validateCollection(self, collectionName, options, function(err, r) {
  492.       if(err) return reject(err);
  493.       resolve(r);
  494.     });
  495.   });
  496. };
  498. var validateCollection = function(self, collectionName, options, callback) {
  499.   var command = {validate: collectionName};
  500.   var keys = Object.keys(options);
  502.   // Decorate command with extra options
  503.   for(var i = 0; i < keys.length; i++) {
  504.     if(options.hasOwnProperty(keys[i])) {
  505.       command[keys[i]] = options[keys[i]];
  506.     }
  507.   }
  509.   self.s.db.command(command, function(err, doc) {
  510.     if(err != null) return callback(err, null);
  512.     if(doc.ok === 0)
  513.       return callback(new Error("Error with validate command"), null);
  514.     if(doc.result != null && doc.result.constructor != String)
  515.       return callback(new Error("Error with validation data"), null);
  516.     if(doc.result != null && doc.result.match(/exception|corrupt/) != null)
  517.       return callback(new Error("Error: invalid collection " + collectionName), null);
  518.     if(doc.valid != null && !doc.valid)
  519.       return callback(new Error("Error: invalid collection " + collectionName), null);
  521.     return callback(null, doc);
  522.   });
  523. }
  525. define.classMethod('validateCollection', {callback: true, promise:true});
  527. /**
  528.  * List the available databases
  529.  *
  530.  * @param {Admin~resultCallback} [callback] The command result callback.
  531.  * @return {Promise} returns Promise if no callback passed
  532.  */
  533. Admin.prototype.listDatabases = function(callback) {
  534.   var self = this;
  535.   // Execute using callback
  536.   if(typeof callback == 'function') return self.s.db.executeDbAdminCommand({listDatabases:1}, {}, callback);
  538.   // Return a Promise
  539.   return new this.s.promiseLibrary(function(resolve, reject) {
  540.     self.s.db.executeDbAdminCommand({listDatabases:1}, {}, function(err, r) {
  541.       if(err) return reject(err);
  542.       resolve(r);
  543.     });
  544.   });
  545. }
  547. define.classMethod('listDatabases', {callback: true, promise:true});
  549. /**
  550.  * Get ReplicaSet status
  551.  *
  552.  * @param {Admin~resultCallback} [callback] The command result callback.
  553.  * @return {Promise} returns Promise if no callback passed
  554.  */
  555. Admin.prototype.replSetGetStatus = function(callback) {
  556.   var self = this;
  557.   // Execute using callback
  558.   if(typeof callback == 'function') return replSetGetStatus(self, callback);
  559.   // Return a Promise
  560.   return new this.s.promiseLibrary(function(resolve, reject) {
  561.     replSetGetStatus(self, function(err, r) {
  562.       if(err) return reject(err);
  563.       resolve(r);
  564.     });
  565.   });
  566. };
  568. var replSetGetStatus = function(self, callback) {
  569.   self.s.db.executeDbAdminCommand({replSetGetStatus:1}, function(err, doc) {
  570.     if(err == null && doc.ok === 1)
  571.       return callback(null, doc);
  572.     if(err) return callback(err, false);
  573.     callback(toError(doc), false);
  574.   });
  575. }
  577. define.classMethod('replSetGetStatus', {callback: true, promise:true});
  579. module.exports = Admin;