Client — Documentation by YARD 0.9.37 (original) (raw)

Examples:

Instantiate a single server or mongos client.

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

Instantiate a client for a replica set.

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

Directly connect to a mongod in a replica set

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

• :app_name (String, Symbol) —
  Application name that is printed to the mongod logs upon establishing a connection in server versions >= 3.4.
• :auth_mech (Symbol) —
  The authentication mechanism to use. One of :mongodb_cr, :mongodb_x509, :plain, :scram, :scram256
• :auth_mech_properties (Hash)
• :auth_source (String) —
  The source to authenticate from.
• :bg_error_backtrace (true | false | nil | Integer) —
  Experimental. Set to true to log complete backtraces for errors in background threads. Set to false or nil to not log backtraces. Provide a positive integer to log up to that many backtrace lines.
• :compressors (Array) —
  A list of potential compressors to use, in order of preference. The driver chooses the first compressor that is also supported by the server. Currently the driver only supports ‘zstd, ’snappy’ and ‘zlib’.
• :direct_connection (true | false) —
  Whether to connect directly to the specified seed, bypassing topology discovery. Exactly one seed must be provided.
• :connect (Symbol) —
  Deprecated - use :direct_connection option instead of this option. The connection method to use. This forces the cluster to behave in the specified way instead of auto-discovering. One of :direct, :replica_set, :sharded, :load_balanced. If :connect is set to :load_balanced, the driver will behave as if the server is a load balancer even if it isn’t connected to a load balancer.
• :connect_timeout (Float) —
  The timeout, in seconds, to attempt a connection.
• :database (String) —
  The database to connect to.
• :heartbeat_frequency (Float) —
  The interval, in seconds, for the server monitor to refresh its description via hello.
• :id_generator (Object) —
  A custom object to generate ids for documents. Must respond to #generate.
• :load_balanced (true | false) —
  Whether to expect to connect to a load balancer.
• :local_threshold (Integer) —
  The local threshold boundary in seconds for selecting a near server for an operation.
• :logger (Logger) —
  A custom logger to use.
• :log_prefix (String) —
  A custom log prefix to use when logging. This option is experimental and subject to change in a future version of the driver.
• :max_connecting (Integer) —
  The maximum number of connections that can be connecting simultaneously. The default is 2. This option should be increased if there are many threads that share the same client and the application is experiencing timeouts while waiting for connections to be established. selecting a server for an operation. The default is 2.
• :max_idle_time (Integer) —
  The maximum seconds a socket can remain idle since it has been checked in to the pool.
• :max_pool_size (Integer) —
  The maximum size of the connection pool. Setting this option to zero creates an unlimited connection pool.
• :max_read_retries (Integer) —
  The maximum number of read retries when legacy read retries are in use.
• :max_write_retries (Integer) —
  The maximum number of write retries when legacy write retries are in use.
• :min_pool_size (Integer) —
  The minimum size of the connection pool.
• :monitoring (true, false) —
  If false is given, the client is initialized without global SDAM event subscribers and will not publish SDAM events. Command monitoring and legacy events will still be published, and the driver will still perform SDAM and monitor its cluster in order to perform server selection. Built-in driver logging of SDAM events will be disabled because it is implemented through SDAM event subscription. Client#subscribe will succeed for all event types, but subscribers to SDAM events will not be invoked. Values other than false result in default behavior which is to perform normal SDAM event publication.
• :monitoring_io (true, false) —
  For internal driver use only. Set to false to prevent SDAM-related I/O from being done by this client or servers under it. Note: setting this option to false will make the client non-functional. It is intended for use in tests which manually invoke SDAM state transitions.
• :cleanup (true | false) —
  For internal driver use only. Set to false to prevent endSessions command being sent to the server to clean up server sessions when the cluster is disconnected, and to to not start the periodic executor. If :monitoring_io is false, :cleanup automatically defaults to false as well.
• :password (String) —
  The user’s password.
• :platform (String) —
  Platform information to include in the metadata printed to the mongod logs upon establishing a connection in server versions >= 3.4.
• :read (Hash) —
  The read preference options. The hash may have the following items:
• :mode – read preference specified as a symbol; valid values are :primary, :primary_preferred, :secondary, :secondary_preferred and :nearest.
• :tag_sets – an array of hashes.
• :local_threshold.
• :read_concern (Hash) —
  The read concern option.
• :read_retry_interval (Float) —
  The interval, in seconds, in which reads on a mongos are retried.
• :replica_set (Symbol) —
  The name of the replica set to connect to. Servers not in this replica set will be ignored.
• :retry_reads (true | false) —
  If true, modern retryable reads are enabled (which is the default). If false, modern retryable reads are disabled and legacy retryable reads are enabled.
• :retry_writes (true | false) —
  Retry writes once when connected to a replica set or sharded cluster versions 3.6 and up. (Default is true.)
• :scan (true | false) —
  Whether to scan all seeds in constructor. The default in driver version 2.x is to do so; driver version 3.x will not scan seeds in constructor. Opt in to the new behavior by setting this option to false. Note: setting this option to nil enables scanning seeds in constructor in driver version 2.x. Driver version 3.x will recognize this option but will ignore it and will never scan seeds in the constructor.
• :sdam_proc (Proc) —
  A Proc to invoke with the client as the argument prior to performing server discovery and monitoring. Use this to set up SDAM event listeners to receive events published during client construction.
  Note: the client is not fully constructed when sdam_proc is invoked, in particular the cluster is nil at this time. sdam_proc should limit itself to calling #subscribe and #unsubscribe methods on the client only.
• :server_api (Hash) —
  The requested server API version. This hash can have the following items:
• :version – string
• :strict – boolean
• :deprecation_errors – boolean
• :server_selection_timeout (Integer) —
  The timeout in seconds for selecting a server for an operation.
• :socket_timeout (Float) —
  The timeout, in seconds, to execute operations on a socket. This option is deprecated, use :timeout_ms instead.
• :srv_max_hosts (Integer) —
  The maximum number of mongoses that the driver will communicate with for sharded topologies. If this option is 0, then there will be no maximum number of mongoses. If the given URI resolves to more hosts than “:srv_max_hosts“, the client will ramdomly choose an “:srv_max_hosts“ sized subset of hosts.
• :srv_service_name (String) —
  The service name to use in the SRV DNS query.
• :ssl (true, false) —
  Whether to use TLS.
• :ssl_ca_cert (String) —
  The file containing concatenated certificate authority certificates used to validate certs passed from the other end of the connection. Intermediate certificates should NOT be specified in files referenced by this option. One of :ssl_ca_cert, :ssl_ca_cert_string or :ssl_ca_cert_object (in order of priority) is required when using :ssl_verify.
• :ssl_ca_cert_object (ArrayOpenSSL::X509::Certificate) —
  An array of OpenSSL::X509::Certificate objects representing the certificate authority certificates used to validate certs passed from the other end of the connection. Intermediate certificates should NOT be specified in files referenced by this option. One of :ssl_ca_cert, :ssl_ca_cert_string or :ssl_ca_cert_object (in order of priority) is required when using :ssl_verify.
• :ssl_ca_cert_string (String) —
  A string containing certificate authority certificate used to validate certs passed from the other end of the connection. This option allows passing only one CA certificate to the driver. Intermediate certificates should NOT be specified in files referenced by this option. One of :ssl_ca_cert, :ssl_ca_cert_string or :ssl_ca_cert_object (in order of priority) is required when using :ssl_verify.
• :ssl_cert (String) —
  The certificate file used to identify the connection against MongoDB. A certificate chain may be passed by specifying the client certificate first followed by any intermediate certificates up to the CA certificate. The file may also contain the certificate’s private key, which will be ignored. This option, if present, takes precedence over the values of :ssl_cert_string and :ssl_cert_object
• :ssl_cert_object (OpenSSL::X509::Certificate) —
  The OpenSSL::X509::Certificate used to identify the connection against MongoDB. Only one certificate may be passed through this option.
• :ssl_cert_string (String) —
  A string containing the PEM-encoded certificate used to identify the connection against MongoDB. A certificate chain may be passed by specifying the client certificate first followed by any intermediate certificates up to the CA certificate. The string may also contain the certificate’s private key, which will be ignored, This option, if present, takes precedence over the value of :ssl_cert_object
• :ssl_key (String) —
  The private keyfile used to identify the connection against MongoDB. Note that even if the key is stored in the same file as the certificate, both need to be explicitly specified. This option, if present, takes precedence over the values of :ssl_key_string and :ssl_key_object
• :ssl_key_object (OpenSSL::PKey) —
  The private key used to identify the connection against MongoDB
• :ssl_key_pass_phrase (String) —
  A passphrase for the private key.
• :ssl_key_string (String) —
  A string containing the PEM-encoded private key used to identify the connection against MongoDB. This parameter, if present, takes precedence over the value of option :ssl_key_object
• :ssl_verify (true, false) —
  Whether to perform peer certificate validation and hostname verification. Note that the decision of whether to validate certificates will be overridden if :ssl_verify_certificate is set, and the decision of whether to validate hostnames will be overridden if :ssl_verify_hostname is set.
• :ssl_verify_certificate (true, false) —
  Whether to perform peer certificate validation. This setting overrides :ssl_verify with respect to whether certificate validation is performed.
• :ssl_verify_hostname (true, false) —
  Whether to perform peer hostname validation. This setting overrides :ssl_verify with respect to whether hostname validation is performed.
• :timeout_ms (Integer) —
  The operation timeout in milliseconds. Must be a non-negative integer. An explicit value of 0 means infinite. The default value is unset which means the feature is not enabled.
• :truncate_logs (true, false) —
  Whether to truncate the logs at the default 250 characters.
• :user (String) —
  The user name.
• :wait_queue_timeout (Float) —
  The time to wait, in seconds, in the connection pool for a connection to be checked in. This option is deprecated, use :timeout_ms instead.
• :wrapping_libraries (Array) —
  Information about libraries such as ODMs that are wrapping the driver, to be added to

metadata sent to the server. Specify the lower level libraries first.  
Allowed hash keys: :name, :version, :platform.  

• :write (Hash) —
  Deprecated. Equivalent to :write_concern option.
• :write_concern (Hash) —
  The write concern options. Can be :w => Integer|String, :wtimeout => Integer (in milliseconds, deprecated), :j => Boolean, :fsync => Boolean.
• :zlib_compression_level (Integer) —
  The Zlib compression level to use, if using compression. See Ruby’s Zlib module for valid levels.
• :resolv_options (Hash) —
  For internal driver use only. Options to pass through to Resolv::DNS constructor for SRV lookups.
• :auto_encryption_options (Hash) —
  Auto-encryption related options.
• :key_vault_client => Client | nil, a client connected to the MongoDB instance containing the encryption key vault
• :key_vault_namespace => String, the namespace of the key vault in the format database.collection
• :kms_providers => Hash, A hash of key management service (KMS) configuration information. Valid hash keys are :aws, :azure, :gcp, :kmip, :local. There may be more than one kms provider specified.
• :kms_tls_options => Hash, A hash of TLS options to authenticate to KMS providers, usually used for KMIP servers. Valid hash keys are :aws, :azure, :gcp, :kmip, :local. There may be more than one kms provider specified.
• :schema_map => Hash | nil, JSONSchema for one or more collections specifying which fields should be encrypted. This option is mutually exclusive with :schema_map_path.
  • Note: Schemas supplied in the schema_map only apply to configuring automatic encryption for client side encryption. Other validation rules in the JSON schema will not be enforced by the driver and will result in an error.
  • Note: Supplying a schema_map provides more security than relying on JSON Schemas obtained from the server. It protects against a malicious server advertising a false JSON Schema, which could trick the client into sending unencrypted data that should be encrypted.
  • Note: If a collection is present on both the :encrypted_fields_map and :schema_map, an error will be raised.
• :schema_map_path => String | nil A path to a file contains the JSON schema
  of the collection that stores auto encrypted documents. This option is mutually exclusive with :schema_map.
• :bypass_auto_encryption => Boolean, when true, disables auto encryption; defaults to false.
• :extra_options => Hash | nil, options related to spawning mongocryptd (this part of the API is subject to change).
• :encrypted_fields_map => Hash | nil, maps a collection namespace to a hash describing encrypted fields for queryable encryption.
  • Note: If a collection is present on both the encryptedFieldsMap and schemaMap, an error will be raised.
• :bypass_query_analysis => Boolean | nil, when true disables automatic analysis of outgoing commands.
• :crypt_shared_lib_path => [ String | nil ] Path that should be the used to load the crypt shared library. Providing this option overrides default crypt shared library load paths for libmongocrypt.
• :crypt_shared_lib_required => [ Boolean | nil ] Whether crypt shared library is required. If ‘true’, an error will be raised if a crypt_shared library cannot be loaded by libmongocrypt.
  Notes on automatic encryption:
• Automatic encryption is an enterprise only feature that only applies to operations on a collection.
• Automatic encryption is not supported for operations on a database or view.
• Automatic encryption requires the authenticated user to have the listCollections privilege.
• At worst, automatic encryption may triple the number of connections used by the Client at any one time.
• If automatic encryption fails on an operation, use a MongoClient configured with bypass_auto_encryption: true and use ClientEncryption.encrypt to manually encrypt values.
• Enabling Client Side Encryption reduces the maximum write batch size and may have a negative performance impact.