Connection

Connection constructor

For practical reasons, a Connection equals a Db.

Returns a promise that resolves when this connection successfully connects to MongoDB, or rejects if this connection failed to connect.

Example:

const conn = await mongoose.createConnection('mongodb://127.0.0.1:27017/test').
  asPromise();
conn.readyState; // 1, means Mongoose is connected

Requires MongoDB Server 8.0 or greater. Executes bulk write operations across multiple models in a single operation. You must specify the model for each operation: Mongoose will use model for casting and validation, as well as determining which collection to apply the operation to.

Example:

const Test = mongoose.model('Test', new Schema({ name: String }));

await db.bulkWrite([
  { model: Test, name: 'insertOne', document: { name: 'test1' } }, // Can specify model as a Model class...
  { model: 'Test', name: 'insertOne', document: { name: 'test2' } } // or as a model name
], { ordered: false });

The MongoClient instance this connection uses to talk to MongoDB. Mongoose automatically sets this property when the connection is opened.

Closes the connection

Retrieves a raw collection instance, creating it if not cached. This method returns a thin wrapper around a [MongoDB Node.js driver collection](MongoDB Node.js driver collection). Using a Collection bypasses Mongoose middleware, validation, and casting, letting you use MongoDB Node.js driver functionality directly.

A hash of the collections associated with this connection

A hash of the global options that are associated with this connection

Helper for createCollection(). Will explicitly create the given collection with specified options. Used to create capped collections and views from mongoose.

Options are passed down without modification to the MongoDB driver's createCollection() function

Calls createCollection() on a models in a series.

The mongodb.Db instance, set when the connection is opened

Removes the model named name from this connection, if it exists. You can use this function to clean up any models you created in your tests to prevent OverwriteModelErrors.

Example:

conn.model('User', new Schema({ name: String }));
console.log(conn.model('User')); // Model object
conn.deleteModel('User');
console.log(conn.model('User')); // undefined

// Usually useful in a Mocha `afterEach()` hook
afterEach(function() {
  conn.deleteModel(/.+/); // Delete every model
});

Destroy the connection. Similar to .close, but also removes the connection from Mongoose's connections list and prevents the connection from ever being re-opened.

Helper for dropCollection(). Will delete the given collection, including all documents and indexes.

Helper for dropDatabase(). Deletes the given database, including all collections, documents, and indexes.

Example:

const conn = mongoose.createConnection('mongodb://127.0.0.1:27017/mydb');
// Deletes the entire 'mydb' database
await conn.dropDatabase();

Gets the value of the option key. Equivalent to conn.options[key]

Example:

conn.get('test'); // returns the 'test' value

Returns the MongoDB driver MongoClient instance that this connection uses to talk to MongoDB.

Example:

const conn = await mongoose.createConnection('mongodb://127.0.0.1:27017/test').
  asPromise();

conn.getClient(); // MongoClient { ... }

The host name portion of the URI. If multiple hosts, such as a replica set, this will contain the first host name in the URI

Example:

mongoose.createConnection('mongodb://127.0.0.1:27017/mydb').host; // "127.0.0.1"

A number identifier for this connection. Used for debugging when you have multiple connections.

Example:

// The default connection has `id = 0`
mongoose.connection.id; // 0

// If you create a new connection, Mongoose increments id
const conn = mongoose.createConnection();
conn.id; // 1

Helper for MongoDB Node driver's listCollections(). Returns an array of collection objects.

Helper for MongoDB Node driver's listDatabases(). Returns an object with a databases property that contains an array of database objects.

Example:

const { databases } = await mongoose.connection.listDatabases();
databases; // [{ name: 'mongoose_test', sizeOnDisk: 0, empty: false }]

Defines or retrieves a model.

const mongoose = require('mongoose');
const db = mongoose.createConnection(..);
db.model('Venue', new Schema(..));
const Ticket = db.model('Ticket', new Schema(..));
const Venue = db.model('Venue');

When no collection argument is passed, Mongoose produces a collection name by passing the model name to the utils.toCollectionName method. This method pluralizes the name. If you don't like this behavior, either pass a collection name or set your schemas collection name option.

Example:

const schema = new Schema({ name: String }, { collection: 'actor' });

// or

schema.set('collection', 'actor');

// or

const collectionName = 'actor'
const M = conn.model('Actor', schema, collectionName)

Returns an array of model names created on this connection.

A POJO containing a map from model names to models. Contains all models that have been added to this connection using Connection#model().

Example:

const conn = mongoose.createConnection();
const Test = conn.model('Test', mongoose.Schema({ name: String }));

Object.keys(conn.models).length; // 1
conn.models.Test === Test; // true

The name of the database this connection points to.

Example:

mongoose.createConnection('mongodb://127.0.0.1:27017/mydb').name; // "mydb"

Listen to events in the Connection

Listen to a event once in the Connection

Opens the connection with a URI using MongoClient.connect().

The password specified in the URI

Example:

mongoose.createConnection('mongodb://val:psw@127.0.0.1:27017/mydb').pass; // "psw"

Declares a plugin executed on all schemas you pass to conn.model()

Equivalent to calling .plugin(fn) on each schema you create.

Example:

const db = mongoose.createConnection('mongodb://127.0.0.1:27017/mydb');
db.plugin(() => console.log('Applied'));
db.plugins.length; // 1

db.model('Test', new Schema({})); // Prints "Applied"

The plugins that will be applied to all models created on this connection.

Example:

const db = mongoose.createConnection('mongodb://127.0.0.1:27017/mydb');
db.plugin(() => console.log('Applied'));
db.plugins.length; // 1

db.model('Test', new Schema({})); // Prints "Applied"

The port portion of the URI. If multiple hosts, such as a replica set, this will contain the port from the first host name in the URI.

Example:

mongoose.createConnection('mongodb://127.0.0.1:27017/mydb').port; // 27017

Connection ready state

• 0 = disconnected
• 1 = connected
• 2 = connecting
• 3 = disconnecting

Each state change emits its associated event name.

Example:

conn.on('connected', callback);
conn.on('disconnected', callback);

Removes the database connection with the given name created with with useDb().

Throws an error if the database connection was not found.

Example:

// Connect to `initialdb` first
const conn = await mongoose.createConnection('mongodb://127.0.0.1:27017/initialdb').asPromise();

// Creates an un-cached connection to `mydb`
const db = conn.useDb('mydb');

// Closes `db`, and removes `db` from `conn.relatedDbs` and `conn.otherDbs`
await conn.removeDb('mydb');

Sets the value of the option key. Equivalent to conn.options[key] = val

Supported options include:

• maxTimeMS: Set maxTimeMS for all queries on this connection.
• 'debug': If true, prints the operations mongoose sends to MongoDB to the console. If a writable stream is passed, it will log to that stream, without colorization. If a callback function is passed, it will receive the collection name, the method name, then all arugments passed to the method. For example, if you wanted to replicate the default logging, you could output from the callback Mongoose: ${collectionName}.${methodName}(${methodArgs.join(', ')}).

Example:

conn.set('test', 'foo');
conn.get('test'); // 'foo'
conn.options.test; // 'foo'

Set the MongoDB driver MongoClient instance that this connection uses to talk to MongoDB. This is useful if you already have a MongoClient instance, and want to reuse it.

Example:

const client = await mongodb.MongoClient.connect('mongodb://127.0.0.1:27017/test');

const conn = mongoose.createConnection().setClient(client);

conn.getClient(); // MongoClient { ... }
conn.readyState; // 1, means 'CONNECTED'

Requires MongoDB >= 3.6.0. Starts a MongoDB session for benefits like causal consistency, retryable writes, and transactions.

Example:

const session = await conn.startSession();
let doc = await Person.findOne({ name: 'Ned Stark' }, null, { session });
await doc.remove();
// `doc` will always be null, even if reading from a replica set
// secondary. Without causal consistency, it is possible to
// get a doc back from the below query if the query reads from a
// secondary that is experiencing replication lag.
doc = await Person.findOne({ name: 'Ned Stark' }, null, { session, readPreference: 'secondary' });

Syncs all the indexes for the models registered with this connection.

Requires MongoDB >= 3.6.0. Executes the wrapped async function in a transaction. Mongoose will commit the transaction if the async function executes successfully and attempt to retry if there was a retriable error.

Calls the MongoDB driver's session.withTransaction(), but also handles resetting Mongoose document state as shown below.

Example:

const doc = new Person({ name: 'Will Riker' });
await db.transaction(async function setRank(session) {
  doc.rank = 'Captain';
  await doc.save({ session });
  doc.isNew; // false

  // Throw an error to abort the transaction
  throw new Error('Oops!');
},{ readPreference: 'primary' }).catch(() => {});

// true, `transaction()` reset the document's state because the
// transaction was aborted.
doc.isNew;

Switches to a different database using the same connection pool.

Returns a new connection object, with the new db.

Example:

// Connect to `initialdb` first
const conn = await mongoose.createConnection('mongodb://127.0.0.1:27017/initialdb').asPromise();

// Creates an un-cached connection to `mydb`
const db = conn.useDb('mydb');
// Creates a cached connection to `mydb2`. All calls to `conn.useDb('mydb2', { useCache: true })` will return the same
// connection instance as opposed to creating a new connection instance
const db2 = conn.useDb('mydb2', { useCache: true });

The username specified in the URI

Example:

mongoose.createConnection('mongodb://val:psw@127.0.0.1:27017/mydb').user; // "val"

Watches the entire underlying database for changes. Similar to Model.watch().

This function does not trigger any middleware. In particular, it does not trigger aggregate middleware.

The ChangeStream object is an event emitter that emits the following events:

• 'change': A change occurred, see below example
• 'error': An unrecoverable error occurred. In particular, change streams currently error out if they lose connection to the replica set primary. Follow this GitHub issue for updates.
• 'end': Emitted if the underlying stream is closed
• 'close': Emitted if the underlying stream is closed

Example:

const User = conn.model('User', new Schema({ name: String }));

const changeStream = conn.watch().on('change', data => console.log(data));

// Triggers a 'change' event on the change stream.
await User.create({ name: 'test' });

A convenience wrapper for connection.client.withSession().

Example:

await conn.withSession(async session => {
  const doc = await TestModel.findOne().session(session);
});