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

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

databaseName

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

namespace

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

options

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

readConcern

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

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

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

writeConcern

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

Methods

addUser

addUser(username, passwordOrOptions?, options?): Promise<Document>
Add a user to the database
Parameters
- username: string
  
  The username for the new user
- Optional passwordOrOptions: string | AddUserOptions
  
  An optional password for the new user, or the options for the command
- Optional options: AddUserOptions
  
  Optional settings for the command
Returns Promise<Document>

Deprecated
Use the createUser command in db.command() instead.

See
https://www.mongodb.com/docs/manual/reference/command/createUser/
- Defined in src/db.ts:430

admin

admin(): Admin
Return the Admin db instance

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

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

collection

collection<TSchema>(name, options?): Collection<TSchema>
Returns a reference to a MongoDB Collection. If it does not exist it will be created implicitly.
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:294

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

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

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/
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:225

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

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

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

indexInformation

indexInformation(name, options?): Promise<Document>
Retrieves this collections index info.
Parameters
- name: string
  
  The name of the collection.
- Optional options: IndexInformationOptions
  
  Optional settings for the command
Returns Promise<Document>
- Defined in src/db.ts:495

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;
  }
  
  Optional settings for the command
Returns ListCollectionsCursor<Pick<CollectionInfo, "type" | "name">>
- Defined in src/db.ts:319
listCollections(filter, options): ListCollectionsCursor<CollectionInfo>
Parameters
- filter: Document
- options: ListCollectionsOptions & {
  nameOnly: false;
  }
Returns ListCollectionsCursor<CollectionInfo>
- Defined in src/db.ts:323
listCollections<T>(filter?, options?): ListCollectionsCursor<T>
Type Parameters
- T extends CollectionInfo | Pick<CollectionInfo, "type" | "name"> = CollectionInfo | Pick<CollectionInfo, "type" | "name">
Parameters
- Optional filter: Document
- Optional options: ListCollectionsOptions
Returns ListCollectionsCursor<T>
- Defined in src/db.ts:327

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

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

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

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

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

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

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

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

addUser

Parameters

username: string

Optional passwordOrOptions: string | AddUserOptions

Optional options: AddUserOptions

Returns Promise<Document>

Deprecated

See

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

`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` passwordOrOptions: string | AddUserOptions

`Optional` options: AddUserOptions

`Optional` options: AggregateOptions

`Optional` options: ListCollectionsOptions

`Optional` options: RunCommandOptions

`Optional` options: CreateCollectionOptions

`Optional` options: CreateIndexesOptions

`Optional` options: DropCollectionOptions

`Optional` options: CommandOperationOptions

`Optional` options: IndexInformationOptions

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