Connection

Connection constructor连接构造函数

For practical reasons, a Connection equals a Db.出于实际原因，Connection等于Db。

Returns a promise that resolves when this connection successfully connects to MongoDB, or rejects if this connection failed to connect.返回一个promise，该promise在该连接成功连接到MongoDB时解析，或者在该连接连接失败时拒绝。

Example:示例：

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

The MongoClient instance this connection uses to talk to MongoDB. 此连接用于与MongoDB对话的MongoClient实例。Mongoose automatically sets this property when the connection is opened.当连接打开时，Mongoose会自动设置此属性。

Closes the connection关闭连接

Retrieves a collection, creating it if not cached.检索集合，如果未缓存则创建该集合。

Not typically needed by applications. Just talk to your collection through your model.应用程序通常不需要。只需通过您的模型与您的集合对话。

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

The mongodb.Db instance, set when the connection is openedmongodbDb实例，在打开连接时设置

Removes the model named name from this connection, if it exists. 从该连接中删除命名的模型name（如果存在）。You can use this function to clean up any models you created in your tests to prevent OverwriteModelErrors.您可以使用此函数来清除您在测试中创建的任何模型，以防止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
});

Destory the connection (not just a alias of .close)

Helper for dropCollection(). dropCollection()的帮助程序。Will delete the given collection, including all documents and indexes.将删除给定的集合，包括所有文档和索引。

Helper for dropDatabase(). 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. URI的主机名部分。If multiple hosts, such as a replica set, this will contain the first host name in the URI如果有多个主机，例如一个复制集，则这将包含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

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. 一个POJO，包含从模型名称到模型的映射。Contains all models that have been added to this connection using Connection#model().包含已使用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"

Opens the connection with a URI using MongoClient.connect().使用MongoClient.connect()打开带有URI的连接。

The password specified in the URIURI中指定的密码

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()声明在传递给conn.model()的所有模式上执行的插件

Equivalent to calling .plugin(fn) on each schema you create.相当于在您创建的每个模式上调用.plugin(fn)。

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.URI的端口部分。如果有多个主机，例如一个复制集，则会包含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);

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.如果异步函数执行成功，Mongoose将提交事务，如果出现可重试的错误，则尝试重试。

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