Node.js MongoDB Driver API

Class: Db

Db

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

lib/db.js, line 132

Creates a new Db instance

Name Type Description
databaseName string

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

The server topology for the database.
options object optional

Optional settings.

Name Type Default Description
authSource string optional

If the database authentication is dependent on another databaseName.
w number | string optional

The write concern.
wtimeout number 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 optional

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

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

A Promise library class the application wishes to use such as Bluebird, must be ES6 compatible
readConcern object 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.

Members

profilingInfo

Retrive the current profiling information for MongoDB

Deprecated
  • Query the system.profile collection directly.

    Methods

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

    lib/db.js, line 781

    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

    The write concern.
    wtimeout number optional

    The write concern timeout.
    j boolean false optional

    Specify a journal write concern.
    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 271

    Return the Admin db instance

    Returns:
    the new Admin db instance

    collection(name, options, callback){Collection}

    lib/db.js, line 316

    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

    The write concern.
    wtimeout number 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 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 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 659

    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 259

    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 420

    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

    The write concern.
    wtimeout number 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 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
    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. create 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 712

    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

    The write concern.
    wtimeout number 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 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)
    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
    callback Db~resultCallback optional

    The command result callback
    Returns:
    Promise if no callback passed

    dropCollection(name, options, callback){Promise}

    lib/db.js, line 603

    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 629

    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 748

    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

    The write concern.
    wtimeout number 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 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 558

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

        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 865

        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 474

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

        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 800

        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

        The write concern.
        wtimeout number 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 579

        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 816

        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 445

        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 876

        Unref all sockets

        watch(pipeline, options){ChangeStream}

        lib/db.js, line 896

        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 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.
        startAtClusterTime 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 277

        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 919

        Db close event

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

        Type:

        error

        lib/db.js, line 939

        Db error event

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

        Type:

        fullsetup

        lib/db.js, line 966

        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 957

        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 928

        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 948

        Db timeout event

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

        Type: