Class: Db

Members

profilingInfo

Retrieve the current profiling information for MongoDB

Deprecated

• Query the system.profile collection directly.

Methods

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

lib/db.js, line 833

Add a user to the database.

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

Returns:

Promise if no callback passed

admin(){Admin}

lib/db.js, line 365

Return the Admin db instance

Returns:

the new Admin db instance

aggregate(pipeline, options, callback){null|AggregationCursor}

lib/db.js, line 333

Execute an aggregation framework pipeline against the database, needs MongoDB >= 3.6

Name	Type	Default	Description
pipeline	object	[]	optional Array containing all the aggregation framework commands for the execution.
options	object		optional Optional settings. Name Type Default Description readPreference ReadPreference | string optional The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST). batchSize number 1000 optional The number of documents to return per batch. See aggregation documentation. cursor object optional Return the query as cursor, on 2.6 > it returns as a real cursor on pre 2.6 it returns as an emulated cursor. Name Type Default Description batchSize number 1000 optional Deprecated. Use options.batchSize explain 'queryPlanner' | 'queryPlannerExtended' | 'executionStats' | 'allPlansExecution' | boolean optional The verbosity mode for the explain output. allowDiskUse boolean false optional allowDiskUse lets the server know if it can use disk to store temporary results for the aggregation (requires mongodb 2.6 >). maxTimeMS number optional maxTimeMS specifies a cumulative time limit in milliseconds for processing operations on the cursor. MongoDB interrupts the operation at the earliest following interrupt point. maxAwaitTimeMS number optional The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query. bypassDocumentValidation boolean false optional Allow driver to bypass schema validation in MongoDB 3.2 or higher. raw boolean false optional Return document results as raw BSON buffers. promoteLongs boolean true optional Promotes Long values to number if they fit inside the 53 bits resolution. promoteValues boolean true optional Promotes BSON values to native types where possible, set to false to only receive wrapper types. promoteBuffers boolean false optional Promotes Binary BSON values to native Node Buffers. collation object optional Specify collation (MongoDB 3.4 or higher) settings for update operation (see 3.4 documentation for available fields). comment string optional Add a comment to an aggregation command hint string | object optional Add an index selection hint to an aggregation command session ClientSession optional optional session to use for this operation
callback	Database~aggregationCallback		The command result callback

collection(name, options, callback){Collection}

lib/db.js, line 418

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

Name	Type	Description
name	string	the collection name we wish to access.
options	object	optional Optional settings. Name Type Default Description w number | string optional Deprecated The write concern. Use writeConcern instead. wtimeout number optional Deprecated The write concern timeout. Use writeConcern instead. j boolean false optional Deprecated Specify a journal write concern. Use writeConcern instead. writeConcern object | WriteConcern optional Specify write concern settings. raw boolean false optional Return document results as raw BSON buffers. pkFactory object optional A primary key factory object for generation of custom _id keys. readPreference ReadPreference | string 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 optional Specify a read concern for the collection. (only MongoDB 3.2 or higher supported) Name Type Default Description level ReadConcernLevel 'local' optional Specify a read concern level for the collection operations (only MongoDB 3.2 or higher supported)
callback	Db~collectionResultCallback	optional The collection result callback

Returns:

the new Collection instance if not in strict mode

collections(options, callback){Promise}

lib/db.js, line 708

Fetch all collections for the current db.

Name	Type	Description
options	Object	optional Optional settings Name Type Description session ClientSession optional optional session to use for this operation
callback	Db~collectionsResultCallback	optional The results callback

Returns:

Promise if no callback passed

command(command, options, callback){Promise}

lib/db.js, line 299

Execute a command

Name	Type	Description
command	object	The command hash
options	object	optional Optional settings. Name Type Description readPreference ReadPreference | string optional The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST). session ClientSession optional optional session to use for this operation
callback	Db~resultCallback	optional The command result callback

Returns:

Promise if no callback passed

createCollection(name, options, callback){Promise}

lib/db.js, line 531

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	Description
name	string	the collection name we wish to access.
options	object	optional Optional settings. Name Type Default Description w number | string optional Deprecated The write concern. Use writeConcern instead. wtimeout number optional Deprecated The write concern timeout. Use writeConcern instead. j boolean false optional Deprecated Specify a journal write concern. Use writeConcern instead. writeConcern object | WriteConcern optional Specify write concern settings. raw boolean false optional Return document results as raw BSON buffers. pkFactory object optional A primary key factory object for generation of custom _id keys. readPreference ReadPreference | string 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 DEPRECATED: Returns an error if the collection does not exist capped boolean false optional Create a capped collection. autoIndexId boolean true optional DEPRECATED: Create an index on the _id field of the document, True by default on MongoDB 2.6 - 3.0 size number optional The size of the capped collection in bytes. max number optional The maximum number of documents in the capped collection. flags number optional Optional. Available for the MMAPv1 storage engine only to set the usePowerOf2Sizes and the noPadding flag. storageEngine object 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 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 optional Determines how strictly MongoDB applies the validation rules to existing documents during an update on MongoDB 3.2 or higher. validationAction string 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 optional Allows users to specify a default configuration for indexes when creating a collection on MongoDB 3.2 or higher. viewOn string 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 optional An array that consists of the aggregation pipeline stage. Creates the view by applying the specified pipeline to the viewOn collection or view on MongoDB 3.4 or higher. collation object optional Specify collation (MongoDB 3.4 or higher) settings for update operation (see 3.4 documentation for available fields). session ClientSession optional optional session to use for this operation
callback	Db~collectionResultCallback	optional The results callback

Returns:

Promise if no callback passed

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

lib/db.js, line 766

Creates an index on the db and collection.

Name	Type	Description
name	string	Name of the collection to create the index on.
fieldOrSpec	string | object	Defines the index.
options	object	optional Optional settings. Name Type Default Description w number | string optional Deprecated The write concern. Use writeConcern instead. wtimeout number optional Deprecated The write concern timeout. Use writeConcern instead. j boolean false optional Deprecated Specify a journal write concern. Use writeConcern instead. writeConcern object | WriteConcern optional Specify write concern settings. 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 optional For geospatial indexes set the lower bound for the co-ordinates. max number optional For geospatial indexes set the high bound for the co-ordinates. v number optional Specify the format version of the indexes. expireAfterSeconds number optional Allows you to expire data on indexes applied to a data (MongoDB 2.2 or higher) name string optional Override the autogenerated index name (useful if the resulting name is larger than 128 bytes) partialFilterExpression object optional Creates a partial index based on the given filter object (MongoDB 3.2 or higher) session ClientSession optional optional session to use for this operation commitQuorum number | string optional (MongoDB 4.4. or higher) Specifies how many data-bearing members of a replica set, including the primary, must complete the index builds successfully before the primary marks the indexes as ready. This option accepts the same values for the "w" field in a write concern plus "votingMembers", which indicates all voting data-bearing nodes.
callback	Db~resultCallback	optional The command result callback

Returns:

Promise if no callback passed

dropCollection(name, options, callback){Promise}

lib/db.js, line 672

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
options	Object	optional Optional settings Name Type Default Description w number | string optional Deprecated The write concern. Use writeConcern instead. wtimeout number optional Deprecated The write concern timeout. Use writeConcern instead. j boolean false optional Deprecated Specify a journal write concern. Use writeConcern instead. writeConcern object | WriteConcern optional Specify write concern settings. session ClientSession optional optional session to use for this operation
callback	Db~resultCallback	optional The results callback

Returns:

Promise if no callback passed

dropDatabase(options, callback){Promise}

lib/db.js, line 690

Drop a database, removing it permanently from the server.

Name	Type	Description
options	Object	optional Optional settings Name Type Description session ClientSession optional optional session to use for this operation
callback	Db~resultCallback	optional The results callback

Returns:

Promise if no callback passed

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

lib/db.js, line 799

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

Name	Type	Description
name	string	The index name
fieldOrSpec	string | object	Defines the index.
options	object	optional Optional settings. Name Type Default Description w number | string optional Deprecated The write concern. Use writeConcern instead. wtimeout number optional Deprecated The write concern timeout. Use writeConcern instead. j boolean false optional Deprecated Specify a journal write concern. Use writeConcern instead. writeConcern object | WriteConcern optional Specify write concern settings. 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 optional For geospatial indexes set the lower bound for the co-ordinates. max number optional For geospatial indexes set the high bound for the co-ordinates. v number optional Specify the format version of the indexes. expireAfterSeconds number optional Allows you to expire data on indexes applied to a data (MongoDB 2.2 or higher) name number optional Override the autogenerated index name (useful if the resulting name is larger than 128 bytes) session ClientSession optional optional session to use for this operation
callback	Db~resultCallback	optional The command result callback

Deprecated

• since version 2.0

Returns:

Promise if no callback passed

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

lib/db.js, line 615

Evaluate JavaScript on the server

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

Deprecated

• Eval is deprecated on MongoDB 3.2 and forward

Returns:

Promise if no callback passed

executeDbAdminCommand(command, options, callback){Promise}

lib/db.js, line 727

Runs a command on the database as admin.

Name	Type	Description
command	object	The command hash
options	object	optional Optional settings. Name Type Description readPreference ReadPreference | string optional The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST). session ClientSession optional optional session to use for this operation
callback	Db~resultCallback	optional The command result callback

Returns:

Promise if no callback passed

indexInformation(name, options, callback){Promise}

lib/db.js, line 932

Retrieves this collections index info.

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

Returns:

Promise if no callback passed

listCollections(filter, options){CommandCursor}

lib/db.js, line 591

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		optional Optional settings. Name Type Default Description nameOnly boolean false optional Since 4.0: If true, will only return the collection name in the response, and will omit additional info batchSize number 1000 optional The batchSize for the returned command cursor or if pre 2.8 the systems batch collection readPreference ReadPreference | string optional The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST). session ClientSession optional optional session to use for this operation

profilingLevel(options, callback){Promise}

lib/db.js, line 912

Retrieve the current profiling Level for MongoDB

Name	Type	Description
options	Object	optional Optional settings Name Type Description session ClientSession optional optional session to use for this operation
callback	Db~resultCallback	optional The command result callback

Returns:

Promise if no callback passed

removeUser(username, options, callback){Promise}

lib/db.js, line 861

Remove a user from a database

Name	Type	Description
username	string	The username.
options	object	optional Optional settings. Name Type Default Description w number | string optional Deprecated The write concern. Use writeConcern instead. wtimeout number optional Deprecated The write concern timeout. Use writeConcern instead. j boolean false optional Deprecated Specify a journal write concern. Use writeConcern instead. writeConcern object | WriteConcern optional Specify write concern settings. session ClientSession optional optional session to use for this operation
callback	Db~resultCallback	optional The command result callback

Returns:

Promise if no callback passed

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

lib/db.js, line 642

Rename a collection.

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

Returns:

Promise if no callback passed

setProfilingLevel(level, options, callback){Promise}

lib/db.js, line 879

Set the current profiling level of MongoDB

Name	Type	Description
level	string	The new profiling level (off, slow_only, all).
options	Object	optional Optional settings Name Type Description session ClientSession optional optional session to use for this operation
callback	Db~resultCallback	optional The command result callback.

Returns:

Promise if no callback passed

stats(options, callback){Promise}

lib/db.js, line 560

Get all the db statistics.

Name	Type	Description
options	object	optional Optional settings. Name Type Description scale number optional Divide the returned sizes by scale value. session ClientSession optional optional session to use for this operation
callback	Db~resultCallback	optional The collection result callback

Returns:

Promise if no callback passed

unref()

lib/db.js, line 945

Unref all sockets

watch(pipeline, options){ChangeStream}

lib/db.js, line 965

Create a new Change Stream, watching for new changes (insertions, updates, replacements, deletions, and invalidations) in this database. Will ignore all changes to system collections.

Name	Type	Description
pipeline	Array	optional An array of aggregation pipeline stages through which to pass change stream documents. This allows for filtering (using $match) and manipulating the change stream documents.
options	object	optional Optional settings Name Type Default Description fullDocument string 'default' optional Allowed values: ‘default’, ‘updateLookup’. When set to ‘updateLookup’, the change stream will include both a delta describing the changes to the document, as well as a copy of the entire document that was changed from some time after the change occurred. resumeAfter object optional Specifies the logical starting point for the new change stream. This should be the _id field from a previously returned change stream document. maxAwaitTimeMS number optional The maximum amount of time for the server to wait on new documents to satisfy a change stream query batchSize number 1000 optional The number of documents to return per batch. See aggregation documentation. collation object optional Specify collation settings for operation. See aggregation documentation. readPreference ReadPreference optional The read preference. Defaults to the read preference of the database. See read preference documentation. startAtOperationTime Timestamp optional receive change events that occur after the specified timestamp session ClientSession optional optional session to use for this operation

Since:

• 3.1.0

Returns:

ChangeStream instance.

Type Definitions

collectionResultCallback(error, collection)

lib/db.js, line 371

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.

Events

close

lib/db.js, line 988

Db close event

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

Type:

• MongoError

error

lib/db.js, line 1008

Db error event

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

Type:

• MongoError

fullsetup

lib/db.js, line 1035

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 1026

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 997

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 1017

Db timeout event

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

Type:

• MongoError