类：Mongo::Client

继承：
对象
  • 对象
显示全部
扩展方式：
可转发
包括：
Loggable
定义于：
lib/ Mongo/ 客户端.rb

Overview

客户端是驱动程序的入口点，也是与之交互的主要对象。

由于：

  • 2.0.0

常量摘要折叠

CRUD_OPTIONS =

不影响集群及其子组件行为的选项。

由于：

  • 2.1.0

[
  :auto_encryption_options,
  :database,
  :read, :read_concern,
  :write, :write_concern,
  :retry_reads, :max_read_retries, :read_retry_interval,
  :retry_writes, :max_write_retries,

  # 当前不能出现在此处的选项：
  #
  # :server_selection_timeout
  # 集群构造函数使用MongoDB Server选择超时来确定
  # 在兼容模式下等待初始扫描的时间，但一次
  # 集群已初始化，不再使用此超时。
  # 不幸的是，服务器选择器读取服务器选择超时
  # 集群，此行为是 Cluster#next_primary 所要求的
  # 不带参数。 当 next_primary 被删除时，我们可以重新访问
  # 使用具有不同服务器选择超时的相同集群对象。
].冻结
VALID_OPTIONS =

有效的客户端选项。

由于：

  • 2.1.2

[
  :app_name,
  :auth_mech,
  :auth_mech_properties,
  :auth_source,
  :auto_encryption_options,
  :bg_error_backtrace,
  :cleanup,
  :compressors,
  :direct_connection,
  :connect,
  :connect_timeout,
  :database,
  :heartbeat_Frequency,
  :id_generator,
  :load_balanced,
  :local_threshold,
  :logger,
  :log_prefix,
  :max_connecting,
  :max_idle_time,
  :max_pool_size,
  :max_read_retries,
  :max_write_retries,
  :min_pool_size,
  :monitoring,
  :monitoring_io,
  :password,
  :platform,
  :populator_io,
  :read,
  :read_concern,
  :read_retry_interval,
  :replica_set,
  :resolv_options,
  :retry_reads,
  :retry_writes,
  :scan,
  :sdam_proc,
  :server_api,
  :server_selection_timeout,
  :socket_timeout,
  :srv_max_hosts,
  :srv_service_name,
  :ssl,
  :ssl_ca_cert,
  :ssl_ca_cert_object,
  :ssl_ca_cert_string,
  :ssl_cert,
  :ssl_cert_object,
  :ssl_cert_string,
  :ssl_key,
  :ssl_key_object,
  :ssl_key_pass_phrase,
  :ssl_key_string,
  :ssl_verify,
  :ssl_verify_certificate,
  :ssl_verify_hostname,
  :ssl_verify_ocsp_endpoint,
  :timeout_ms,
  :truncate_logs,
  : user,
  :wait_queue_timeout,
  :wrapping_libraries,
  :write,
  :write_concern,
  :zlib_compression_level,
].冻结
VALID_COMPRESSORS =

驱动程序支持的压缩算法。

由于：

  • 2.5.0

[
  mongo::protocol::压缩::zstd,
  mongo::protocol::压缩::snappy,
  mongo::protocol::压缩::zlib
].冻结
VALID_SERVER_API_VERSIONS =

已知的服务器 API 版本。

由于：

  • 2.0.0

%w(
  1
).冻结

Loggable中包含的常量

Loggable::PREFIX

实例属性摘要折叠

类方法摘要折叠

实例方法摘要折叠

Loggable中包含的方法

#log_debug 、 #log_error 、 #log_ Fatal 、 #log_info 、 #log_warn 、 #logger

构造函数详情

#initialize (addresses_or_uri, options = nil) ⇒客户端

实例化一个新的驱动程序客户端。

例子：

实例化单个服务器或 mongos 客户端。

Mongo::Client.new(['127.0.0.1:27017'])

实例化副本集的客户端。

Mongo::Client.new(['127.0.0.1:27017', '127.0.0.1:27021'])

直接连接到副本集中的 mongod

Mongo::Client.new(['127.0.0.1:27017'], :connect => :direct)
# without `:connect => :direct`, Mongo::Client will discover and
# connect to the replica set if given the address of a server in
# a replica set

参数：

  • Addresses_or_uri ( Array< string > | string ) —

    主机:端口 或MongoDB URI 连接string形式的服务器地址数组。

  • 选项 （哈希） （默认为： nil ） —

    客户端要使用的选项。 如果还提供了MongoDB URI 连接string ，则这些选项优先于 URI string中存在的任何类似选项。

选项哈希 ( options )：

  • :app_name （ string ，符号） —

    在服务器版本 >= 3.4 中建立连接时打印到 mongod 日志的应用程序名称。

  • :auth_mech （符号） —

    要使用的身份验证机制。 :mongodb_cr、:mongodb_x 509 、:plain、:scram、:scram 256之一

  • :auth_mech_properties （哈希）
  • :auth_source （ string ） —

    要从中进行身份验证的来源。

  • :bg_error_backtrace ( true | false | nil | Integer ) —

    实验性的。 设置为 true 可记录后台线程中错误的完整回溯。 设置为 false 或 nil 可不记录回溯。 提供一个正整数以记录最多那么多的回溯行。

  • :compressors ( Array<String> ) —

    要使用的潜在压缩器列表（按优先顺序排列）。 驱动程序会选择服务器也支持的第一个压缩程序。 目前该驱动程序仅支持“zstd”、“snappy”和“zlib”。

  • :direct_connection ( true | false ) —

    是否绕过拓扑发现，直接连接到指定的种子。 必须提供一个种子。

  • :connect （符号） —

    已弃用 - 使用 :direct_connection 选项代替此选项。 要使用的连接方法。 这会强制集群按照指定方式运行，而不是自动发现。 :direct、:replica_set、:sharded、:load_balanced 之一。 如果 :connect 设置为 :load_balanced，则即使服务器未连接到负载均衡器，驱动程序也会将其视为负载均衡器。

  • :connect_timeout （浮点） —

    尝试连接的超时时间（以秒为单位）。

  • :database （ string ） —

    要连接到的数据库。

  • :heartbeat_Frequency （浮点） —

    服务器监视器通过 hello 刷新其描述的时间间隔（以秒为单位）。

  • :id_generator （对象） —

    用于生成文档 ID 的自定义对象。 必须响应#generate。

  • :load_balanced ( true | false ) —

    是否期望连接到负载均衡器。

  • :local_threshold （整数） —

    为操作选择邻近服务器的本地阈值边界（以秒为单位）。

  • :logger （记录器） —

    要使用的自定义记录器。

  • :log_prefix （ string ） —

    记录日志时使用的自定义日志前缀。 此选项是实验性的，在驾驶员的未来版本中可能会发生变化。

  • :max_connecting （整数） —

    可以同时连接的最大连接数。 默认值为 2。 如果有许多线程股票同一客户端，并且应用程序在等待建立连接时遇到超时，则应增加此选项。 为操作选择服务器。 默认值为 2。

  • :max_idle_time （整数） —

    套接字自签入池以来可以保持空闲状态的最大秒数。

  • :max_pool_size （整数） —

    连接池的最大大小。 将此选项设置为零会创建一个无限制的连接池。

  • :max_read_retries （整数） —

    使用传统读取重试时的最大读取重试次数。

  • :max_write_retries （整数） —

    使用传统写入重试时的最大写入重试次数。

  • :min_pool_size （整数） —

    连接池的最小大小。

  • :monitoring ( true , false ) —

    如果为 false，则客户端在没有全局 SDAM 事件订阅者的情况下进行初始化，并且不会发布 SDAM 事件。 命令监控和传统事件仍将发布，驱动程序仍将执行 SDAM 并监控其集群，以便执行服务器选择。 SDAM 事件的内置驱动程序日志记录将被禁用，因为它是通过 SDAM 事件订阅实现的。 对于所有事件类型，Client#subscribe 都会成功，但不会调用 SDAM 事件的订阅者。 false 以外的值会导致默认行为，即执行正常的 SDAM 事件发布。

  • :monitoring_io ( true , false ) —

    仅供内部驱动程序使用。 设置为 false 可防止此客户端或其下的服务器执行与 SDAM 相关的 I/O。 注意：将此选项设置为 false 将使客户端无法运行。 它适用于手动调用 SDAM 状态转换的测试。

  • :cleanup ( true | false ) —

    仅供内部驱动程序使用。 设置为 false 可防止在集群断开连接时向服务器发送 endSessions 命令以清理服务器会话，并且不启动定期执行程序。 如果 :monitoring_io 为 false，则 :cleanup 也会自动默认为 false。

  • :password （ string ） —

    用户的密码。

  • :platform （ string ） —

    在服务器版本 >= 3.4 中建立连接时打印到 mongod 日志的元数据中包含的平台信息。

  • :read （哈希） —

    读取偏好选项。 哈希可能包含以下项目：

    • ：模式—读取偏好（read preference），指定为符号；有效值为： 主节点 (primary node in the replica set) 、 :primary_preferred 、 : secondary_preferred和:nearest 。

    • :tag_sets – 哈希数组。

    • :local_threshold 。

  • :read_concern （哈希） —

    读关注选项。

  • :read_retry_interval （浮点） —

    重试读取 mongos 的时间间隔（以秒为单位）。

  • :replica_set （符号） —

    要连接到的副本集的名称。 不在该副本集中的服务器将被忽略。

  • :retry_reads ( true | false ) —

    如果为 true，则启用现代可重试读取（这是默认设置）。 如果为 false，则禁用新式可重试读取，启用传统可重试读取。

  • :retry_writes ( true | false ) —

    连接到副本集或分片集群版本3.6及更高版本时，重试写入一次。 （默认为 true。）

  • :scan ( true | false ) —

    是否在构造函数中扫描所有种子。 驱动程序版本2 .x 中的默认设置就是这样做；驱动程序版本3 .x 不会扫描构造函数中的种子。 将此选项设置为 false，选择接受新行为。 注意：将此选项设置为 nil 可以在驱动程序版本2 .x 的构造函数中扫描种子。 驱动程序版本3 .x 将识别此选项，但会忽略它，并且永远不会扫描构造函数中的种子。

  • :sdam_proc ( Proc ) —

    在执行服务器发现和监控之前，以客户端作为参数调用的 Proc。 使用它来设置 SDAM 事件侦听器，以接收在客户端构造期间发布的事件。

    注意：调用 sdam_proc 时，客户端尚未完全构建，特别是此时集群为 nil。 sdam_proc 应限制自身仅在客户端上调用 #subscribe 和 #unsubscribe 方法。

  • :server_api （哈希） —

    请求的服务器 API 版本。 此哈希可以包含以下项目：

    • :version – string

    • :strict – 布尔值

    • :deprecation_errors – 布尔值

  • :server_selection_timeout （整数） —

    为操作选择服务器的超时时间（以秒为单位）。

  • :socket_timeout （浮点） —

    在套接字上执行操作的超时时间（以秒为单位）。 此选项已弃用，请改用 :timeout_ms。

  • :srv_max_hosts （整数） —

    驾驶员在分片拓扑结构中与之通信的分片的的最大数量。 如果此选项为0 ，则没有最大 mongoses 数量限制。 如果给定的 URI 解析为主机数量超过“:srv_max_hosts“，客户端将随机选择“:srv_max_hosts“大小的主机子集。

  • :srv_service_name （ string ） —

    要在 SRV DNS 查询中使用的服务名称。

  • :ssl ( true , false ) —

    是否使用 TLS。

  • :ssl_ca_cert （ string ） —

    包含连接的证书颁发机构证书的文件，用于验证从连接另一端传递的证书。 不应在此选项引用的文件中指定中间证书。 使用 :ssl_verify 时，需要 :ssl_ca_cert、:ssl_ca_cert_string 或 :ssl_ca_cert_object（按优先级顺序）之一。

  • :ssl_ca_cert_object ( Array<OpenSSL::X 509 ::Certificate> ) —

    OpenSSL::X 509 ::Certificate 对象数组，表示证书颁发机构证书，用于验证从连接另一端传递的证书。 不应在此选项引用的文件中指定中间证书。 使用 :ssl_verify 时，需要 :ssl_ca_cert、:ssl_ca_cert_string 或 :ssl_ca_cert_object（按优先级顺序）之一。

  • :ssl_ca_cert_string （ string ） —

    包含证书颁发机构证书的string ，用于验证从连接另一端传递的证书。 此选项允许仅将一个 CA 证书传递给驱动程序。 不应在此选项引用的文件中指定中间证书。 使用 :ssl_verify 时，需要 :ssl_ca_cert、:ssl_ca_cert_string 或 :ssl_ca_cert_object（按优先级顺序）之一。

  • :ssl_cert （ string ） —

    用于识别针对 MongoDB 的连接的证书文件。 可以通过先指定客户端证书，然后指定直到 CA 证书的任何中间证书来传递证书链。 该文件还可能包含证书的私钥，但该私钥将被忽略。 此选项（如果存在）优先于 :ssl_cert_string 和 :ssl_cert_object 的值

  • :ssl_cert_object ( OpenSSL::X 509 ::Certificate ) —

    用于识别针对 MongoDB 的连接的 OpenSSL::X 509 ::Certificate。 通过此选项只能传递一个证书。

  • :ssl_cert_string （ string ） —

    包含 PEM 编码证书的string ，用于标识针对MongoDB的连接。 可以通过先指定客户端证书，然后指定直到 CA 证书的任何中间证书来传递证书链。 该string还可能包含证书的私钥，但该私钥将被忽略。此选项（如果存在）优先于 :ssl_cert_object 的值

  • :ssl_key （ string ） —

    用于识别针对 MongoDB 的连接的私钥文件。 请注意，即使密钥与证书存储在同一文件中，也需要显式指定两者。 此选项（如果存在）优先于 :ssl_key_string 和 :ssl_key_object 的值

  • :ssl_key_object ( OpenSSL::PKey ) —

    用于识别针对 MongoDB 的连接的私钥

  • :ssl_key_pass_phrase （ string ） —

    私钥的密码。

  • :ssl_key_string （ string ） —

    包含 PEM 编码私钥的string ，用于识别针对MongoDB的连接。 此参数（如果存在）优先于 :ssl_key_object 选项的值

  • :ssl_verify ( true , false ) —

    是否执行对等证书验证和主机名验证。 请注意，如果 :ssl_verify_certificate 已设置，则是否验证证书的决策将被覆盖；如果 :ssl_verify_hostname 已设置，则是否验证主机名的决策将被覆盖。

  • :ssl_verify_certificate ( true , false ) —

    是否执行对等证书验证。 在是否执行证书验证方面，此设置会覆盖 :ssl_verify。

  • :ssl_verify_hostname ( true , false ) —

    是否执行对等主机名验证。 在是否执行主机名验证方面，此设置会覆盖 :ssl_verify。

  • :timeout_ms （整数） —

    操作超时（以毫秒为单位）。 必须是非负整数。 0 的显式值表示无限。 未设置默认值，这意味着未启用该功能。

  • :truncate_logs ( true , false ) —

    是否按默认的 250 个字符截断日志。

  • : user （ string ） —

    用户名。

  • :wait_queue_timeout （浮点） —

    在连接池等待连接签入的时间（以秒为单位）。 此选项已弃用，请改用 :timeout_ms。

  • :wrapping_libraries ( Array<Hash> ) —

    有关封装驾驶员的 ODM 等库的信息，将添加到

    metadata sent to the server. Specify the lower level libraries first.
Allowed hash keys: :name, :version, :platform.
  • :write （哈希） —

    已弃用。 相当于 :write_concern 选项。

  • :write_concern （哈希） —

    写关注（write concern）选项。 可以是 :w => 整数|字符串、:wtimeout => 整数（以毫秒为单位，已弃用）、:j => 布尔值、: fsync => 布尔值。

  • :zlib_compression_level （整数） —

    如果使用压缩，则为要使用的zlib压缩级别。 有关有效级别，请参阅Ruby的zlib模块。

  • :resolv_options （哈希） —

    仅供内部驱动程序使用。 传递给 Resolv::DNS 构造函数以进行 SRV 查找的选项。

  • :auto_encryption_options （哈希） —

    自动加密相关选项。

    • :key_vault_client => 客户端 | nil，连接到包含加密密钥保管库的 MongoDB 实例的客户端

    • :key_vault_namespace => string ，密钥保管库的命名空间，格式为 database.collection

    • :kms_providers => 哈希， KMS ( KMS ) 配置信息的哈希。 有效的哈希键为 :aws、:azure、:gcp、:kmip、:local。 可能指定了多个KMS提供商。

    • :kms_tls_options => 哈希，用于向KMS提供商进行身份验证的 TLS 选项哈希，通常用于 KMIP 服务器。 有效的哈希键为 :aws、:azure、:gcp、:kmip、:local。 可能指定了多个KMS提供商。

    • :schema_map => 哈希 | nil，一个或多个集合的 JSONSchema，指定应加密哪些字段。 此选项与 :schema_map_path 互斥。

      • 注意：schema_map 中提供的模式仅适用于为客户端加密配置自动加密。 JSON schema中的其他验证规则不会由驱动程序执行，并会导致错误。

      • 注意：提供 schema_map 比依赖从服务器获取的JSON schema 更安全。 它可以防止恶意服务器公布虚假JSON schema，这种情况可能会诱骗客户端发送应加密的未加密数据。

      • 注意：如果 :encrypted_fields_map 和 :schema_map 上同时存在一个集合，则会引发错误。

    • :schema_map_path => string | nil 包含JSON schema的文件的路径

    存储自动加密文档的集合的名称。 此选项与 :schema_map 互斥。

    • :bypass_auto_encryption => 布尔值，为 true 时，禁用自动加密；默认为 false。

    • :extra_options => 哈希 | nil，与生成 mongocryptd 相关的选项（这部分 API 可能会有变更）。

    • :crypted_fields_map => 哈希 | nil，将集合命名空间映射到描述可查询加密的加密字段的Queryable Encryption 。

      • 注意：如果一个集合同时存在于encryptedFieldsMap 和schemaMap 上，则会引发错误。

    • :bypass_query_analysis => Boolean | nil，为 true 时会禁用对传出命令的自动分析。

    • :crypt_shared_lib_path => [ string | nil ] 用于加载 crypt 共享库的路径。 提供此选项会覆盖 libmongocrypt 的默认 crypt 共享库加载路径。

    • :crypt_shared_lib_required => [ Boolean | nil ] 是否需要 crypt 共享库。 如果为“true”，则当 libmongocrypt 无法加载 crypt_shared 库时，将引发错误。

    自动加密注意事项：

    • 自动加密是一项仅限企业使用的功能，仅适用于对集合进行的操作。

    • 对数据库或视图的操作不支持自动加密。

    • 自动加密要求经过身份验证的用户具有 listCollections 特权。

    • 在最坏的情况下，自动加密可能会使客户端在任何时间使用的连接数增加两倍。

    • 如果自动加密在操作上失败，请使用配置了bypass_auto_encryption: true 的 MongoClient 并使用 ClientEncryption.encrypt 手动加密值。

    • 启用客户端加密会减小最大写入批处理大小，可能会对性能产生负面影响。

