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']] } }
})

Hierarchy

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.
- Optional options: DbOptions
  
  Optional settings for Db construction.
Returns Db
- Defined in src/db.ts:149

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

databaseName

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

namespace

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

options

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

readConcern

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

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

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

writeConcern

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

Methods

admin

admin(): Admin
Return the Admin db instance

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

aggregate

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

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

collections

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

command

command(command, options?): Promise<Document>
Execute a command
Parameters
- command: Document
  
  The command to run
- Optional options: RunCommandOptions
  
  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:269

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
- Optional options: CreateCollectionOptions
  
  Optional settings for the command
Returns Promise<Collection<TSchema>>
- Defined in src/db.ts:234

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
- Optional options: CreateIndexesOptions
  
  Optional settings for the command
Returns Promise<string>
- Defined in src/db.ts:431

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
- Optional options: DropCollectionOptions
  
  Optional settings for the command
Returns Promise<boolean>
- Defined in src/db.ts:393

dropDatabase

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

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:490
indexInformation(name, options): Promise<IndexDescriptionCompact>
Parameters
- name: string
- options: IndexInformationOptions & {
  full?: false;
  }
Returns Promise<IndexDescriptionCompact>
- Defined in src/db.ts:494
indexInformation(name, options): Promise<IndexDescriptionCompact | IndexDescriptionInfo[]>
Parameters
- name: string
- options: IndexInformationOptions
Returns Promise<IndexDescriptionCompact | IndexDescriptionInfo[]>
- Defined in src/db.ts:498
indexInformation(name): Promise<IndexDescriptionCompact>
Parameters
- name: string
Returns Promise<IndexDescriptionCompact>
- Defined in src/db.ts:502

listCollections

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

profilingLevel

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

removeUser

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

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
- Optional options: 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:371

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.
- Optional options: RunCursorCommandOptions
  
  Configurations for running the command, bson options will apply to getMores
Returns RunCommandCursor
- Defined in src/db.ts:547

setProfilingLevel

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

stats

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

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
- Defined in src/db.ts:525

Class Db

Example

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

client: MongoClient

databaseName: string

Optional options: DbOptions

Returns Db

Properties

Static SYSTEM_COMMAND_COLLECTION

Static SYSTEM_INDEX_COLLECTION

Static SYSTEM_JS_COLLECTION

Static SYSTEM_NAMESPACE_COLLECTION

Static SYSTEM_PROFILE_COLLECTION

Static SYSTEM_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

writeConcern

Returns undefined | WriteConcern

Methods

admin

Returns Admin

aggregate

Type Parameters

T extends Document = Document

Parameters

pipeline: Document[] = []

Optional options: AggregateOptions

Returns AggregationCursor<T>

collection

Type Parameters

TSchema extends Document = Document

Parameters

name: string

options: CollectionOptions = {}

Returns Collection<TSchema>

collections

Parameters

Optional options: ListCollectionsOptions

Returns Promise<Collection<Document>[]>

command

Parameters

command: Document

Optional options: RunCommandOptions

Returns Promise<Document>

Remarks

createCollection

Type Parameters

TSchema extends Document = Document

Parameters

name: string

Optional options: CreateCollectionOptions

Returns Promise<Collection<TSchema>>

createIndex

Parameters

name: string

indexSpec: IndexSpecification

Optional options: CreateIndexesOptions

Returns Promise<string>

dropCollection

`Optional` options: DbOptions

`Static` SYSTEM_COMMAND_COLLECTION

`Static` SYSTEM_INDEX_COLLECTION

`Static` SYSTEM_JS_COLLECTION

`Static` SYSTEM_NAMESPACE_COLLECTION

`Static` SYSTEM_PROFILE_COLLECTION

`Static` SYSTEM_USER_COLLECTION

`Optional` options: AggregateOptions

`Optional` options: ListCollectionsOptions

`Optional` options: RunCommandOptions

`Optional` options: CreateCollectionOptions

`Optional` options: CreateIndexesOptions

`Optional` options: DropCollectionOptions

`Optional` options: CommandOperationOptions

options: IndexInformationOptions & {
full: true;
}

options: IndexInformationOptions & {
full?: false;
}

options: ListCollectionsOptions & {
nameOnly: true;
}

options: ListCollectionsOptions & {
nameOnly: false;
}

`Optional` filter: Document

`Optional` options: ListCollectionsOptions

`Optional` options: CommandOperationOptions

`Optional` options: CommandOperationOptions

`Optional` options: RenameOptions

`Optional` options: RunCursorCommandOptions

`Optional` options: CommandOperationOptions

`Optional` options: DbStatsOptions