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

Deprecated The write concern. Use writeConcern instead.

wtimeout number optional

Deprecated The write concern timeout. Use writeConcern instead.

j boolean false optional

Deprecated Specify a journal write concern. Use writeConcern instead.

writeConcern object | WriteConcern optional

Specify write concern settings.

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.

bsonRegExp boolean false optional

By default, regex returned from MDB will be native to the language. Setting to true will ensure that a BSON.BSONRegExp object is returned.

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 ReadConcernLevel 'local' optional

Specify a read concern level for the collection operations (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

Retrieve the current profiling information for MongoDB

Deprecated
  • Query the system.profile collection directly.

    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

    Deprecated The write concern. Use writeConcern instead.

    wtimeout number optional

    Deprecated The write concern timeout. Use writeConcern instead.

    j boolean false optional

    Deprecated Specify a journal write concern. Use writeConcern instead.

    writeConcern object | WriteConcern optional

    Specify write concern settings.

    customData object optional

    Custom data associated with the user (only Mongodb 2.6 or higher)

    roles Array.<object> optional

    Roles associated with the created user (only Mongodb 2.6 or higher)

    session ClientSession optional

    optional session to use for this operation

    callback Db~resultCallback optional

    The command result callback

    Returns:
    Promise if no callback passed

    Return the Admin db instance

    Returns:
    the new Admin db instance

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

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

    Name Type Default Description
    pipeline object [] optional

    Array containing all the aggregation framework commands for the execution.

    options object optional

    Optional settings.

    Name Type Default Description
    readPreference ReadPreference | string optional

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

    batchSize number 1000 optional

    The number of documents to return per batch. See aggregation documentation.

    cursor object optional

    Return the query as cursor, on 2.6 > it returns as a real cursor on pre 2.6 it returns as an emulated cursor.

    Name Type Default Description
    batchSize number 1000 optional

    Deprecated. Use options.batchSize

    explain 'queryPlanner' | 'queryPlannerExtended' | 'executionStats' | 'allPlansExecution' | boolean optional

    The verbosity mode for the explain output.

    allowDiskUse boolean false optional

    allowDiskUse lets the server know if it can use disk to store temporary results for the aggregation (requires mongodb 2.6 >).

    maxTimeMS number optional

    maxTimeMS specifies a cumulative time limit in milliseconds for processing operations on the cursor. MongoDB interrupts the operation at the earliest following interrupt point.

    maxAwaitTimeMS number optional

    The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query.

    bypassDocumentValidation boolean false optional

    Allow driver to bypass schema validation in MongoDB 3.2 or higher.

    raw boolean false optional

    Return document results as raw BSON buffers.

    promoteLongs boolean true optional

    Promotes Long values to number if they fit inside the 53 bits resolution.

    promoteValues boolean true optional

    Promotes BSON values to native types where possible, set to false to only receive wrapper types.

    promoteBuffers boolean false optional

    Promotes Binary BSON values to native Node Buffers.

    bsonRegExp boolean false optional

    By default, regex returned from MDB will be native to the language. Setting to true will ensure that a BSON.BSONRegExp object is returned.

    collation object optional

    Specify collation (MongoDB 3.4 or higher) settings for update operation (see 3.4 documentation for available fields).

    comment string optional

    Add a comment to an aggregation command

    hint string | object optional

    Add an index selection hint to an aggregation command

    session ClientSession optional

    optional session to use for this operation

    callback Database~aggregationCallback

    The command result callback

    collection(name, options, callback){Collection}

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

    Name Type Description
    name string

    the collection name we wish to access.

    options object optional

    Optional settings.

    Name Type Default Description
    w number | string optional

    Deprecated The write concern. Use writeConcern instead.

    wtimeout number optional

    Deprecated The write concern timeout. Use writeConcern instead.

    j boolean false optional

    Deprecated Specify a journal write concern. Use writeConcern instead.

    writeConcern object | WriteConcern optional

    Specify write concern settings.

    raw boolean false optional

    Return document results as raw BSON buffers.

    pkFactory object optional

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

    readPreference ReadPreference | string optional

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

    serializeFunctions boolean false optional

    Serialize functions on any object.

    strict boolean false optional

    Deprecated Returns an error if the collection does not exist

    readConcern object optional

    Specify a read concern for the collection. (only MongoDB 3.2 or higher supported)

    Name Type Default Description
    level ReadConcernLevel 'local' optional

    Specify a read concern level for the collection operations (only MongoDB 3.2 or higher supported)

    callback Db~collectionResultCallback optional

    The collection result callback

    Returns:
    the new Collection instance if not in strict mode

    collections(options, callback){Promise}

    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://www.mongodb.com/docs/manual/reference/command/create/

    Name Type Description
    name string

    the collection name we wish to access.

    options object optional

    Optional settings.

    Name Type Default Description
    w number | string optional

    Deprecated The write concern. Use writeConcern instead.

    wtimeout number optional

    Deprecated The write concern timeout. Use writeConcern instead.

    j boolean false optional

    Deprecated Specify a journal write concern. Use writeConcern instead.

    writeConcern object | WriteConcern optional

    Specify write concern settings.

    raw boolean false optional

    Return document results as raw BSON buffers.

    pkFactory object optional

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

    readPreference ReadPreference | string optional

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

    serializeFunctions boolean false optional

    Serialize functions on any object.

    strict boolean false optional

    DEPRECATED: Returns an error if the collection does not exist

    capped boolean false optional

    Create a capped collection.

    autoIndexId boolean true optional

    DEPRECATED: Create an index on the _id field of the document, True by default on MongoDB 2.6 - 3.0

    size number optional

    The size of the capped collection in bytes.

    max number optional

    The maximum number of documents in the capped collection.

    flags number optional

    Optional. Available for the MMAPv1 storage engine only to set the usePowerOf2Sizes and the noPadding flag.

    storageEngine object optional

    Allows users to specify configuration to the storage engine on a per-collection basis when creating a collection on MongoDB 3.0 or higher.

    validator object optional

    Allows users to specify validation rules or expressions for the collection. For more information, see Document Validation on MongoDB 3.2 or higher.

    validationLevel string optional

    Determines how strictly MongoDB applies the validation rules to existing documents during an update on MongoDB 3.2 or higher.

    validationAction string optional

    Determines whether to error on invalid documents or just warn about the violations but allow invalid documents to be inserted on MongoDB 3.2 or higher.

    indexOptionDefaults object optional

    Allows users to specify a default configuration for indexes when creating a collection on MongoDB 3.2 or higher.

    viewOn string optional

    The name of the source collection or view from which to create the view. The name is not the full namespace of the collection or view; i.e. does not include the database name and implies the same database as the view to create on MongoDB 3.4 or higher.

    pipeline array optional

    An array that consists of the aggregation pipeline stage. Creates the view by applying the specified pipeline to the viewOn collection or view on MongoDB 3.4 or higher.

    collation object optional

    Specify collation (MongoDB 3.4 or higher) settings for update operation (see 3.4 documentation for available fields).

    session ClientSession optional

    optional session to use for this operation

    callback Db~collectionResultCallback optional

    The results callback

    Returns:
    Promise if no callback passed

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

    Creates an index on the db and collection.

    Name Type Description
    name string

    Name of the collection to create the index on.

    fieldOrSpec string | object

    Defines the index.

    options object optional

    Optional settings.

    Name Type Default Description
    w number | string optional

    Deprecated The write concern. Use writeConcern instead.

    wtimeout number optional

    Deprecated The write concern timeout. Use writeConcern instead.

    j boolean false optional

    Deprecated Specify a journal write concern. Use writeConcern instead.

    writeConcern object | WriteConcern optional

    Specify write concern settings.

    unique boolean false optional

    Creates an unique index.

    sparse boolean false optional

    Creates a sparse index.

    background boolean false optional

    Creates the index in the background, yielding whenever possible.

    dropDups boolean false optional

    A unique index cannot be created on a key that has pre-existing duplicate values. If you would like to create the index anyway, keeping the first document the database indexes and deleting all subsequent documents that have duplicate value

    min number optional

    For geospatial indexes set the lower bound for the co-ordinates.

    max number optional

    For geospatial indexes set the high bound for the co-ordinates.

    v number optional

    Specify the format version of the indexes.

    expireAfterSeconds number optional

    Allows you to expire data on indexes applied to a data (MongoDB 2.2 or higher)

    name string optional

    Override the autogenerated index name (useful if the resulting name is larger than 128 bytes)

    partialFilterExpression object optional

    Creates a partial index based on the given filter object (MongoDB 3.2 or higher)

    session ClientSession optional

    optional session to use for this operation

    commitQuorum number | string optional

    (MongoDB 4.4. or higher) Specifies how many data-bearing members of a replica set, including the primary, must complete the index builds successfully before the primary marks the indexes as ready. This option accepts the same values for the "w" field in a write concern plus "votingMembers", which indicates all voting data-bearing nodes.

    callback Db~resultCallback optional

    The command result callback

    Returns:
    Promise if no callback passed

    dropCollection(name, options, callback){Promise}

    Drop a collection from the database, removing it permanently. New accesses will create a new collection.

    Name Type Description
    name string

    Name of collection to drop

    options Object optional

    Optional settings

    Name Type Default Description
    w number | string optional

    Deprecated The write concern. Use writeConcern instead.

    wtimeout number optional

    Deprecated The write concern timeout. Use writeConcern instead.

    j boolean false optional

    Deprecated Specify a journal write concern. Use writeConcern instead.

    writeConcern object | WriteConcern optional

    Specify write concern settings.

    session ClientSession optional

    optional session to use for this operation

    callback Db~resultCallback optional

    The results callback

    Returns:
    Promise if no callback passed

    dropDatabase(options, callback){Promise}

    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

    Deprecated The write concern. Use writeConcern instead.

    wtimeout number optional

    Deprecated The write concern timeout. Use writeConcern instead.

    j boolean false optional

    Deprecated Specify a journal write concern. Use writeConcern instead.

    writeConcern object | WriteConcern optional

    Specify write concern settings.

    unique boolean false optional

    Creates an unique index.

    sparse boolean false optional

    Creates a sparse index.

    background boolean false optional

    Creates the index in the background, yielding whenever possible.

    dropDups boolean false optional

    A unique index cannot be created on a key that has pre-existing duplicate values. If you would like to create the index anyway, keeping the first document the database indexes and deleting all subsequent documents that have duplicate value

    min number optional

    For geospatial indexes set the lower bound for the co-ordinates.

    max number optional

    For geospatial indexes set the high bound for the co-ordinates.

    v number optional

    Specify the format version of the indexes.

    expireAfterSeconds number optional

    Allows you to expire data on indexes applied to a data (MongoDB 2.2 or higher)

    name number optional

    Override the autogenerated index name (useful if the resulting name is larger than 128 bytes)

    session ClientSession optional

    optional session to use for this operation

    callback Db~resultCallback optional

    The command result callback

    Deprecated
    • since version 2.0
      Returns:
      Promise if no callback passed

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

      Evaluate JavaScript on the server

      Name Type Description
      code Code

      JavaScript to execute on server.

      parameters object | array

      The parameters for the call.

      options object optional

      Optional settings.

      Name Type Default Description
      nolock boolean false optional

      Tell MongoDB not to block on the evaluation of the javascript.

      session ClientSession optional

      optional session to use for this operation

      callback Db~resultCallback optional

      The results callback

      Deprecated
      • Eval is deprecated on MongoDB 3.2 and forward
        Returns:
        Promise if no callback passed

        executeDbAdminCommand(command, options, callback){Promise}

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

        The batchSize for the returned command cursor or if pre 2.8 the systems batch collection

        readPreference ReadPreference | string optional

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

        session ClientSession optional

        optional session to use for this operation

        profilingLevel(options, callback){Promise}

        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

        Deprecated The write concern. Use writeConcern instead.

        wtimeout number optional

        Deprecated The write concern timeout. Use writeConcern instead.

        j boolean false optional

        Deprecated Specify a journal write concern. Use writeConcern instead.

        writeConcern object | WriteConcern optional

        Specify write concern settings.

        session ClientSession optional

        optional session to use for this operation

        callback Db~resultCallback optional

        The command result callback

        Returns:
        Promise if no callback passed

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

        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

        Deprecated
        • This function is deprecated and will be removed in the next major version.

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

          The number of documents to return per batch. See aggregation documentation.

          collation object optional

          Specify collation settings for operation. See aggregation documentation.

          readPreference ReadPreference optional

          The read preference. Defaults to the read preference of the database. See read preference documentation.

          startAtOperationTime Timestamp optional

          receive change events that occur after the specified timestamp

          session ClientSession optional

          optional session to use for this operation

          Since:
          • 3.1.0
          Returns:
          ChangeStream instance.

          Type Definitions

          collectionResultCallback(error, collection)

          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: