Class: Db

Db

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

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.

Methods

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

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

Return the Admin db instance

Returns:
the new Admin db instance

collection(name, options, callback){Collection}

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}

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}

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}

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://docs.mongodb.com/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}

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}

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}

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}

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}

    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}

      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}

      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}

      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

      profilingInfo(options, callback){Promise}

      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}

        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}

        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}

        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}

        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}

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

        Unref all sockets

        watch(pipeline, options){ChangeStream}

        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)

        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

        Db close event

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

        Type:

        Db error event

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

        Type:

        fullsetup

        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

        Db parseError event

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

        Type:

        reconnect

        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

        Db timeout event

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

        Type: