创建客户端

运用 Mongo::Client

要连接到 MongoDB 部署，请创建一个Mongo::Client对象。 向“Mongo::Client”构造函数提供主机和选项列表或 连接string URI 。 客户端选择的数据库默认为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身份验证机制一起使用。

连接类型

默认情况下，驱动程序将发现指示其连接到的部署类型（负载均衡部署除外），并以与部署类型匹配的方式运行。 以下小节介绍了驱动程序在每种部署类型中的行为方式，以及如何绕过自动部署类型检测，强制执行特定行为。

请注意，当驱动程序收到来自指示其连接的任何服务器的第一个回复时，就会检测到部署类型（除非请求了负载均衡模式，请参阅下文）。 即使底层部署被替换为其他类型的部署，驱动程序仍将保留在已发现或已配置的拓扑结构中。In particular, when replacing a replica set with a sharded cluster at the same address the client instance must be recreated (such as by restarting the application) for it to communicate with the sharded cluster.

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

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 查找分开的单独 DNS 查询中检索的，因此在网络连接不可靠的环境中，当 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 个探测器

要使用较低的值，或在 JRuby 等不公开所需 API 的环境中更改参数，请按照 MongoDB诊断常见问题解答keepalive 部分 中的描述在系统级别调整参数 。

连接池化

Mongo::Client 实例在客户端连接的每个服务器上都有一个连接池。 该连接池按需创建连接，以支持应用程序发出的并发 MongoDB 操作。 连接没有线程关联性。

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

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

每个池对可以同时连接到服务器的连接数有限制。 此限制称为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 个监控连接）。 如果应用程序使用读取偏好（read preference）来查询从节点，则它们的池也会增长，并且总连接可以达到 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 )，如果您在分叉后没有在子进程上重新启动驱动程序的监控线程，尽管您的子进程最初可能会正常运行，但如果/当您的MongoDB 集群状态发生变化时，您最终会看到Mongo::Error::NoServerAvailable异常，示例，由于网络错误或维护事件。

关于 ( 2 )，如果子进程重复使用父进程的文件描述符，您将看到Mongo::Error::SocketError错误，并附带Errno::EPIPE: Broken pipe和EOFError: end of file reached等消息。

在 Web应用程序程序中使用Ruby驾驶员程序时，如果可能，我们建议不要在父进程中创建任何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 开始，旧版使用现代机制，并且默认已弃用。

可重试写入 (Retryable Writes)

驱动程序实现两种重试写入的机制：现代和传统。 从驱动程序版本 2.9.0 开始，支持它的服务器默认使用现代机制，而旧版机制在所有服务器版本上均已弃用并默认禁用。

在对collection的日常操作中使用的以下写入方法会进行写入重试：

• 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记录器文档 有关默认记录器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 )

压缩

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

驱动程序会选择服务器也支持的所请求压缩程序中的第一个压缩程序。 该驱动程序当前支持zstd 、 snappy和zlib压缩器。 建议使用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 版本运行。

可以通过Client的:server_api选项指定服务器 API 参数。 这些参数无法通过 URI 提供。

目前唯一定义的 API 版本是"1" 。 可以通过以下方式请求：

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

MongoDB Server 将 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"中没有任何已弃用的操作。

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

5.0 之前的 MongoDB Server 无法识别 API 参数，如果应用程序配置这些参数，则会产生各种错误。Ruby 驱动程序会将 API 参数发送到所有 MongoDB 3.6 及更高版本的服务器，但仅当应用程序与 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 参数只能在客户端级别指定。 不得在数据库、collection、会话、事务或单个操作级别上指定它们。

开发配置

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

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

生产配置

在生产中使用 Ruby 驱动程序部署应用程序时，请考虑以下因素：

• 从驱动程序版本 2.11 开始，完全遵循:min_pool_size客户端选项 — 驱动程序将与标识为独立运行的主节点或从节点的每台服务器创建相同数量的连接。 在以前的驱动程序版本中，驱动程序按需创建连接。 从驱动程序版本 2.11 开始，使用:min_pool_size的应用程序会发现与所有服务器的空闲连接数量增加，尤其是与副本集部署中的从节点和分片集群中的节点的空闲连接。

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

功能标志

以下是 Mongo Ruby 驱动程序提供的功能标志列表：

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

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