Class: Db

Db

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

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}

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

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

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

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

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}

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

    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}

      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}

      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}

      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}

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

        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}

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

        Unref all sockets

        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.

        resultCallback(error, result)

        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

        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: