Class Db

The Db class is a class that represents a MongoDB Database.

Example

import { MongoClient } from 'mongodb';

interface Pet {
  name: string;
  kind: 'dog' | 'cat' | 'fish';
}

const client = new MongoClient('mongodb://localhost:27017');
const db = client.db();

// Create a collection that validates our union
await db.createCollection<Pet>('pets', {
  validator: { $expr: { $in: ['$kind', ['dog', 'cat', 'fish']] } }
})

Constructors

constructor

new Db(client, databaseName, options?): Db
Creates a new Db instance.

Db name cannot contain a dot, the server may apply more restrictions when an operation is run.
Parameters
- client: MongoClient
  The MongoClient for the database.
- databaseName: string
  The name of the database this instance represents.
- Optionaloptions: DbOptions
  Optional settings for Db construction.
Returns Db
- Defined in src/db.ts:152

Properties

`Static`SYSTEM_COMMAND_COLLECTION

SYSTEM_COMMAND_COLLECTION: string = CONSTANTS.SYSTEM_COMMAND_COLLECTION

`Static`SYSTEM_INDEX_COLLECTION

SYSTEM_INDEX_COLLECTION: string = CONSTANTS.SYSTEM_INDEX_COLLECTION

`Static`SYSTEM_JS_COLLECTION

SYSTEM_JS_COLLECTION: string = CONSTANTS.SYSTEM_JS_COLLECTION

`Static`SYSTEM_NAMESPACE_COLLECTION

SYSTEM_NAMESPACE_COLLECTION: string = CONSTANTS.SYSTEM_NAMESPACE_COLLECTION

`Static`SYSTEM_PROFILE_COLLECTION

SYSTEM_PROFILE_COLLECTION: string = CONSTANTS.SYSTEM_PROFILE_COLLECTION

`Static`SYSTEM_USER_COLLECTION

SYSTEM_USER_COLLECTION: string = CONSTANTS.SYSTEM_USER_COLLECTION

Accessors

bsonOptions

get bsonOptions(): BSONSerializeOptions
Returns BSONSerializeOptions
- Defined in src/db.ts:215

databaseName

get databaseName(): string
Returns string
- Defined in src/db.ts:183

namespace

get namespace(): string
Returns string
- Defined in src/db.ts:224

options

get options(): undefined | DbOptions
Returns undefined | DbOptions
- Defined in src/db.ts:188

readConcern

get readConcern(): undefined | ReadConcern
Returns undefined | ReadConcern
- Defined in src/db.ts:199

readPreference

get readPreference(): ReadPreference
The current readPreference of the Db. If not explicitly defined for this Db, will be inherited from the parent MongoClient

Returns ReadPreference
- Defined in src/db.ts:207

secondaryOk

get secondaryOk(): boolean
Check if a secondary can be used (because the read preference is not set to primary)

Returns boolean
- Defined in src/db.ts:195

timeoutMS

get timeoutMS(): undefined | number
Returns undefined | number
- Defined in src/db.ts:228

writeConcern

get writeConcern(): undefined | WriteConcern
Returns undefined | WriteConcern
- Defined in src/db.ts:220

Methods

admin

admin(): Admin
Return the Admin db instance

Returns Admin
- Defined in src/db.ts:313

aggregate

aggregate<T>(pipeline?, options?): AggregationCursor<T>
Execute an aggregation framework pipeline against the database.
Type Parameters
- T extends Document = Document
Parameters
- pipeline: Document[] = []
  An array of aggregation stages to be executed
- Optionaloptions: AggregateOptions
  Optional settings for the command
Returns AggregationCursor<T>
- Defined in src/db.ts:300

collection

collection<TSchema>(name, options?): Collection<TSchema>
Returns a reference to a MongoDB Collection. If it does not exist it will be created implicitly.

Collection namespace validation is performed server-side.
Type Parameters
- TSchema extends Document = Document
Parameters
- name: string
  the collection name we wish to access.
- options: CollectionOptions = {}
Returns Collection<TSchema>
return the new Collection instance
- Defined in src/db.ts:325

collections

collections(options?): Promise<Collection<Document>[]>
Fetch all collections for the current db.
Parameters
- Optionaloptions: ListCollectionsOptions
  Optional settings for the command
Returns Promise<Collection<Document>[]>
- Defined in src/db.ts:437

command

command(command, options?): Promise<Document>
Execute a command
Parameters
- command: Document
  The command to run
- Optionaloptions: {
      readPreference?: ReadPreferenceLike;
      session?: ClientSession;
      timeoutMS?: number;
  } & BSONSerializeOptions & Abortable
  Optional settings for the command
Returns Promise<Document>
Remarks
This command does not inherit options from the MongoClient.

The driver will ensure the following fields are attached to the command sent to the server:
- lsid - sourced from an implicit session or options.session
- $readPreference - defaults to primary or can be configured by options.readPreference
- $db - sourced from the name of this database
If the client has a serverApi setting:
- apiVersion
- apiStrict
- apiDeprecationErrors
When in a transaction:
- readConcern - sourced from readConcern set on the TransactionOptions
- writeConcern - sourced from writeConcern set on the TransactionOptions
Attaching any of the above fields to the command will have no effect as the driver will overwrite the value.
- Defined in src/db.ts:276

createCollection

createCollection<TSchema>(name, options?): Promise<Collection<TSchema>>
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/

Collection namespace validation is performed server-side.
Type Parameters
- TSchema extends Document = Document
Parameters
- name: string
  The name of the collection to create
- Optionaloptions: CreateCollectionOptions
  Optional settings for the command
Returns Promise<Collection<TSchema>>
- Defined in src/db.ts:241

createIndex

createIndex(name, indexSpec, options?): Promise<string>
Creates an index on the db and collection.
Parameters
- name: string
  Name of the collection to create the index on.
- indexSpec: IndexSpecification
  Specify the field to index, or an index specification
- Optionaloptions: CreateIndexesOptions
  Optional settings for the command
Returns Promise<string>
- Defined in src/db.ts:451

dropCollection

dropCollection(name, options?): Promise<boolean>
Drop a collection from the database, removing it permanently. New accesses will create a new collection.
Parameters
- name: string
  Name of collection to drop
- Optionaloptions: DropCollectionOptions
  Optional settings for the command
Returns Promise<boolean>
- Defined in src/db.ts:413

dropDatabase

dropDatabase(options?): Promise<boolean>
Drop a database, removing it permanently from the server.
Parameters
- Optionaloptions: CommandOperationOptions
  Optional settings for the command
Returns Promise<boolean>
- Defined in src/db.ts:425

indexInformation

indexInformation(name, options): Promise<IndexDescriptionInfo[]>
Retrieves this collections index info.
Parameters
- name: string
  The name of the collection.
- options: IndexInformationOptions & {
  full: true;
  }
  Optional settings for the command
Returns Promise<IndexDescriptionInfo[]>
- Defined in src/db.ts:510
indexInformation(name, options): Promise<IndexDescriptionCompact>
Parameters
- name: string
- options: IndexInformationOptions & {
  full?: false;
  }
Returns Promise<IndexDescriptionCompact>
- Defined in src/db.ts:514
indexInformation(name, options): Promise<IndexDescriptionCompact | IndexDescriptionInfo[]>
Parameters
- name: string
- options: IndexInformationOptions
Returns Promise<IndexDescriptionCompact | IndexDescriptionInfo[]>
- Defined in src/db.ts:518
indexInformation(name): Promise<IndexDescriptionCompact>
Parameters
- name: string
Returns Promise<IndexDescriptionCompact>
- Defined in src/db.ts:522

listCollections

listCollections(filter, options): ListCollectionsCursor<Pick<CollectionInfo, "type" | "name">>
List all collections of this database with optional filter
Parameters
- filter: Document
  Query to filter collections by
- options: ListCollectionsOptions & {
  nameOnly: true;
  } & Abortable
  Optional settings for the command
Returns ListCollectionsCursor<Pick<CollectionInfo, "type" | "name">>
- Defined in src/db.ts:353
listCollections(filter, options): ListCollectionsCursor<CollectionInfo>
Parameters
- filter: Document
- options: ListCollectionsOptions & {
  nameOnly: false;
  } & Abortable
Returns ListCollectionsCursor<CollectionInfo>
- Defined in src/db.ts:357
listCollections<T>(filter?, options?): ListCollectionsCursor<T>
Type Parameters
- T extends CollectionInfo | Pick<CollectionInfo, "type" | "name"> = CollectionInfo | Pick<CollectionInfo, "type" | "name">
Parameters
- Optionalfilter: Document
- Optionaloptions: ListCollectionsOptions & Abortable
Returns ListCollectionsCursor<T>
- Defined in src/db.ts:361

profilingLevel

profilingLevel(options?): Promise<string>
Retrieve the current profiling Level for MongoDB
Parameters
- Optionaloptions: CommandOperationOptions
  Optional settings for the command
Returns Promise<string>
- Defined in src/db.ts:497

removeUser

removeUser(username, options?): Promise<boolean>
Remove a user from a database
Parameters
- username: string
  The username to remove
- Optionaloptions: CommandOperationOptions
  Optional settings for the command
Returns Promise<boolean>
- Defined in src/db.ts:469

renameCollection

renameCollection<TSchema>(fromCollection, toCollection, options?): Promise<Collection<TSchema>>
Rename a collection.
Type Parameters
- TSchema extends Document = Document
Parameters
- fromCollection: string
  Name of current collection to rename
- toCollection: string
  New name of of the collection
- Optionaloptions: RenameOptions
  Optional settings for the command
Returns Promise<Collection<TSchema>>
Remarks
This operation does not inherit options from the MongoClient.
- Defined in src/db.ts:387

runCursorCommand

runCursorCommand(command, options?): RunCommandCursor
A low level cursor API providing basic driver functionality:
- ClientSession management
- ReadPreference for server selection
- Running getMores automatically when a local batch is exhausted
Parameters
- command: Document
  The command that will start a cursor on the server.
- Optionaloptions: RunCursorCommandOptions
  Configurations for running the command, bson options will apply to getMores
Returns RunCommandCursor
- Defined in src/db.ts:619

setProfilingLevel

setProfilingLevel(level, options?): Promise<ProfilingLevel>
Set the current profiling level of MongoDB
Parameters
- level: ProfilingLevel
  The new profiling level (off, slow_only, all).
- Optionaloptions: CommandOperationOptions
  Optional settings for the command
Returns Promise<ProfilingLevel>
- Defined in src/db.ts:482

stats

stats(options?): Promise<Document>
Get all the db statistics.
Parameters
- Optionaloptions: DbStatsOptions
  Optional settings for the command
Returns Promise<Document>
- Defined in src/db.ts:340

watch

watch<TSchema, TChange>(pipeline?, options?): ChangeStream<TSchema, TChange>
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.
Type Parameters
- TSchema extends Document = Document
  Type of the data being detected by the change stream
- TChange extends Document = ChangeStreamDocument<TSchema>
  Type of the whole change stream document emitted
Parameters
- pipeline: Document[] = []
  An array of pipeline stages through which to pass change stream documents. This allows for filtering (using $match) and manipulating the change stream documents.
- options: ChangeStreamOptions = {}
  Optional settings for the command
Returns ChangeStream<TSchema, TChange>
Remarks
watch() accepts two generic arguments for distinct use cases:
- The first is to provide the schema that may be defined for all the collections within this database
- The second is to override the shape of the change stream document entirely, if it is not provided the type will default to ChangeStreamDocument of the first argument
Example
In iterator mode, if a next() call throws a timeout error, it will attempt to resume the change stream. The next call can just be retried after this succeeds.
```
const changeStream = collection.watch([], { timeoutMS: 100 });
try {
    await changeStream.next();
} catch (e) {
    if (e instanceof MongoOperationTimeoutError && !changeStream.closed) {
      await changeStream.next();
    }
    throw e;
}
```
Example
In emitter mode, if the change stream goes timeoutMS without emitting a change event, it will emit an error event that returns a MongoOperationTimeoutError, but will not close the change stream unless the resume attempt fails. There is no need to re-establish change listeners as this will automatically continue emitting change events once the resume attempt completes.
```
const changeStream = collection.watch([], { timeoutMS: 100 });
changeStream.on('change', console.log);
changeStream.on('error', e => {
    if (e instanceof MongoOperationTimeoutError && !changeStream.closed) {
        // do nothing
    } else {
        changeStream.close();
    }
});
```
- Defined in src/db.ts:597

Class Db

Example

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns Db

Properties

StaticSYSTEM_COMMAND_COLLECTION

StaticSYSTEM_INDEX_COLLECTION

StaticSYSTEM_JS_COLLECTION

StaticSYSTEM_NAMESPACE_COLLECTION

StaticSYSTEM_PROFILE_COLLECTION

StaticSYSTEM_USER_COLLECTION

Accessors

bsonOptions

Returns BSONSerializeOptions

databaseName

Returns string

namespace

Returns string

options

Returns undefined | DbOptions

readConcern

Returns undefined | ReadConcern

readPreference

Returns ReadPreference

secondaryOk

Returns boolean

timeoutMS

Returns undefined | number

writeConcern

Returns undefined | WriteConcern

Methods

admin

Returns Admin

aggregate

Type Parameters

Parameters

Returns AggregationCursor<T>

collection

Type Parameters

Parameters

Returns Collection<TSchema>

collections

Parameters

Returns Promise<Collection<Document>[]>

command

Parameters

Returns Promise<Document>

Remarks

createCollection

Type Parameters

Parameters

Returns Promise<Collection<TSchema>>

createIndex

Parameters

Returns Promise<string>

dropCollection

Parameters

Returns Promise<boolean>

dropDatabase

Parameters

Returns Promise<boolean>

indexInformation

Parameters

Returns Promise<IndexDescriptionInfo[]>

Parameters

Returns Promise<IndexDescriptionCompact>

Parameters

Returns Promise<IndexDescriptionCompact | IndexDescriptionInfo[]>

Parameters

Returns Promise<IndexDescriptionCompact>

listCollections

Parameters

Returns ListCollectionsCursor<Pick<CollectionInfo, "type" | "name">>

`Static`SYSTEM_COMMAND_COLLECTION

`Static`SYSTEM_INDEX_COLLECTION

`Static`SYSTEM_JS_COLLECTION

`Static`SYSTEM_NAMESPACE_COLLECTION

`Static`SYSTEM_PROFILE_COLLECTION

`Static`SYSTEM_USER_COLLECTION