由于：

  • 2.0.0



502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
 
# File 'lib/ Mongo/ 客户端.rb', 第 502 行

def 初始化(Addresses_or_uri, 选项 = nil)
  选项 = 选项 ? 选项.dup : {}

  已处理 = process_addresses(Addresses_or_uri, 选项)

  uri = 已处理[:uri]
  地址 = 已处理[:addresses]
  选项 = 已处理[:options]

  # 如果 URI 是 SRV URI，请记下这一点，以便我们可以启动
  # 如果拓扑结构是分片集群，则 SRV 轮询。
  srv_uri = uri if uri.is_a?(URI::SRVProtocol)

  选项 = self.class.canonicalize_ruby_options(选项)

  # 服务器API版本指定为string 。
  # 但是，总是以string形式提供数字 1 是非常烦人的，
  # 因此在此处转换为string类型。
  if server_api = 选项[:server_api]
    if server_api.is_a?(哈希)
      server_api = 选项::已编辑.new(server_api)
      if (版本 = server_api[:version]).is_a?(整型)
        选项[:server_api] = server_api.合并(merge)(版本： 版本.to_s)
      end
    end
  end

  # 对 sdam_proc 进行特殊处理，因为它仅在客户端期间使用
  # 构建
  sdam_proc = 选项.删除(:sdam_proc)

  # 对于 gssapi service_name，默认选项以哈希形式给出
  #（从顶层向下一级）。
  merged_options = default_options(选项)
  选项.每 do |k, v|
    default_v = merged_options[k]
    if 哈希 === default_v
      v = default_v.合并(merge)(v)
    end
    merged_options[k] = v
  end
  选项 = merged_options

  选项.密钥.每 do |k|
    if 选项[k].nil?
      选项.删除(k)
    end
  end

  @options = validate_new_options!(选项)
=begin WriteConcern 对象支持
  if @options[:write_concern].is_a?(WriteConcern::Base)
    # 缓存实例，以便我们不会不必要地重建它。
    @write_concern = @options[:write_concern]
    @options[:write_concern] = @write_concern.options
  end
=end
  @options.冻结
  validate_options!(地址, is_srv: uri.is_a?(URI::SRVProtocol))
  validate_authentication_options!

  database_options = @options.dup
  database_options.删除(:server_api)
  @database = Database.new(self, @options[:database], database_options)

  # 临时设立监控，以便事件订阅
  # 在没有集群的情况下进行设置
  @monitoring = 监控.new(@options)

  if sdam_proc
    sdam_proc.调用(self)
  end

  @connect_lock = 互斥锁.new
  @connect_lock.同步 do
    @cluster = 集群.new(地址, @monitoring,
      cluster_options.合并(merge)(srv_uri: srv_uri))
  end

  开始
    # 取消设置监控，从现在开始将其从集群中删除
    remove_instance_variable(' @monitoring ')

    if @options[:auto_encryption_options]
      @connect_lock.同步 do
        build_encrypter
      end
    end

  救援
    开始
      @cluster.关闭
    救援 => e
      log_warn("在客户端构造函数的异常处理程序中关闭集群时出错: #{ e . class } : #{ e } ")
      # 删除此异常，以便引发原始异常
    end
    提高
  end

  if block_given?
    开始
      产量(self)
    确保
      关闭
    end
  end
end

实例属性详细信息

# 集群 ⇒ Mongo::Cluster (readonly)

返回集群客户端的服务器集群。

返回：

由于：

  • 2.0.0



139
140
141
 
# File 'lib/ Mongo/ 客户端.rb', 第 139 行

def 集群
  @cluster
end

#数据库⇒ Mongo::Database (readonly)

返回数据库 客户端正在操作的数据库。

返回：

由于：

  • 2.0.0



142
143
144
 
# File 'lib/ Mongo/ 客户端.rb', 第 142 行

def database
  @database
end

# encrypter ⇒ Mongo::Crypt::AutoEncrypter (readonly)

返回 封装自动加密行为的对象。

返回：

由于：

  • 2.0.0



149
150
151
 
# File 'lib/ Mongo/ 客户端.rb', 第 149 行

def 加密器
  @encrypter
end

# options ⇒哈希（只读）

返回 options 配置选项。

返回：

  • (哈希) —

    options 配置选项。

由于：

  • 2.0.0



145
146
147
 
# File 'lib/ Mongo/ 客户端.rb', 第 145 行

def 选项
  @options
end

类方法详细信息

。 canonicalize_ruby_options (options) ⇒对象

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

将指定选项中的身份验证机制属性（如果给定）小写，然后将选项转换为 Options::Redacted 的实例。

由于：

  • 2.0.0



1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
 
# File 'lib/ Mongo/ 客户端.rb', 第 1162 行

def canonicalize_ruby_options(选项)
  选项::已编辑.new(哈希[选项.map do |k, v|
    if k == :auth_mech_properties || k == ' auth_mech_properties '
      if v
        v = 哈希[v.map { |pk, pv| [pk.Downcase, pv] }]
      end
    end
    [k, v]
  end])
end

实例方法详细信息

# == (other) ⇒ true , false也称为： eql?

确定此客户端是否等同于另一个对象。

例子：

检查客户端相等性。

client == other

参数：

  • 其他 ( Object ) —

    要比较的对象。

返回：

  • ( true , false ) —

    如果对象相等。

由于：

  • 2.0.0



178
179
180
181
 
# File 'lib/ Mongo/ 客户端.rb', 第 178 行

def ==(其他)
  return false 除非 其他.is_a?(客户)
  集群 == 其他.集群 && 选项 == 其他.选项
end

# [] (collection_name, options = {}) ⇒ Mongo::Collection

获取所提供集合名称的集合对象。

例子：

获取集合。

client[:users]

参数：

  • collection_name ( string , Symbol ) —

    集合的名称。

  • 选项 （哈希） （默认为： {} ） —

    集合的选项。

返回：

由于：

  • 2.0.0



195
196
197
 
# File 'lib/ Mongo/ 客户端.rb', 第 195 行

def [ ](collection_name, 选项 = {})
  database[collection_name, 选项]
end

# close ⇒ true

关闭所有连接。

返回：

  • ( true ) —

    始终为 true。

由于：

  • 2.1.0



865
866
867
868
869
870
871
 
# File 'lib/ Mongo/ 客户端.rb', 第 865 行

def 关闭
  @connect_lock.同步 do
    @close = true
    do_close
  end
  true
end

# close_encrypter ⇒ true

关闭加密器并清理自动加密资源。

返回：

  • ( true ) —

    始终为 true。

由于：

  • 2.0.0



876
877
878
879
880
 
# File 'lib/ Mongo/ 客户端.rb', 第 876 行

def close_encrypter
  @encrypter.关闭 if @encrypter

  true
end

#已关闭？ ⇒布尔

返回：

  • （布尔值）

由于：

  • 2.0.0



856
857
858
 
# File 'lib/ Mongo/ 客户端.rb', 第 856 行

def 已关闭？
  !!@close
end

# cluster_options ⇒对象

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

由于：

  • 2.0.0



611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
 
# File 'lib/ Mongo/ 客户端.rb', 第 611 行

def cluster_options
  # 当具有不同 CRUD_OPTIONS 的新客户端出现时，我们会股票集群
  # 已请求；因此，集群不应获得任何这些
  # 实例化时的选项
  选项.拒绝 do |key, 值|
    CRUD_OPTIONS.包括？(key.to_sym)
  end.合并(merge)(
    # 但需要放回数据库进行身份验证...
    database: 选项[:database],

    # 放入这些选项是为了兼容传统版本，但请注意
    # 它们在客户端和集群上的值不必匹配 -
    # 应用程序应从客户端而不是集群读取这些值
    max_read_retries: 选项[:max_read_retries],
    read_retry_interval: 选项[:read_retry_interval],
  ).点击 do |选项|
    # 如果客户端已有集群，则将 srv_uri 转发到新集群
    # 用于维护 SRV 监控的集群。 如果客户端是全新的，
    # 其构造函数手动设置 srv_uri。
    if 集群
      选项.update(srv_uri: 集群.选项[:srv_uri])
    end
  end
end

# database_names (filter = {}, opts = {}) ⇒ Array<String>

获取所有数据库的名称。

例子：

获取数据库名称。

client.database_names

参数：

  • 筛选器 （哈希） （默认为： {} ） —

    用于获取数据库列表的筛选条件。

  • opts （哈希） （默认为： {} ） —

    命令选项。

  • 选项 (哈希) —

    一组可自定义的选项

选项哈希 ( opts )：

  • :authorized_databases ( true , false ) —

    一个标志，用于确定启用访问权限控制时根据用户权限返回哪些数据库

    请参阅mongodb.com/zh-cn/docs/manual/reference/command/listDatabases/ 了解更多信息和用法。

  • :session （会话） —

    要使用的会话。

  • :comment （对象） —

    用户提供的待附加到该命令的注释。

返回：

  • ( Array<String> ) —

    数据库的名称。

由于：

  • 2.0.5



932
933
934
 
# File 'lib/ Mongo/ 客户端.rb', 第 932 行

def database_names(筛选器 = {}, opts = {})
  list_databases(筛选器, true, opts).收集{ |信息| 信息[' name '] }
end

#encrypted_fields_map ⇒哈希 | nil

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

如果在创建客户端时提供了加密字段映射哈希，则返回加密字段映射哈希。

返回：

  • ( Hash | nil ) —

    加密的字段映射哈希值，如果未设立，则为 nil。

由于：

  • 2.0.0



1178
1179
1180
 
# File 'lib/ Mongo/ 客户端.rb', 第 1178 行

def encryption_fields_map
  @encrypted_fields_map ||= @options.获取(:auto_encryption_options, {})[:encrypted_fields_map]
end

# get_session (options = {}) ⇒会话| nil

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

如果可能，返回用于操作的会话。

如果设置了 :session 选项，则验证该会话并将其返回。 否则，如果部署支持会话，则创建一个新会话并将其返回。 创建新会话时，如果给出 :implicit 选项，则该会话将为隐式会话（生命周期由驱动程序管理），否则会话将为显式会话（生命周期由应用程序管理）。 如果部署不支持会话，则返回 nil。

参数：

  • 选项 （哈希） （默认为： {} ） —

    一组可自定义的选项

选项哈希 ( options )：

  • :implicit ( true | false ) —

    未传入会话时，是否创建隐式会话。

  • :session （会话） —

    要验证并返回的会话。

返回：

  • ( Session | nil ) —

    会话对象，如果部署不支持会话，则返回 nil。

由于：

  • 2.0.0



1118
1119
1120
1121
1122
 
# File 'lib/ Mongo/ 客户端.rb', 第 1118 行

def get_session(选项 = {})
  get_session!(选项)
救援 错误::SessionsNotSupported
  nil
end

#哈希⇒整数

获取客户端的哈希值。

例子：

获取客户端哈希值。

client.hash

返回：

  • ( Integer ) —

    客户端哈希值。

由于：

  • 2.0.0



207
208
209
 
# File 'lib/ Mongo/ 客户端.rb', 第 207 行

def 哈希
  [集群, 选项].哈希
end

#检查⇒ string

以string形式获取客户端检查结果。

例子：

检查客户端。

client.inspect

返回：

  • ( string ) —

    检查string 。

由于：

  • 2.0.0



674
675
676
 
# File 'lib/ Mongo/ 客户端.rb', 第 674 行

def 检查
  " #<Mongo::Client:0 x #{ object_id} 集群= #{ 集群.summary} > "
end

# list_databases (filter = {}, name_only = false, opts = {}) ⇒ Array<Hash>

获取每个数据库的信息。

See https://mongodb.com/zh-cn/docs/manual/reference/command/listDatabases/
for more information and usage.

例子：

获取每个数据库的信息。

client.list_databases

参数：

  • 筛选器 （哈希） （默认为： {} ） —

    用于获取数据库列表的筛选条件。

  • name_only ( true , false ) （默认为： false ） —

    是否仅返回每个数据库名称，而不返回完整的元数据。

  • opts （哈希） （默认为： {} ） —

    命令选项。

  • 选项 (哈希) —

    一组可自定义的选项

选项哈希 ( opts )：

  • :authorized_databases ( true , false ) —

    一个标志，用于确定启用访问权限控制时根据用户权限返回哪些数据库。

  • :comment （对象） —

    用户提供的待附加到该命令的注释。

  • :session （会话） —

    要使用的会话。

返回：

  • ( Array<Hash> ) —

    每个数据库的信息。

由于：

  • 2.0.5



963
964
965
966
967
968
969
 
# File 'lib/ Mongo/ 客户端.rb', 第 963 行

def list_databases(筛选器 = {}, name_only = false, opts = {})
  cmd = { listDatabases： 1 }
  cmd[:nameOnly] = !!name_only
  cmd[:filter] = 筛选器 除非 筛选器.空？
  cmd[:authorizedDatabases] = true if opts[:authorized_databases]
  请使用(Database::ADMIN).database.read_command(cmd, opts).first[Database::数据库]
end

# list_mongo_databases (filter = {}, opts = {}) ⇒ Array< Mongo::Database >

返回 Mongo::Database 对象的列表。

例子：

获取 Mongo::Database 对象的列表。

client.list_mongo_databases

参数：

  • 筛选器 （哈希） （默认为： {} ） —

    用于获取数据库列表的筛选条件。

  • opts （哈希） （默认为： {} ） —

    命令选项。

  • 选项 (哈希) —

    一组可自定义的选项

选项哈希 ( opts )：

  • :session （会话） —

    要使用的会话。

返回：

由于：

  • 2.5.0



986
987
988
989
990
 
# File 'lib/ Mongo/ 客户端.rb', 第 986 行

def list_mongo_databases(筛选器 = {}, opts = {})
  database_names(筛选器, opts).收集 do |名称|
    Database.new(self, 名称, 选项)
  end
end

# max_read_retries ⇒整数

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

获取使用传统读取重试时客户端可以重试读取操作的最大次数。

返回：

  • ( Integer ) —

    最大重试次数。

由于：

  • 2.0.0



642
643
644
 
# File 'lib/ Mongo/ 客户端.rb', 第 642 行

def max_read_retries
  选项[:max_read_retries] || 集群::MAX_READ_RETRIES
end

# max_write_retries ⇒整数

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

获取使用传统写入重试时客户端可以重试写入操作的最大次数。

返回：

  • ( Integer ) —

    最大重试次数。

由于：

  • 2.0.0



662
663
664
 
# File 'lib/ Mongo/ 客户端.rb', 第 662 行

def max_write_retries
  选项[:max_write_retries] || 集群::MAX_WRITE_RETRIES
end

# read_concern ⇒哈希

获取此客户端的读关注（read concern）。

例子：

获取客户端读关注。

client.read_concern

返回：

  • (哈希) —

    读关注。

由于：

  • 2.6.0



839
840
841
 
# File 'lib/ Mongo/ 客户端.rb', 第 839 行

def read_concern
  选项[:read_concern]
end

# read_preference ⇒ BSON::Document

从传递给客户端的选项中获取读取偏好（read preference）。

例子：

获取读取偏好。

client.read_preference

返回：

  • ( BSON::Document ) —

    用户定义的读取偏好。 该文档可能包含以下字段：

    • ：模式—读取偏好（read preference），指定为符号；有效值为： 主节点 (primary node in the replica set) 、 :primary_preferred 、 : secondary_preferred和:nearest 。

    • :tag_sets – 哈希数组。

    • :local_threshold 。

由于：

  • 2.0.0



722
723
724
 
# File 'lib/ Mongo/ 客户端.rb', 第 722 行

def read_preference
  @read_preference ||= 选项[:read]
end

# read_retry_interval ⇒浮点

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

获取使用传统读取重试时读取重试的时间间隔（以秒为单位）。

返回：

  • (浮点) —

    间隔。

由于：

  • 2.0.0



652
653
654
 
# File 'lib/ Mongo/ 客户端.rb', 第 652 行

def read_retry_interval
  选项[:read_retry_interval] || 集群::READ_RETRY_INTERVAL
end

# reconnect ⇒ true

重新连接客户端。

例子：

重新连接客户端。

client.reconnect

返回：

  • ( true ) —

    始终为 true。

由于：

  • 2.1.0



890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
 
# File 'lib/ Mongo/ 客户端.rb', 第 890 行

def 重新连接
  地址 = 集群.地址.map(和:to_s)

  @connect_lock.同步 do
    do_close 救援 nil

    @cluster = 集群.new(地址, 监控, cluster_options)

    if @options[:auto_encryption_options]
      build_encrypter
    end

    @close = false
  end

  true
end

# server_selector ⇒ Mongo::ServerSelector

获取服务器选择器。 它要么使用客户端选项中定义的读取偏好，要么默认为主服务器选择器。

例子：

获取服务器选择器。

client.server_selector

返回：

  • ( Mongo::ServerSelector ) —

    使用用户定义的读取偏好（read preference）的服务器选择器或默认主服务器选择器。

由于：

  • 2.5.0



700
701
702
703
704
705
706
 
# File 'lib/ Mongo/ 客户端.rb', 第 700 行

def server_selector
  @server_selector ||= if read_preference
    ServerSelector.获取(read_preference)
  else
    ServerSelector.主节点
  end
end

# start_session (options = {}) ⇒会话

注意：

会话不能同时被多个线程使用；会话对象不是线程安全的。

启动会话。

如果部署不支持会话，则引发 Mongo::Error::InvalidSession。 当驾驶员未连接到承载数据的服务器时（示例在故障转移期间），也可能会引发此异常。

例子：

启动会话。

client.start_session(causal_consistency: true)

参数：

  • 选项 （哈希） （默认为： {} ） —

    会话选项。 接受 Session#initialize 接受的选项。

返回：

由于：

  • 2.5.0



1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
 
# File 'lib/ Mongo/ 客户端.rb', 第 1011 行

def start_session(选项 = {})
  会话 = get_session!(选项.合并(merge)(隐式： false))
  if block_given?
    开始
      产量 会话
    确保
      会话.end_session
    end
  else
    会话
  end
end

#摘要⇒ string

注意：

返回的摘要string的确切格式和布局不是驱动程序公共API的一部分，并且可能随时更改。

获取客户端状态摘要。

返回：

  • ( string ) —

    摘要string 。

由于：

  • 2.7.0



686
687
688
 
# File 'lib/ Mongo/ 客户端.rb', 第 686 行

def 总结
  " #<Client cluster= #{ cluster .summary } } > "
end

#timeout_ms ⇒ Integer | nil

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回 timeout_ms 选项的值（如果设立）。

返回：

  • ( Integer | nil ) —

    timeout_ms 选项的值（如果设立）。

由于：

  • 2.0.0



1184
1185
1186
 
# File 'lib/ Mongo/ 客户端.rb', 第 1184 行

def timeout_ms
  @options[:timeout_ms]
end

#timeout_sec ⇒ Float | nil

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回转换为秒的 timeout_ms 选项值。

返回：

  • ( Float | nil ) —

    timeout_ms 选项的值转换为秒。

由于：

  • 2.0.0



1190
1191
1192
1193
1194
1195
1196
 
# File 'lib/ Mongo/ 客户端.rb', 第 1190 行

def timeout_sec
  if timeout_ms.nil?
    nil
  else
    timeout_ms / 1_000.0
  end
end

#update_options(new_options) ⇒ Hash

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

从 new_options 更新此客户端的选项，从而验证所有选项。

新选项可以根据各种规则进行转换。 返回实际应用于客户端的选项的最终哈希值。

如果选项验证失败，此方法可能会发出警告或引发异常。 如果此方法引发异常，则应丢弃客户端（与构造函数引发异常的情况类似）。

参数：

  • new_options (哈希) —

    要使用的新选项。

返回：

  • (哈希) —

    修改后写入客户端的新选项。

由于：

  • 2.0.0



789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
 
# File 'lib/ Mongo/ 客户端.rb', 第 789 行

def update_options(new_options)
  old_options = @options

  new_options = self.class.canonicalize_ruby_options(new_options || {})

  validate_new_options!(new_options).点击 do |opts|
    # 我们的选项已冻结
    选项 = @options.dup
    if 选项[:write] && opts[:write_concern]
      选项.删除(:write)
    end
    if 选项[:write_concern] && opts[:write]
      选项.删除(:write_concern)
    end

    选项.update(opts)
    @options = 选项.冻结

    auto_encryption_options_changed =
      @options[:auto_encryption_options] != old_options[:auto_encryption_options]

    # 如果有新的 auto_encryption_options，则创建新的加密器。
    # 否则，允许新客户端与
    # 原始客户端。
    #
    # 如果 auto_encryption_options 为 nil，则将 @encrypter 设置为 nil，但不
    # 关闭加密器，因为原始客户端可能仍在使用它。
    if @options[:auto_encryption_options] && auto_encryption_options_changed
      @connect_lock.同步 do
        build_encrypter
      end
    elsif @options[:auto_encryption_options].nil?
      @connect_lock.同步 do
        @encrypter = nil
      end
    end

    validate_options!
    validate_authentication_options!
  end
end

# use (name) ⇒ Mongo::Client

注意：

新客户端与原始客户端共享集群，因此也共享监控实例和监控事件订阅者。

创建一个新客户端，配置为使用具有提供名称的数据库，并使用此客户端中配置的其他选项。

例子：

为“users”数据库创建客户端。

client.use(:users)

参数：

  • 名称 ( string , Symbol ) —

    要使用的数据库名称。

返回：

由于：

  • 2.0.0



741
742
743
 
# File 'lib/ Mongo/ 客户端.rb', 第 741 行

def 请使用(名称)
  通过(database: 名称)
end

# watch (管道 = [], options = {}) ⇒ ChangeStream

注意：

变更流只允许“多数”读关注（read concern）。

注意：

出于支持可恢复性的目的，此辅助方法优于使用 $changeStream 阶段运行原始聚合。

从 MongoDB Server 3.6版本开始，聚合框架支持“$changeStream”管道阶段。 从版本4.0开始，此阶段允许用户请求为客户端集群中发生的所有更改发送通知。

例子：

获取客户端集群的变更通知。

client.watch([{ '$match' => { operationType: { '$in' => ['insert', 'replace'] } } }])

参数：

  • 管道 ( Array<Hash> ) （默认为： [] ） —

    可选的附加过滤器操作符。

  • 选项 （哈希） （默认为： {} ） —

    变更流选项。

选项哈希 ( options )：

  • :full_document （ string ） —

    允许的值：nil、'default'、'updateLookup'、'whenAvailable'、'required'。

    默认为不发送值（即 nil)，相当于“default”。 默认情况下，部分更新的变更通知将包含描述文档变更的增量。

    当设置为“updateLookup”时，部分更新的变更通知将包括描述文档更改的增量，以及自更改发生后某个时间以来已更改的整个文档的副本。

    当设置为 'whenAvailable' 时，将变更流配置为返回替换和更新变更事件的已修改文档的后像（如果此事件的后像可用）。

    当设置为“必需”时，行为与“whenAvailable”相同，只是如果后图像不可用，则会引发错误。

  • :full_document_before_change （ string ） —

    允许的值：nil、'whenAvailable'、'required'、'off'。

    默认为不发送值（即 nil)，相当于“off”。

    当设置为 'whenAvailable' 时，将变更流配置为返回用于替换、更新和删除变更事件的已修改文档的前像（如果可用）。

    当设置为“必需”时，行为与“whenAvailable”相同，只是如果前像不可用，则会引发错误。

  • :resume_after （ BSON::Document 、 Hash ） —

    指定新变更流的逻辑起点。

  • :max_await_time_ms （整数） —

    服务器等待新文档满足变更流查询的最长时间。

  • :batch_size （整数） —

    批次中要返回的文档数量。

  • :collation （ BSON::Document 、 Hash ） —

    要使用的排序规则。

  • :session （会话） —

    要使用的会话。

  • :start_at_operation_time ( BSON::Timestamp ) —

    仅返回在指定时间戳时或之后发生的更改。 针对服务器运行的任何命令都将返回可在此处使用的集群时间。 仅由服务器版本4.0 + 识别。

  • :comment （对象） —

    用户提供的待附加到该命令的注释。

  • :show_expanded_events （布尔值） —

    使服务器能够发送变更流事件的“扩展”列表。 此标志集包含的其他事件列表包括：createIndexes、dropIndexes、modify、create、shardCollection、reshardCollection、refinedCollectionShardKey。

返回：

  • ( ChangeStream ) —

    变更流对象。

由于：

  • 2.6.0



1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
 
# File 'lib/ Mongo/ 客户端.rb', 第 1088 行

def 观看(管道 = [], 选项 = {})
  return 请使用(Database::ADMIN).观看(管道, 选项) 除非 database.名称 == Database::ADMIN

  view_options = 选项.dup
  view_options[:cursor_type] = :tailable_await if 选项[:max_await_time_ms]

  mongo::Collection::查看::变更流.new(
    mongo::Collection::查看.new(self[" #{ Database :: COMMAND } .aggregate "], {}, view_options),
    管道,
    mongo::Collection::查看::变更流::集群,
    选项)
end

# with (new_options = nil) ⇒ Mongo::Client

注意：

根据给定的选项，返回的客户端可能与原始客户端共享集群，或者使用新集群创建。 如果创建了新集群，则新客户端上的监控事件订阅者将设置为默认事件订阅者集，并且原始客户端上的任何订阅者都不会被复制。

创建一个新客户端，并将传递的选项合并到该客户端的现有选项上。 对于在不改变原始客户端的情况下一次性更改特定选项非常有用。

例子：

获取具有更改选项的客户端。

client.with(:read => { :mode => :primary_preferred })

参数：

  • new_options （哈希） （默认为： nil ） —

    要使用的新选项。

返回：

由于：

  • 2.0.0



763
764
765
766
767
768
769
770
771
772
773
 
# File 'lib/ Mongo/ 客户端.rb', 第 763 行

def 通过(new_options = nil)
  克隆.点击 do |客户端|
    opts = 客户端.update_options(new_options || 选项::已编辑.new)
    Database.创建(客户端)
    # 如果某些选项会影响集群，则不能使用该集群
    # 已更改。
    if cluster_moduring?(opts)
      集群.创建(客户端, 监控： opts[:monitoring])
    end
  end
end

# with_session (options = {}, &block) ⇒对象

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

如果可能，创建一个用于操作的会话，并将其生成提供的区块。

如果设置了 :session 选项，则验证该会话并使用它。 否则，如果部署支持会话，则创建并使用新会话。 创建新会话时，如果给出 :implicit 选项，则该会话将为隐式会话（生命周期由驱动程序管理），否则会话将为显式会话（生命周期由应用程序管理）。 如果部署不支持会话，则块的产出为 nil。

当区块完成时，如果会话已创建并且是隐式的，或者传入了隐式会话，则会话将结束，从而将其返回到可用会话池中。

参数：

  • 选项 （哈希） （默认为： {} ） —

    一组可自定义的选项

选项哈希 ( options )：

  • :implicit ( true | false ) —

    未传入会话时，是否创建隐式会话。

  • :session （会话） —

    要验证并返回的会话。

由于：

  • 2.0.0



1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
 
# File 'lib/ Mongo/ 客户端.rb', 第 1144 行

def with_session(选项 = {}, 和块)
  # TODO：将其重新添加到 RUBY- 3174中。
  #assert_not_close

  会话 = get_session(选项)

  产量 会话
确保
  if 会话 && 会话.隐式？
    会话.end_session
  end
end

# write_concern ⇒ Mongo::WriteConcern

获取此客户端的写关注。 如果未提供选项，则使用默认的单服务器确认。

例子：

获取客户端写关注。

client.write_concern

返回：

由于：

  • 2.0.0



852
853
854
 
# File 'lib/ Mongo/ 客户端.rb', 第 852 行

def write_concern
  @write_concern ||= writeConcern.获取(选项[:write_concern] || 选项[:write])
end