连接

你可以使用 mongoose.connect() 方法连接到 MongoDB。

mongoose.connect('mongodb://127.0.0.1:27017/myapp');

这是连接在默认端口 (27017) 上本地运行的 myapp 数据库所需的最低限度。 对于本地 MongoDB 数据库，我们建议使用 127.0.0.1 而不是 localhost。 这是因为 Node.js 18 及更高版本更喜欢 IPv6 地址，这意味着，在许多计算机上，Node.js 会将 localhost 解析为 IPv6 地址 ::1，并且 Mongoose 将无法连接，除非 mongodb 实例在启用 ipv6 的情况下运行。

你还可以在 uri 中指定更多参数：

mongoose.connect('mongodb://username:password@host:port/database?options...');

有关详细信息，请参阅 mongodb 连接字符串规范。

• 缓冲
• 错误处理
• 选项
• serverSelectionTimeoutMS
• 连接字符串选项
• 连接事件
• 关于 keepAlive 的注意事项
• 服务器选择
• 副本集连接
• 副本集主机名
• 多 mongos 支持
• 多个连接
• 连接池
• 多租户连接

操作缓冲

Mongoose 让你可以立即开始使用模型，而无需等待 mongoose 建立与 MongoDB 的连接。

mongoose.connect('mongodb://127.0.0.1:27017/myapp');
const MyModel = mongoose.model('Test', new Schema({ name: String }));
// Works
await MyModel.findOne();

这是因为 mongoose 在内部缓冲模型函数调用。 这种缓冲很方便，但也是造成混乱的常见原因。 如果你在没有连接的情况下使用模型，Mongoose 默认情况下不会抛出任何错误。

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

setTimeout(function() {
  mongoose.connect('mongodb://127.0.0.1:27017/myapp');
}, 60000);

// Will just hang until mongoose successfully connects
await promise;

要禁用缓冲，请关闭 结构上的 bufferCommands 选项。 如果你打开了 bufferCommands 并且连接挂起，请尝试关闭 bufferCommands 以查看是否未正确打开连接。 你还可以全局禁用 bufferCommands：

mongoose.set('bufferCommands', false);

请注意，如果你使用 autoCreate 选项.0，缓冲还负责等待 Mongoose 创建集合。 如果禁用缓冲，还应该禁用 autoCreate 选项并使用 createCollection() 创建 上限集合 或 带有排序规则的集合。

const schema = new Schema({
  name: String
}, {
  capped: { size: 1024 },
  bufferCommands: false,
  autoCreate: false // disable `autoCreate` since `bufferCommands` is false
});

const Model = mongoose.model('Test', schema);
// Explicitly create the collection before using it
// so the collection is capped.
await Model.createCollection();

错误处理

Mongoose 连接可能会发生两类错误。

• 初始连接时出错： 如果初始连接失败，Mongoose 将发出 'error' 事件，并且返回的 promise mongoose.connect() 将被拒绝。 然而，Mongoose 会自动尝试重新连接 not。
• 建立初始连接后出错： Mongoose 将尝试重新连接，并且会发出 'error' 事件。

要处理初始连接错误，你应该将 .catch() 或 try/catch 与 async/await 结合使用。

mongoose.connect('mongodb://127.0.0.1:27017/test').
  catch(error => handleError(error));

// Or:
try {
  await mongoose.connect('mongodb://127.0.0.1:27017/test');
} catch (error) {
  handleError(error);
}

要在建立初始连接后处理错误，你应该监听连接上的错误事件。 但是，你仍然需要处理初始连接错误，如上所示。

mongoose.connection.on('error', err => {
  logError(err);
});

请注意，如果 Mongoose 失去与 MongoDB 的连接，它不一定会发出 'error' 事件。 当 Mongoose 与 MongoDB 断开连接时，你应该监听 disconnected 事件来报告。

选项

connect 方法还接受 options 对象，该对象将传递给底层 MongoDB 驱动程序。

mongoose.connect(uri, options);

完整的选项列表可以在 MongoClientOptions 的 MongoDB Node.js 驱动程序文档 上找到。 Mongoose 将选项传递给驱动程序而不进行修改，并对一些例外情况进行取模，如下所述。

• bufferCommands - 这是 Mongoose 特定的选项（未传递给 MongoDB 驱动程序），用于禁用 Mongoose 的缓冲机制
• user/pass - 用于身份验证的用户名和密码。 这些选项是 Mongoose 特定的，它们相当于 MongoDB 驱动程序的 auth.username 和 auth.password 选项。
• autoIndex - 默认情况下，mongoose 在连接时会自动构建在你的结构中定义的索引。 这对于开发来说非常有用，但对于大型生产部署来说并不理想，因为索引构建可能会导致性能下降。 如果将 autoIndex 设置为 false，mongoose 将不会自动为与此连接关联的 any 模型构建索引。
• dbName - 指定要连接到的数据库并覆盖连接字符串中指定的任何数据库。 如果你无法像 一些 mongodb+srv 语法连接 那样在连接字符串中指定默认数据库，这会很有用。

以下是一些对于调整 Mongoose 很重要的选项。

• promiseLibrary - 设置 底层驱动程序的 promise 库。
• maxPoolSize - MongoDB 驱动程序为此连接保持打开的最大套接字数。 默认情况下，maxPoolSize 为 100。 请记住，MongoDB 一次只允许每个套接字执行一个操作，因此，如果你发现有一些缓慢的查询阻碍了更快的查询的继续，你可能需要增加此值。 参见 MongoDB 和 Node.js 中的慢车。 如果遇到 连接限制，你可能需要减少 maxPoolSize。
• minPoolSize - MongoDB 驱动程序为此连接保持打开的最小套接字数。 MongoDB 驱动程序可能会关闭一段时间不活动的套接字。 如果你希望你的应用经历较长的空闲时间，并希望确保你的套接字保持打开状态以避免活动开始时缓慢运行，你可能需要增加 minPoolSize。
• socketTimeoutMS - MongoDB 驱动程序在初始连接后由于不活动而终止套接字之前将等待多长时间。 套接字可能由于没有活动或长时间运行的操作而处于非活动状态。 socketTimeoutMS 默认为 0，这意味着 Node.js 不会因不活动而使套接字超时。 MongoDB 驱动程序成功完成后，此选项将传递给 Node.js socket#setTimeout() function。
• family - 是使用 IPv4 还是 IPv6 进行连接。 该选项传递给 Node.js' dns.lookup() 函数。 如果不指定此选项，MongoDB 驱动程序将首先尝试 IPv6，如果 IPv6 失败，则再尝试 IPv4。 如果你的 mongoose.connect(uri) 调用需要很长时间，请尝试 mongoose.connect(uri, { family: 4 })
• authSource - 使用 user 和 pass 进行身份验证时使用的数据库。 在 MongoDB 中，用户的范围仅限于数据库。 如果你遇到意外的登录失败，你可能需要设置此选项。
• serverSelectionTimeoutMS - MongoDB 驱动程序将尝试找到一个服务器来发送任何给定的操作，并持续重试 serverSelectionTimeoutMS 毫秒。 如果未设置，MongoDB 驱动程序默认使用 30000（30 秒）。
• heartbeatFrequencyMS - MongoDB 驱动程序每隔 heartbeatFrequencyMS 发送一次心跳来检查连接状态。 心跳受 serverSelectionTimeoutMS 约束，因此 MongoDB 驱动程序默认会重试失败的心跳最多 30 秒。 Mongoose 仅在心跳失败后发出 'disconnected' 事件，因此你可能需要减少此设置以减少服务器停机和 Mongoose 发出 'disconnected' 之间的时间。 我们建议你将此设置设置为 1000 以下，过多的心跳会导致性能下降。

serverSelectionTimeoutMS

serverSelectionTimeoutMS 选项极其重要： 它控制 MongoDB Node.js 驱动程序在出错之前尝试重试任何操作的时间。 这包括初始连接（如 await mongoose.connect()）以及向 MongoDB 发出请求的任何操作（如 save() 或 find()）。

默认情况下，serverSelectionTimeoutMS 为 30000（30 秒）。 这意味着，例如，如果你在独立 MongoDB 服务器关闭时调用 mongoose.connect()，则 mongoose.connect() 调用只会在 30 秒后抛出错误。

// Throws an error "getaddrinfo ENOTFOUND doesnt.exist" after 30 seconds
await mongoose.connect('mongodb://doesnt.exist:27017/test');

同样，如果你的独立 MongoDB 服务器在初始连接后出现故障，任何 find() 或 save() 调用都将在 30 秒后出错，除非你的 MongoDB 服务器重新启动。

虽然 30 秒看起来很长，但 serverSelectionTimeoutMS 意味着你在 副本集故障转移 期间不太可能看到任何中断。 如果你丢失了主副本集，MongoDB Node 驱动程序将确保你在副本集选举期间发送的任何操作最终都会执行，假设副本集选举花费的时间少于 serverSelectionTimeoutMS。

要更快地获得有关失败连接的反馈，你可以将 serverSelectionTimeoutMS 减少到 5000，如下所示。 我们不建议减少 serverSelectionTimeoutMS，除非你运行的是独立的 MongoDB 服务器而不是副本集，或者除非你使用像 AWS Lambda 这样的无服务器运行时。

mongoose.connect(uri, {
  serverSelectionTimeoutMS: 5000
});

无法针对 mongoose.connect() 与查询独立调整 serverSelectionTimeoutMS。 如果你想减少查询和其他操作的 serverSelectionTimeoutMS，但仍重试 mongoose.connect() 时间更长，则你有责任使用 for 循环或 像预重试这样的工具 自己重试 connect() 调用。

const serverSelectionTimeoutMS = 5000;

// Prints "Failed 0", "Failed 1", "Failed 2" and then throws an
// error. Exits after approximately 15 seconds.
for (let i = 0; i < 3; ++i) {
  try {
    await mongoose.connect('mongodb://doesnt.exist:27017/test', {
      serverSelectionTimeoutMS
    });
    break;
  } catch (err) {
    console.log('Failed', i);
    if (i >= 2) {
      throw err;
    }
  }
}

回调

connect() 函数还接受回调参数并返回 promise。

mongoose.connect(uri, options, function(error) {
  // Check error in initial connection. There is no 2nd param to the callback.
});

// Or using promises
mongoose.connect(uri, options).then(
  () => { /** ready to use. The `mongoose.connect()` promise resolves to mongoose instance. */ },
  err => { /** handle initial connection error */ }
);

连接字符串选项

你还可以在连接字符串中将驱动程序选项指定为 URI 的 查询字符串中的参数 部分。 这仅适用于传递给 MongoDB 驱动程序的选项。 你 不能 在查询字符串中设置了 Mongoose 特定选项，例如 bufferCommands。

mongoose.connect('mongodb://127.0.0.1:27017/test?socketTimeoutMS=1000&bufferCommands=false&authSource=otherdb');
// The above is equivalent to:
mongoose.connect('mongodb://127.0.0.1:27017/test', {
  socketTimeoutMS: 1000
  // Note that mongoose will **not** pull `bufferCommands` from the query string
});

将选项放入查询字符串的缺点是查询字符串选项更难阅读。 优点是你只需要一个配置选项，URI，而不是 socketTimeoutMS 等的单独选项。最佳实践是将开发和生产之间可能不同的选项（例如 replicaSet 或 ssl）放在连接字符串中，并且选项 在选项对象中应该保持不变，例如 socketTimeoutMS 或 maxPoolSize。

MongoDB 文档有 支持的连接字符串选项 的完整列表。 以下是在连接字符串中设置的一些选项通常很有用，因为它们与主机名和身份验证信息密切相关。

• authSource - 使用 user 和 pass 进行身份验证时使用的数据库。 在 MongoDB 中，用户的范围仅限于数据库。 如果你遇到意外的登录失败，你可能需要设置此选项。
• family - 是使用 IPv4 还是 IPv6 进行连接。 该选项传递给 Node.js' dns.lookup() 函数。 如果不指定此选项，MongoDB 驱动程序将首先尝试 IPv6，如果 IPv6 失败，则再尝试 IPv4。 如果你的 mongoose.connect(uri) 调用需要很长时间，请尝试 mongoose.connect(uri, { family: 4 })

连接事件

连接继承自 Node.js' EventEmitter class，并在连接发生问题时触发事件，例如失去与 MongoDB 服务器的连接。 下面是连接可能发出的事件列表。

• connecting： 当 Mongoose 开始与 MongoDB 服务器建立初始连接时发出
• connected： 当 Mongoose 成功与 MongoDB 服务器建立初始连接时，或者当 Mongoose 在失去连接后重新连接时发出。 如果 Mongoose 失去连接，可能会多次发出。
• open： 在所有该连接的模型上执行 'connected' 和 onOpen 后发出。
• disconnecting： 你的应用调用 Connection#close() 来断开与 MongoDB 的连接
• disconnected： 当 Mongoose 失去与 MongoDB 服务器的连接时发出。 此事件可能是由于你的代码显式关闭连接、数据库服务器崩溃或网络连接问题造成的。
• close： Connection#close() 成功关闭连接后发出。 如果你调用 conn.close()，你将同时收到 'disconnected' 事件和 'close' 事件。
• reconnected： 如果 Mongoose 失去与 MongoDB 的连接并成功重新连接，则发出。 Mongoose 在失去与数据库的连接时尝试 自动重新连接。
• error： 如果连接上发生错误，例如由于格式错误的数据或大于 16MB 的有效负载而导致 parseError，则发出该错误。
• fullsetup： 当你连接到副本集并且 Mongoose 已成功连接到主副本集和至少一个辅助副本集时发出。
• all： 当你连接到副本集并且 Mongoose 已成功连接到连接字符串中指定的所有服务器时发出。

当你连接到单个 MongoDB 服务器（"standalone"）时，如果 Mongoose 与独立服务器断开连接，则会发出 'disconnected'；如果成功连接到独立服务器，则会发出 'connected'。 在副本集中，如果 Mongoose 失去与主副本集的连接，则将发出 'disconnected' 信号；如果设法重新连接至主副本集，则将发出 'connected' 信号。

关于 keepAlive 的注意事项

在 Mongoose 5.2.0 之前，需要启用 keepAlive 选项来启动 TCP 保活，以防止出现 "connection closed" 错误。 然而，从 Mongoose 5.2.0 开始，keepAlive 默认为 true，从 Mongoose 7.2.0 开始，keepAlive 已被弃用。 请从你的 Mongoose 连接中删除 keepAlive 和 keepAliveInitialDelay 选项。

副本集连接

要连接到副本集，你需要传递要连接的主机的逗号分隔列表，而不是单个主机。

mongoose.connect('mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]' [, options]);

例如：

mongoose.connect('mongodb://user:pw@host1.com:27017,host2.com:27017,host3.com:27017/testdb');

要连接到单节点副本集，请指定 replicaSet 选项。

mongoose.connect('mongodb://host1:port1/?replicaSet=rsName');

服务器选择

底层 MongoDB 驱动程序使用名为 服务器选择 的进程连接到 MongoDB 并向 MongoDB 发送操作。 如果 MongoDB 驱动程序在 serverSelectionTimeoutMS 之后找不到服务器来发送操作，你将收到以下错误：

MongoTimeoutError: Server selection timed out after 30000 ms

你可以使用 serverSelectionTimeoutMS 选项到 mongoose.connect() 配置超时：

mongoose.connect(uri, {
  serverSelectionTimeoutMS: 5000 // Timeout after 5s instead of 30s
});

MongoTimeoutError 具有 reason 属性，用于解释服务器选择超时的原因。 例如，如果你使用不正确的密码连接到独立服务器，则 reason 将包含 "认证失败" 错误。

const mongoose = require('mongoose');

const uri = 'mongodb+srv://username:badpw@cluster0-OMITTED.mongodb.net/' +
  'test?retryWrites=true&w=majority';
// Prints "MongoServerError: bad auth Authentication failed."
mongoose.connect(uri, {
  serverSelectionTimeoutMS: 5000
}).catch(err => console.log(err.reason));

副本集主机名

MongoDB 副本集依赖于能够可靠地找出每个成员的域名。
在 Linux 和 OSX 上，MongoDB 服务器使用 hostname 命令 的输出来确定要向副本集报告的域名。 如果你连接到在将 hostname 报告为 localhost 的计算机上运行的远程 MongoDB 副本集，这可能会导致令人困惑的错误：

// Can get this error even if your connection string doesn't include
// `localhost` if `rs.conf()` reports that one replica set member has
// `localhost` as its host name.
MongooseServerSelectionError: connect ECONNREFUSED localhost:27017

如果你遇到类似的错误，请使用 mongo shell 连接到副本集并运行 rs.conf() 命令来检查每个副本集成员的主机名。 跟随 本页有关更改副本集成员主机名的说明。

你还可以检查 MongooseServerSelectionError 的 reason.servers 属性，以查看 MongoDB Node 驱动程序认为你的副本集的状态是什么。 reason.servers 属性包含 map 个服务器描述。

if (err.name === 'MongooseServerSelectionError') {
  // Contains a Map describing the state of your replica set. For example:
  // Map(1) {
  //   'localhost:27017' => ServerDescription {
  //     address: 'localhost:27017',
  //     type: 'Unknown',
  //     ...
  //   }
  // }
  console.log(err.reason.servers);
}

多 mongos 支持

你还可以连接到多个 mongos 实例，以在分片集群中实现高可用性。 你在 mongoose 5.x 中执行 不需要传递任何特殊选项来连接多个 mongos。

// Connect to 2 mongos servers
mongoose.connect('mongodb://mongosA:27501,mongosB:27501', cb);

多个连接

到目前为止，我们已经了解了如何使用 Mongoose 的默认连接来连接 MongoDB。 当你调用 mongoose.connect() 时，Mongoose 会创建一个默认连接。 你可以使用 mongoose.connection 访问默认连接。

由于多种原因，你可能需要多个 MongoDB 连接。 原因之一是你是否有多个数据库或多个 MongoDB 集群。 另一个原因是围绕 慢车 进行工作。 mongoose.createConnection() 函数采用与 mongoose.connect() 相同的参数并返回一个新连接。

const conn = mongoose.createConnection('mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]', options);

然后使用该 connection 对象创建和检索 models。 型号的 always 范围仅限于单个连接。

const UserModel = conn.model('User', userSchema);

如果你使用多个连接，则应确保导出结构、not 模型。 从文件导出模型称为导出模型结构。 导出模型结构受到限制，因为你只能使用一个连接。

const userSchema = new Schema({ name: String, email: String });

// The alternative to the export model pattern is the export schema pattern.
module.exports = userSchema;

// Because if you export a model as shown below, the model will be scoped
// to Mongoose's default connection.
// module.exports = mongoose.model('User', userSchema);

如果你使用导出结构结构，你仍然需要在某处创建模型。 有两种常见的结构。 首先是导出连接并在文件中注册连接上的模型：

// connections/fast.js
const mongoose = require('mongoose');

const conn = mongoose.createConnection(process.env.MONGODB_URI);
conn.model('User', require('../schemas/user'));

module.exports = conn;

// connections/slow.js
const mongoose = require('mongoose');

const conn = mongoose.createConnection(process.env.MONGODB_URI);
conn.model('User', require('../schemas/user'));
conn.model('PageView', require('../schemas/pageView'));

module.exports = conn;

另一种替代方法是注册与依赖注入器或另一个 控制反转 (IOC) 模式 的连接。

const mongoose = require('mongoose');

module.exports = function connectionFactory() {
  const conn = mongoose.createConnection(process.env.MONGODB_URI);

  conn.model('User', require('../schemas/user'));
  conn.model('PageView', require('../schemas/pageView'));

  return conn;
};

连接池

每个 connection，无论是使用 mongoose.connect 还是 mongoose.createConnection 创建，都由内部可配置连接池支持，默认最大大小为 100。 使用你的连接选项调整池大小：

// With object options
mongoose.createConnection(uri, { maxPoolSize: 10 });

// With connection string options
const uri = 'mongodb://127.0.0.1:27017/test?maxPoolSize=10';
mongoose.createConnection(uri);

连接池大小很重要，因为 MongoDB 目前每个套接字只能处理一个操作。 因此 maxPoolSize 起到了并发操作数量的上限的作用。

多租户连接

在 Mongoose 的上下文中，多租户结构通常意味着多个不同的客户端通过单个 Mongoose 应用与 MongoDB 通信的情况。 这通常意味着每个客户端通过单个 Mongoose 应用进行查询并执行更新，但在同一 MongoDB 集群中拥有不同的 MongoDB 数据库。

我们推荐阅读 这篇关于 Mongoose 多租户的文章； 它很好地描述了我们如何定义多租户，并对我们推荐的结构进行了更详细的概述。

对于 Mongoose 中的多租户，我们推荐两种结构：

1. 维护一个连接池，使用 Connection.prototype.useDb() 方法在租户之间切换。
2. 为每个租户维护一个单独的连接池，将连接存储在映射或 POJO 中。

以下是结构(1)的示例。 对于租户数量较少或每个租户的工作负载较轻（大约每秒 < 1 个请求，所有请求占用 < 10 毫秒的数据库处理时间）的情况，我们建议使用模式 (1)。 结构（1）在生产中实现起来更简单，管理也更简单，因为只有 1 个连接池。 但是，在高负载下，你可能会遇到一些问题，即由于 慢车，某些租户的操作会减慢其他租户的操作。

const express = require('express');
const mongoose = require('mongoose');

mongoose.connect('mongodb://127.0.0.1:27017/main');
mongoose.set('debug', true);

mongoose.model('User', mongoose.Schema({ name: String }));

const app = express();

app.get('/users/:tenantId', function(req, res) {
  const db = mongoose.connection.useDb(`tenant_${req.params.tenantId}`, {
    // `useCache` tells Mongoose to cache connections by database name, so
    // `mongoose.connection.useDb('foo', { useCache: true })` returns the
    // same reference each time.
    useCache: true
  });
  // Need to register models every time a new connection is created
  if (!db.models['User']) {
    db.model('User', mongoose.Schema({ name: String }));
  }
  console.log('Find users from', db.name);
  db.model('User').find().
    then(users => res.json({ users })).
    catch(err => res.status(500).json({ message: err.message }));
});

app.listen(3000);

以下是结构(2)的示例。 结构 (2) 更灵活，更适合超过 10k 租户且每秒超过 1 个请求的用例。 由于每个租户都有独立的连接池，一个租户的缓慢操作对其他租户的影响很小。 然而，这种结构在生产中更难实现和管理。 特别是 MongoDB 确实对打开连接数有限制 和 MongoDB Atlas 对打开连接数有单独的限制，因此你需要确保连接池中的套接字总数不超过 MongoDB 的限制。

const express = require('express');
const mongoose = require('mongoose');

const tenantIdToConnection = {};

const app = express();

app.get('/users/:tenantId', function(req, res) {
  let initialConnection = Promise.resolve();
  const { tenantId } = req.params;
  if (!tenantIdToConnection[tenantId]) {
    tenantIdToConnection[tenantId] = mongoose.createConnection(`mongodb://127.0.0.1:27017/tenant_${tenantId}`);
    tenantIdToConnection[tenantId].model('User', mongoose.Schema({ name: String }));
    initialConnection = tenantIdToConnection[tenantId].asPromise();
  }
  const db = tenantIdToConnection[tenantId];
  initialConnection.
    then(() => db.model('User').find()).
    then(users => res.json({ users })).
    catch(err => res.status(500).json({ message: err.message }));
});

app.listen(3000);

下一步

现在我们已经介绍了连接，让我们看一下 models。