Node.js MongoDB Driver API

Class: Db

Db

new Db(databaseName, topology, options){Db}

lib/db.js, line 151

Creates a new Db instance

Name Type Default Description
databaseName string

The name of the database this instance represents.
topology Server | ReplSet | Mongos

The server topology for the database.
options object null optional

Optional settings.

Name Type Default Description
authSource string null optional

If the database authentication is dependent on another databaseName.
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.
forceServerObjectId boolean false optional

Force server to assign _id values instead of driver.
serializeFunctions boolean false optional

Serialize functions on any object.
ignoreUndefined Boolean false optional

Specify if the BSON serializer should ignore undefined fields.
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.
promoteBuffers boolean false optional

Promotes Binary BSON values to native Node Buffers.
promoteValues boolean true optional

Promotes BSON values to native types where possible, set to false to only receive wrapper types.
bufferMaxEntries number -1 optional

Sets a cap on how many operations the driver will buffer up before giving up on getting a working connection, default is -1 which is unlimited.
readPreference ReadPreference | string null optional

The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
pkFactory object null optional

A primary key factory object for generation of custom _id keys.
promiseLibrary object null optional

A Promise library class the application wishes to use such as Bluebird, must be ES6 compatible
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)
Properties:
Name Type Description
serverConfig Server | ReplSet | Mongos

Get the current db topology.
bufferMaxEntries number

Current bufferMaxEntries value for the database
databaseName string

The name of the database this instance represents.
options object

The options associated with the db instance.
native_parser boolean

The current value of the parameter native_parser.
slaveOk boolean

The current slaveOk value for the db instance.
writeConcern object

The current write concern values.
topology object

Access the topology object (single server, replicaset or mongos).
Fires:
Returns:
Db instance.

Methods

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

lib/db.js, line 1316

Add a user to the database.

NOTE: if you are connecting to MongoDB >= 4.0, the password will not be digested.
We STRONGLY recommend that adding users be done exclusively over a TLS connection.

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)
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

collection(name, options, callback){Collection}

lib/db.js, line 408

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: 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 optional

The collection result callback
Returns:
the new Collection instance if not in strict mode

collections(options, callback){Promise}

lib/db.js, line 910

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 351

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).
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 592

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

DEPRECATED: Create an index on the _id field of the document, True by default on MongoDB 2.6 - 3.0
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).
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 1006

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)
session ClientSession optional

optional session to use for this operation
callback Db~resultCallback optional

The command result callback
Returns:
Promise if no callback passed

dropCollection(name, options, callback){Promise}

lib/db.js, line 828

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 Description
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 867

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 1103

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)
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 783

    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 evaulation 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 954

      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).
      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 1516

      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).
      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 659

      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).
      session ClientSession optional

      optional session to use for this operation

      profilingInfo(options, callback){Promise}

      lib/db.js, line 1458

      Retrive the current profiling information 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.
      Deprecated
      • Query the system.profile collection directly.
        Returns:
        Promise if no callback passed

        profilingLevel(options, callback){Promise}

        lib/db.js, line 1484

        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 1400

        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.
        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 804

        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.
        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 1417

        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 614

        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.
        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 1683

        Unref all sockets

        Type Definitions

        collectionResultCallback(error, collection)

        lib/db.js, line 369

        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.

        resultCallback(error, result)

        lib/db.js, line 297

        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

        close

        lib/db.js, line 1687

        Db close event

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

        Type:

        error

        lib/db.js, line 1707

        Db error event

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

        Type:

        fullsetup

        lib/db.js, line 1734

        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:

        parseError

        lib/db.js, line 1725

        Db parseError event

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

        Type:

        reconnect

        lib/db.js, line 1696

        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 1716

        Db timeout event

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

        Type: