创建客户端

使用Mongo::Client

要连接到 MongoDB 部署，创建一个 Mongo::Client 对象。提供主机列表和选项或一个连接字符串 URI 给``Mongo::Client``构造函数。客户端选择的数据库名默认为 admin。

默认情况下，驱动程序将自动检测部署使用的拓扑结构并相应地连接。

要连接到本地独立 MongoDB 部署，指定服务器的地址和端口号。在大多数情况下，您还需要指定要连接的数据库名；如果没有指定数据库名，则客户端将使用 admin 数据库

Mongo::Client.new([ '127.0.0.1:27017' ], database: 'mydb')
# Or using the URI syntax:
Mongo::Client.new("mongodb://127.0.0.1:27017/mydb")

要 连接到 MongoDB Atlas，指定 Atlas 部署 URI

Mongo::Client.new("mongodb+srv://username:myRealPassword@cluster0.mongodb.net/mydb?w=majority")

驱动程序将发现集群中的所有节点并根据需要连接到它们。

Mongo::Client.new(...) do |client|
  # work with the client
end

数据库选择

默认情况下，客户端将连接到admin数据库。

admin数据库是MongoDB中的一个特殊数据库，通常用于管理任务和存储用户和角色等管理数据（尽管用户和角色也可以在其他数据库中定义）。在分片集群中，admin数据库存在于配置服务器上，而不是分片服务器上。虽然可以使用admin数据库进行常规操作（如存储应用程序数据），但这样做并不推荐，应用程序应明确指定其希望使用的数据库。

可以在构建Client时指定数据库

# Using Ruby client options:
client = Mongo::Client.new(['localhost'], database: 'mydb')
# Using a MongoDB URI:
client = Mongo::Client.new('mongodb://localhost/mydb')

给定一个Client实例，可以通过调用use方法来获取一个配置了指定数据库的新Client实例

client = Mongo::Client.new(['localhost'], database: 'mydb')
admin_client = client.use('admin')
# Issue an administrative command
admin_client.database.command(replSetGetConfig: 1).documents.first

MongoDB中还有其他特殊数据库，只能用于其声明的目的

• 配置数据库。

• 本地数据库。

• 用于与$external数据库配合使用的PLAIN、Kerberos和X.509认证机制。

连接类型

默认情况下，驱动程序将自动识别它被指示连接到的部署类型（除了负载均衡部署）并以与部署类型相匹配的方式行为。以下小节将描述驱动程序在每种部署类型中的行为以及如何强制特定行为，从而绕过自动部署类型检测。

请注意，部署类型的检测发生在驱动程序收到它被指示连接到的任何服务器首次回复时（除非请求负载均衡模式，见下文）。即使底层部署被不同类型的部署所替换，驱动程序也将保持发现的或配置的拓扑。特别是，当在同一地址用分片集群替换副本集时，客户端实例必须被重新创建（例如通过重启应用程序），以便与分片集群通信。

目前不支持自动检测负载均衡部署。负载均衡部署将被视为其底层类型的部署，这通常是分片集群。当将负载均衡部署视为分片集群时，驱动程序将无法正确运行，因此当部署是负载均衡时，客户端必须显式配置为连接到负载均衡器。

Mongo::Client.new([ '127.0.0.1:27017' ], database: 'mydb')
Mongo::Client.new([ '127.0.0.1:27017', '127.0.0.1:27018' ], database: 'mydb')
# Or using the URI syntax:
Mongo::Client.new("mongodb://127.0.0.1:27017,127.0.0.1:27018/mydb")

Mongo::Client.new([ '127.0.0.1:27017', '127.0.0.1:27018' ],
  database: 'mydb', replica_set: 'myapp')
# Or using the URI syntax:
Mongo::Client.new("mongodb://127.0.0.1:27017,127.0.0.1:27018/mydb?replicaSet=myapp")

Mongo::Client.new([ '127.0.0.1:27017', '127.0.0.1:27018' ],
  database: 'mydb', connect: :replica_set)
# Or using the URI syntax:
Mongo::Client.new("mongodb://127.0.0.1:27017,127.0.0.1:27018/mydb?connect=replica_set")

Mongo::Client.new("mongodb+srv://username:myRealPassword@cluster0.mongodb.net/test?w=majority")

Mongo::Client.new([ '1.2.3.4:27017', '1.2.3.5:27017' ], database: 'mydb')
Mongo::Client.new("mongodb://1.2.3.4:27017,1.2.3.5:27017/mydb")

Mongo::Client.new("mongodb+srv://username:myRealPassword@cluster0.mongodb.net/test?w=majority")

Mongo::Client.new([ '127.0.0.1:27017', '127.0.0.1:27018' ],
  database: 'mydb', connect: :sharded)
# Or using the URI syntax:
Mongo::Client.new("mongodb://127.0.0.1:27017,127.0.0.1:27018/mydb?connect=sharded")

Mongo::Client.new([ '1.2.3.4:27017' ], database: 'mydb', direct_connection: true)
# Or using the URI syntax:
Mongo::Client.new("mongodb://1.2.3.4:27017/mydb?directConnection=true")

Mongo::Client.new([ '1.2.3.4:27017' ], database: 'mydb', connect: :direct)
# Or using the URI syntax:
Mongo::Client.new("mongodb://1.2.3.4:27017/mydb?connect=direct")

Mongo::Client.new([ '1.2.3.4:27017' ], database: 'mydb', load_balanced: true)
# Or using the URI syntax:
Mongo::Client.new("mongodb://1.2.3.4:27017/mydb?loadBalanced=true")

Mongo::Client.new([ '1.2.3.4:27017' ],
  database: 'mydb', load_balanced: true, connect: :load_balanced)
# Or using the URI syntax:
Mongo::Client.new("mongodb://1.2.3.4:27017/mydb?loadBalanced=true&connect=load_balanced")

require 'mongo'
# Replace the placeholders with your credentials
uri = "mongodb+srv://<username>:<password>@cluster0.sample.mongodb.net/?retryWrites=true&w=majority"
# Set the server_api field of the options object to Stable API version 1
options = { server_api: { version: "1" } }
# Create a new client and connect to the server
client = Mongo::Client.new(uri, options)
# Send a ping to confirm a successful connection
begin
  admin_client = client.use('admin')
  result = admin_client.database.command(ping: 1).documents.first
  puts "Pinged your deployment. You successfully connected to MongoDB!"
rescue Mongo::Error::OperationFailure => ex
  puts ex
ensure
  client.close
end

SRV URI 说明

当驱动程序连接到 mongodb+srv 协议 URI 时，请注意以下几点

1. 当客户端构建时，SRV URI 查找是同步进行的。如果由于任何原因查找失败，客户端构建将因异常而失败。当使用主机列表构建客户端时，驱动程序将尝试联系并监控这些主机，直到客户端对象存在为止。如果这些主机中的一个最初无法解析但在之后变得可解析，当它变得可用时，驱动程序将能够建立到该主机的连接。初始 SRV URI 查找必须在第一次尝试中成功；后续的主机查找将由驱动程序根据需要重试。

2. 驱动程序在对应 SRV 记录的 DNS TXT 记录中查找 URI 选项。这些选项可以按照顺序由 URI 中指定的 URI 选项和 Ruby 选项覆盖。

3. 由于 URI 选项是从 SRV 查找中单独检索的，在网络连接不可靠的环境中，当 SRV 查找成功时，URI 选项查询可能会失败。此类失败会导致驱动程序使用错误的认证源，从而导致认证失败。可以通过明确指定认证源来解决此问题。

   Mongo::Client.new("mongodb+srv://username:myRealPassword@cluster0.mongodb.net/test?w=majority&authSource=admin")

4. 如果构建的 Client 对象的拓扑结构未知或为分片集群，驱动程序将开始监控指定的 SRV DNS 记录以查找更改，并将自动更新集群中的服务器列表。当拓扑结构变为单个或副本集时，更新将停止。

客户端选项

Mongo::Client 构造函数接受配置驱动程序行为的多个选项。这些选项可以作为 Ruby 选项在选项哈希中提供，作为 URI 选项在 URI 中提供，或两者兼而有之。如果提供了 Ruby 选项和相应的 URI 选项，则 Ruby 选项优先。

{ read:
  { mode: :secondary,
    tag_sets: [ "data_center" => "berlin" ],
    max_staleness: 5,
  }
}

{ write_concern: { w: 2 } }

超时选项

TLS连接

使用TLS连接到MongoDB部署

• 在Mongo::Client中启用TLS连接。

• 指定客户端TLS证书。

• 指定CA证书以验证服务器的TLS证书。

client = Mongo::Client.new(["localhost:27017"],
  ssl: true,
  ssl_cert: 'path/to/client.crt',
  ssl_key: 'path/to/client.key',
  ssl_ca_cert: 'path/to/ca.crt',
)

client = Mongo::Client.new(["localhost:27017"],
  ssl: true,
  ssl_cert: 'path/to/client.pem',
  ssl_key: 'path/to/client.pem',
  ssl_ca_cert: 'path/to/ca.crt',
)

client = Mongo::Client.new(
  "mongodb://localhost:27017/?tls=true&tlsCertificateKeyFile=path%2fto%2fclient.pem&tlsCertificateKeyFile=path%2fto%2fca.crt")

Mongo.tls_context_hooks.push(
  Proc.new { |context|
    context.ciphers = ["AES256-SHA"]
  }
)
# Only the AES256-SHA cipher will be enabled from this point forward

IPv4/IPv6 连接

当客户端以 localhost 作为主机名构建时，它将仅尝试 IPv4 连接（即如果 localhost 解析为 127.0.0.1 和 ::1，则驱动程序将仅尝试连接到 127.0.0.1）。

当客户端以除 localhost 之外的主机名构建时，它将尝试 IPv4 和 IPv6 连接，具体取决于主机名解析到的地址。驱动程序尊重 getaddrinfo 返回地址的顺序，并将依次尝试连接到它们。第一个成功连接将被使用。

驱动程序目前未实现 Happy Eyeballs 算法。

TCP Keepalive 配置

在系统配置和 Ruby 语言运行时允许的情况下，驱动程序启用 TCP keepalive，并为以下每个 keepalive 参数，如果系统值可以确定并且高于列出的驱动程序值，则将相应参数的值设置为指定的值

• tcp_keepalive_time: 120 秒

• tcp_keepalive_intvl: 10 秒

• tcp_keepalive_cnt: 9 次探测

要使用较小的值，或者更改不公开所需API的环境（如JRuby）中的参数，请按照以下方式在系统级别调整参数：MongoDB诊断FAQ中的keepalive部分。

连接池

Mongo::Client实例为每个客户端连接的服务器有一个连接池。该池在需要时创建连接以支持由应用程序发出的并发MongoDB操作。连接没有线程亲和性。

客户端实例为每个已知服务器额外打开一个连接以监控服务器状态。

每个连接池的大小限制为max_pool_size，默认为5。当应用程序中的线程开始对MongoDB进行操作时，它会尝试从池中检索一个连接来发送该操作。如果池中有些连接可用，它将从池中借出一个连接并用于该操作。如果没有可用的连接，并且池的大小小于max_pool_size，将创建一个新的连接。如果所有连接都在使用中，并且池已达到最大大小，线程将等待另一个线程将连接返回到池中。如果将max_pool_size设置为0，则池中最大连接数没有限制。

每个连接池对可以同时连接到服务器的连接数有限制。这个限制被称为 max_connecting，默认值为2。如果当前连接到服务器的连接数达到这个限制，连接池将等待一个连接尝试成功或失败后再尝试创建新的连接。如果你的应用程序有大量线程，你可能想要增加 max_connecting 的值，以避免线程等待建立连接。

线程等待连接变得可用的秒数是可以配置的。这个设置称为 wait_queue_timeout，以秒为单位。如果这个超时时间到达，将引发一个 Timeout::Error。默认值为1秒。

从驱动程序版本2.11开始，驱动程序会积极地创建到 min_pool_size 设置的连接。在驱动程序版本2.11之前，驱动程序总是根据需要创建连接。在所有版本的驱动程序中，一旦建立连接，只要连接池大小不超过 min_pool_size，驱动程序就会将其保留在池中。

请注意，如果将 min_pool_size 设置为一个大于零的值，驱动程序将在副本集部署中为辅助节点建立那么多连接，即使应用程序没有执行辅助读取。这些连接的目的是在主节点改变时提供更快的故障转移。

以下是一个估计多线程应用程序将打开的连接数的示例：连接到3节点副本集的客户端打开3个监控套接字。它还打开所需数量的套接字以支持每个服务器上多线程应用程序的并发操作，最多可达 max_pool_size。如果应用程序仅使用主节点（默认），则只有主节点连接池会增长，总连接数最多为8（主节点池中的5个连接 + 3个监控连接）。如果应用程序使用读取偏好查询辅助节点，它们的池也会增长，总连接数可以达到18（5 + 5 + 5 + 3）。

大多数应用程序的默认配置对 Mongo::Client 是有效的

client = Mongo::Client.new(["localhost:27017"])

为每个进程 只创建一次 此客户端，并对其所有操作进行重用。为每个请求创建一个新的客户端是一个常见的错误，这非常低效，也不是客户端设计的目的。

为了在一个进程中支持极高的并发 MongoDB 操作数量，增加 max_pool_size

client = Mongo::Client.new(["localhost:27017"], max_pool_size: 200)

为了在一个进程中支持极高数量的共享同一客户端的线程，增加 max_connecting

client = Mongo::Client.new(["localhost:27017"], max_pool_size: 200, max_connecting: 10)

任何数量的线程都可以等待连接变得可用，并且它们可以等待默认值（1秒）或 wait_queue_timeout 设置

client = Mongo::Client.new(["localhost:27017"], wait_queue_timeout: 0.5)

当任何线程调用客户端上的 #close 时，所有连接都将关闭

client.close

请注意，当使用上述描述的 块语法 创建客户端时，客户端会在块执行完毕后自动关闭。

使用分叉服务器

当在具有分叉 Web 服务器（如 Puma）的 Web 应用程序中使用 Mongo Ruby 驱动程序，或者当应用程序在其他情况下分叉时，每个进程（父进程和子进程）必须有自己的客户端连接。这是因为

1. 后台 Ruby 线程（例如，Ruby MongoDB 驱动程序用于监控连接状态的线程）不会转移到子进程。

2. 文件描述符（如网络套接字）在父进程和子进程之间是共享的，这可能导致 I/O 冲突。

关于（1），如果您在分叉后不在子进程中重新启动驱动程序的监控线程，尽管您的子进程最初可能看起来可以正常工作，但您最终会看到 Mongo::Error::NoServerAvailable 异常，如果/当您的 MongoDB 集群状态改变时，例如由于网络错误或维护事件。

关于（2），如果一个子进程重用了父进程的文件描述符，您将看到带有类似 Errno::EPIPE: 管道已损坏 和 EOFError: 文件末尾已到达 等消息的 Mongo::Error::SocketError 错误。

当 Ruby 驱动程序在 Web 应用程序中使用时，如果可能，我们建议不要在父进程中创建任何 Mongo::Client 实例（在工作者被分叉之前），而是在工作者中仅创建客户端实例。

# Immediately before fork
client.close

# Immediately after fork
client.reconnect

client.summary
=> "#<Client cluster=#<Cluster
  topology=ReplicaSetWithPrimary[localhost:14420,localhost:14421,localhost:14422,localhost:14423,name=ruby-driver-rs,v=1,e=7fffffff000000000000001f]
  servers=[#<Server address=localhost:14420 PRIMARY replica_set=ruby-driver-rs pool=#<ConnectionPool size=0 (0-5) used=0 avail=0 pending=0>>,
    #<Server address=localhost:14421 SECONDARY replica_set=ruby-driver-rs pool=#<ConnectionPool size=0 (0-5) used=0 avail=0 pending=0>>,
    #<Server address=localhost:14422 SECONDARY replica_set=ruby-driver-rs pool=#<ConnectionPool size=0 (0-5) used=0 avail=0 pending=0>>,
    #<Server address=localhost:14423 ARBITER replica_set=ruby-driver-rs>]>>"

client.summary
=> "#<Client cluster=#<Cluster
  topology=ReplicaSetWithPrimary[localhost:14420,localhost:14421,localhost:14422,localhost:14423,name=ruby-driver-rs,v=1,e=7fffffff000000000000001f]
  servers=[#<Server address=localhost:14420 PRIMARY replica_set=ruby-driver-rs NO-MONITORING pool=#<ConnectionPool size=0 (0-5) used=0 avail=0 pending=0>>,
    #<Server address=localhost:14421 SECONDARY replica_set=ruby-driver-rs NO-MONITORING pool=#<ConnectionPool size=0 (0-5) used=0 avail=0 pending=0>>,
    #<Server address=localhost:14422 SECONDARY replica_set=ruby-driver-rs NO-MONITORING pool=#<ConnectionPool size=0 (0-5) used=0 avail=0 pending=0>>,
    #<Server address=localhost:14423 ARBITER replica_set=ruby-driver-rs>]>>"

可重试读取

驱动程序实现了两种重试读取的机制：现代和传统。截至驱动程序版本2.9.0，默认使用现代机制，传统机制已弃用。

可重试写入

驱动程序实现了两种写入重试机制：现代和传统。截至驱动程序版本 2.9.0，对支持的服务器默认使用现代机制，而传统机制已弃用并在所有服务器版本中默认禁用。

以下在集合的日常操作中使用的写入方法会受到写入重试的影响：

• collection#insert_one

• collection#update_one

• collection#delete_one

• collection#replace_one

• collection#find_one_and_update

• collection#find_one_and_replace

• collection#find_one_and_delete

• collection#bulk_write（适用于所有单个语句操作，即不适用于update_many或delete_many）

日志记录

您可以使用默认的全局驱动程序日志记录器或设置自己的。要设置自己的

Mongo::Logger.logger = other_logger

请参阅Ruby Logger 文档以获取有关默认日志记录器 API 和可用级别的更多信息。

Mongo::Logger.logger.level = Logger::WARN

my_logger = Logger.new(STDOUT)
Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test', :logger => my_logger )

Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test', :truncate_logs => false )

压缩

要使用线协议压缩，必须明确请求至少一个压缩器，使用Ruby选项中的:compressors或URI选项中的compressors。如果没有明确请求压缩器，即使系统上存在一个或多个压缩器的必需依赖项，驱动程序也不会使用压缩。

驱动程序选择请求的压缩器列表中第一个同时由服务器支持的压缩器。驱动程序目前支持zstd、snappy和zlib压缩器。《code class="leafygreen-ui-1l06pbn">zstd压缩器推荐使用，因为它在相同CPU消耗的情况下产生最高的压缩率。为了实现与服务器最大的兼容性，可以指定所有三个压缩器，例如compressors: ["zstd", "snappy", "zlib"]。

zstd 压缩器需要安装 zstd-ruby 库。 snappy 压缩器需要安装 snappy 库。如果请求 zstd 或 snappy 压缩，并且相应的库不可加载，则在创建 Mongo::Client 时驱动程序将引发错误。zlib 压缩需要存在 zlib 标准库扩展。

服务器对各种压缩器的支持如下

• zstd 需要 MongoDB 4.2 或更高版本，并且默认启用。

• snappy 需要 MongoDB 3.4 或更高版本，并且在 MongoDB 3.6 或更高版本中默认启用。

• zlib 需要 MongoDB 3.6 或更高版本，并且在 MongoDB 4.2 和更高版本中默认启用。

服务器 API 参数

从 MongoDB 5.0 开始，应用程序可以请求服务器按照特定的服务器 API 版本运行。

可以通过 :server_api 选项将服务器 API 参数指定给 Client。这些参数不能通过 URI 提供。

当前定义的唯一API版本是"1"。可以按照以下方式请求

client = Mongo::Client.new(['localhost'], server_api: {version: "1"})

MongoDB服务器将API版本定义为字符串值。为了方便，如果API版本以整数形式提供，Ruby驱动程序将将其转换为字符串并发送到服务器

client = Mongo::Client.new(['localhost'], server_api: {version: 1})

请注意，服务器可能定义未转换为字符串整数的API版本。应用程序不应假设所有合法的API版本都可以表示为整数。

当请求特定的API版本时，该API版本中的操作将按该API版本中指定的方式执行。不属于指定API版本的操作将像没有指定API版本一样执行。受配置的API版本影响的行为包括命令及其参数、查询、聚合管道阶段和参数。

应用程序可以通过设置:strict选项来请求服务器拒绝所有不属于指定API版本的操作

client = Mongo::Client.new(['localhost'], server_api: {version: "1", strict: true})

例如，由于:tailable选项不属于服务器API版本1，以下查询将失败

client = Mongo::Client.new(['localhost'], server_api: {version: "1", strict: true})
client['collection'].find({}, tailable: true)
# => Mongo::Error::OperationFailure (BSON field 'FindCommand.tailable' is not allowed with apiStrict:true. (323) (on localhost:27017, modern retry, attempt 1))

应用程序可以通过设置:deprecation_errors选项来请求服务器拒绝所有在指定API版本中已弃用的操作

client = Mongo::Client.new(['localhost'], server_api: {version: "1", deprecation_errors: true})

请注意，截至本文写作时，API版本"1"中没有弃用的操作。

如果服务器API参数已在Client对象上定义，它们将被客户端作为每个[1]执行的操作的一部分发送。

5.0之前的MongoDB服务器不识别API参数，如果应用程序配置了它们，将产生各种错误。Ruby驱动程序将向所有MongoDB 3.6及更高版本的服务器发送API参数，但只有在应用程序与MongoDB 5.0或更高版本的服务器通信时才应配置API参数。API参数不能发送到使用旧式线协议的MongoDB 3.4及更低版本的服务器；如果应用程序配置了API参数并连接到MongoDB 3.4或更低版本的服务器，驱动程序将在每次操作中产生错误。

命令助手允许应用程序将手动构造的命令发送到服务器。如果客户端未配置服务器API参数，则可以使用命令助手发出具有API参数的命令

client.database.command(
  ping: 1,
  apiVersion: "1",
  apiStrict: false,
  apiDeprecationErrors: false,
)

如果客户端配置了服务器API参数，则不能使用命令助手发出带有服务器API参数的命令。这包括当客户端和命令助手收到的服务器API参数相同的情况。如果使用服务器API参数构建了客户端，要发送不同的API参数（或根本不发送）必须构造一个新的客户端，可以从头开始或使用with方法。

服务器API参数只能在客户端级别指定。它们不能在数据库、集合、会话、事务或单个操作级别指定。

开发配置

驱动程序的默认配置适用于生产部署。在开发过程中，可以调整一些设置以提供更好的开发者体验。

• :server_selection_timeout：如果您的MongoDB服务器在本地运行且您手动启动它，请将此设置为较低值（例如，1）。较短的连接超时会导致服务器未运行时驱动程序快速失败。

生产配置

在生产环境中使用Ruby驱动程序部署应用程序时，请考虑以下几点：

• 从驱动程序版本2.11开始，客户端选项:min_pool_size被完全尊重 - 驱动程序将为每个标识为独立、主或次服务器的服务器创建这么多连接。在之前的驱动程序版本中，驱动程序按需创建连接。使用:min_pool_size的应用程序将在驱动程序版本2.11及更高版本中看到所有服务器上的空闲连接数量增加，尤其是在副本集部署中的次级和分片集群中的节点。

• 如果应用程序由另一个Web服务器或负载均衡器反向代理，则通常应将 server_selection_timeout 设置为比反向代理的读取超时更低的值。例如，Heroku请求超时 为30秒且不可配置；如果使用MongoDB在Heroku上部署Ruby应用程序，请考虑将服务器选择超时降低到20或15秒。

功能标志

以下是由Mongo Ruby Driver提供的功能标志列表

这些功能标志可以直接在 Mongo 模块上设置或使用 options 方法

Mongo.validate_update_replace = true
Mongo.options = { validate_update_replace: true }