Class: Mongo::Client

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Loggable
Defined in:
lib/mongo/client.rb

Overview

The client is the entry point to the driver and is the main object that will be interacted with.

Since:

  • 2.0.0

Constant Summary collapse

CRUD_OPTIONS =

The options that do not affect the behavior of a cluster and its subcomponents.

Since:

  • 2.1.0

[ :database, :read, :write, :retry_writes ].freeze
VALID_OPTIONS =

Valid client options.

Since:

  • 2.1.2

[
  :app_name,
  :auth_mech,
  :auth_mech_properties,
  :auth_source,
  :compressors,
  :connect,
  :connect_timeout,
  :database,
  :heartbeat_frequency,
  :id_generator,
  :local_threshold,
  :logger,
  :max_idle_time,
  :max_pool_size,
  :max_read_retries,
  :min_pool_size,
  :monitoring,
  :monitoring_io,
  :password,
  :platform,
  :read,
  :read_concern,
  :read_retry_interval,
  :replica_set,
  :retry_writes,
  :scan,
  :sdam_proc,
  :server_selection_timeout,
  :socket_timeout,
  :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,
  :truncate_logs,
  :user,
  :wait_queue_timeout,
  :write,
  :zlib_compression_level,
].freeze
VALID_COMPRESSORS =

The compression algorithms supported by the driver.

Since:

  • 2.5.0

[ Mongo::Protocol::Compressed::ZLIB ].freeze

Constants included from Loggable

Loggable::PREFIX

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Loggable

#log_debug, #log_error, #log_fatal, #log_info, #log_warn, #logger

Constructor Details

#initialize(addresses_or_uri, options = nil) {|_self| ... } ⇒ Client

Instantiate a new driver client.

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

Parameters:

  • addresses_or_uri (Array<String>, String)

    The array of server addresses in the form of host:port or a MongoDB URI connection string.

  • options (Hash) (defaults to: nil)

    The options to be used by the client.

Options Hash (options):

  • :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.

  • :compressors (Array<String>)

    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 'zlib'.

  • :connect (Symbol)

    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

  • :connect_timeout (Float)

    The timeout, in seconds, to attempt a connection.

  • :database (String)

    The database to connect to.

  • :heartbeat_frequency (Float)

    The number of seconds for the server monitor to refresh it's description via ismaster.

  • :id_generator (Object)

    A custom object to generate ids for documents. Must respond to #generate.

  • :local_threshold (Integer)

    The local threshold boundary in seconds for selecting a near server for an operation.

  • :logger (Logger)

    A custom logger if desired.

  • :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.

  • :max_read_retries (Integer)

    The maximum number of read retries on mongos query failures.

  • :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.

  • :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_writes (true, false)

    Retry writes once when connected to a replica set or sharded cluster versions 3.6 and up.

  • :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 dispatched 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_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.

  • :ssl (true, false)

    Whether to use SSL.

  • :ssl_ca_cert (String)

    The file containing concatenated certificate authority certificates used to validate certs passed from the other end of the connection. One of :ssl_ca_cert, :ssl_ca_cert_string or :ssl_ca_cert_object (in order of priority) is required for :ssl_verify.

  • :ssl_ca_cert_object (Array<OpenSSL::X509::Certificate>)

    An array of OpenSSL::X509::Certificate representing the certificate authority certificates used to validate certs passed from the other end of the connection. One of :ssl_ca_cert, :ssl_ca_cert_string or :ssl_ca_cert_object (in order of priority) is required for :ssl_verify.

  • :ssl_ca_cert_string (String)

    A string containing concatenated certificate authority certificates used to validate certs passed from the other end of the connection. One of :ssl_ca_cert, :ssl_ca_cert_string or :ssl_ca_cert_object (in order of priority) is required for :ssl_verify.

  • :ssl_cert (String)

    The certificate file used to identify the connection against MongoDB. 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

  • :ssl_cert_string (String)

    A string containing the PEM-encoded certificate used to identify the connection against MongoDB. 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.

  • :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.

  • :write (Hash)

    The write concern options. Can be :w => Integer|String, :fsync => Boolean, :j => Boolean.

  • :zlib_compression_level (Integer)

    The Zlib compression level to use, if using compression. See Ruby's Zlib module for valid levels.

Yields:

  • (_self)

Yield Parameters:

  • _self (Mongo::Client)

    the object that the method was called on

Since:

  • 2.0.0



315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
# File 'lib/mongo/client.rb', line 315

def initialize(addresses_or_uri, options = nil)
  if options
    options = options.dup
  else
    options = {}
  end
  Lint.validate_underscore_read_preference(options[:read])
  Lint.validate_read_concern_option(options[:read_concern])
  if addresses_or_uri.is_a?(::String)
    uri = URI.get(addresses_or_uri, options)
    addresses = uri.servers
    options = uri.client_options.merge(options)
  else
    addresses = addresses_or_uri
  end
  # Special handling for sdam_proc as it is only used during client
  # construction
  sdam_proc = options.delete(:sdam_proc)
  @options = validate_options!(Database::DEFAULT_OPTIONS.merge(options)).freeze
  @database = Database.new(self, @options[:database], @options)
  # Temporarily set monitoring so that event subscriptions can be
  # set up without there being a cluster
  @monitoring = Monitoring.new(@options)
  if sdam_proc
    sdam_proc.call(self)
  end
  @server_selection_semaphore = Semaphore.new
  @cluster = Cluster.new(addresses, @monitoring, cluster_options)
  # Unset monitoring, it will be taken out of cluster from now on
  remove_instance_variable('@monitoring')

  yield(self) if block_given?
end

Instance Attribute Details

#clusterMongo::Cluster (readonly)

Returns cluster The cluster of servers for the client.

Returns:

Since:

  • 2.0.0



91
92
93
# File 'lib/mongo/client.rb', line 91

def cluster
  @cluster
end

#databaseMongo::Database (readonly)

Returns database The database the client is operating on.

Returns:

Since:

  • 2.0.0



94
95
96
# File 'lib/mongo/client.rb', line 94

def database
  @database
end

#optionsHash (readonly)

Returns options The configuration options.

Returns:

  • (Hash)

    options The configuration options.

Since:

  • 2.0.0



97
98
99
# File 'lib/mongo/client.rb', line 97

def options
  @options
end

Instance Method Details

#==(other) ⇒ true, false Also known as: eql?

Determine if this client is equivalent to another object.

Examples:

Check client equality.

client == other

Parameters:

  • other (Object)

    The object to compare to.

Returns:

  • (true, false)

    If the objects are equal.

Since:

  • 2.0.0



126
127
128
129
# File 'lib/mongo/client.rb', line 126

def ==(other)
  return false unless other.is_a?(Client)
  cluster == other.cluster && options == other.options
end

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

Get a collection object for the provided collection name.

Examples:

Get the collection.

client[:users]

Parameters:

  • collection_name (String, Symbol)

    The name of the collection.

  • options (Hash) (defaults to: {})

    The options to the collection.

Returns:

Since:

  • 2.0.0



143
144
145
# File 'lib/mongo/client.rb', line 143

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

#close(wait = false) ⇒ true

Close all connections.

Examples:

Disconnect the client.

client.close

Parameters:

  • wait (Boolean) (defaults to: false)

    Whether to wait for background threads to finish running.

Returns:

  • (true)

    Always true.

Since:

  • 2.1.0



509
510
511
512
# File 'lib/mongo/client.rb', line 509

def close(wait=false)
  @cluster.disconnect!(wait)
  true
end

#cluster_optionsObject

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 2.0.0



350
351
352
353
354
355
356
357
358
359
360
361
# File 'lib/mongo/client.rb', line 350

def cluster_options
  # We share clusters when a new client with different CRUD_OPTIONS
  # is requested; therefore, cluster should not be getting any of these
  # options upon instantiation
  options.reject do |key, value|
    CRUD_OPTIONS.include?(key.to_sym)
  end.merge(
    server_selection_semaphore: @server_selection_semaphore,
    # but need to put the database back in for auth...
    database: options[:database],
  )
end

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

Get the names of all databases.

Examples:

Get the database names.

client.database_names

Parameters:

  • filter (Hash) (defaults to: {})

    The filter criteria for getting a list of databases.

  • opts (Hash) (defaults to: {})

    The command options.

Returns:

  • (Array<String>)

    The names of the databases.

Since:

  • 2.0.5



542
543
544
# File 'lib/mongo/client.rb', line 542

def database_names(filter = {}, opts = {})
  list_databases(filter, true, opts).collect{ |info| info[Database::NAME] }
end

#hashInteger

Get the hash value of the client.

Examples:

Get the client hash value.

client.hash

Returns:

  • (Integer)

    The client hash value.

Since:

  • 2.0.0



155
156
157
# File 'lib/mongo/client.rb', line 155

def hash
  [cluster, options].hash
end

#inspectString

Get an inspection of the client as a string.

Examples:

Inspect the client.

client.inspect

Returns:

  • (String)

    The inspection string.

Since:

  • 2.0.0



371
372
373
# File 'lib/mongo/client.rb', line 371

def inspect
  "#<Mongo::Client:0x#{object_id} cluster=#{cluster.summary}>"
end

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

Get info for each database.

Examples:

Get the info for each database.

client.list_databases

Parameters:

  • filter (Hash) (defaults to: {})

    The filter criteria for getting a list of databases.

  • name_only (true, false) (defaults to: false)

    Whether to only return each database name without full metadata.

  • opts (Hash) (defaults to: {})

    The command options.

Returns:

  • (Array<Hash>)

    The info for each database.

Since:

  • 2.0.5



558
559
560
561
562
563
# File 'lib/mongo/client.rb', line 558

def list_databases(filter = {}, name_only = false, opts = {})
  cmd = { listDatabases: 1 }
  cmd[:nameOnly] = !!name_only
  cmd[:filter] = filter unless filter.empty?
  use(Database::ADMIN).command(cmd, opts).first[Database::DATABASES]
end

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

Returns a list of Mongo::Database objects.

Examples:

Get a list of Mongo::Database objects.

client.list_mongo_databases

Parameters:

  • filter (Hash) (defaults to: {})

    The filter criteria for getting a list of databases.

  • opts (Hash) (defaults to: {})

    The command options.

Returns:

Since:

  • 2.5.0



576
577
578
579
580
# File 'lib/mongo/client.rb', line 576

def list_mongo_databases(filter = {}, opts = {})
  database_names(filter, opts).collect do |name|
    Database.new(self, name, options)
  end
end

#read_concernHash

Get the read concern for this client.

Examples:

Get the client read concern.

client.read_concern

Returns:

  • (Hash)

    The read concern.

Since:

  • 2.6.0



480
481
482
# File 'lib/mongo/client.rb', line 480

def read_concern
  options[:read_concern]
end

#read_preferenceBSON::Document

Get the read preference from the options passed to the client.

Examples:

Get the read preference.

client.read_preference

Returns:

  • (BSON::Document)

    The user-defined read preference. The document may have the following fields:

    • :read – 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.

Since:

  • 2.0.0



418
419
420
# File 'lib/mongo/client.rb', line 418

def read_preference
  @read_preference ||= options[:read]
end

#reconnecttrue

Reconnect the client.

Examples:

Reconnect the client.

client.reconnect

Returns:

  • (true)

    Always true.

Since:

  • 2.1.0



522
523
524
525
526
527
528
529
# File 'lib/mongo/client.rb', line 522

def reconnect
  addresses = cluster.addresses.map(&:to_s)

  @cluster.disconnect! rescue nil

  @cluster = Cluster.new(addresses, monitoring, cluster_options)
  true
end

#server_selectorMongo::ServerSelector

Get the server selector. It either uses the read preference defined in the client options or defaults to a Primary server selector.

Examples:

Get the server selector.

client.server_selector

Returns:

  • (Mongo::ServerSelector)

    The server selector using the user-defined read preference or a Primary server selector default.

Since:

  • 2.5.0



400
401
402
# File 'lib/mongo/client.rb', line 400

def server_selector
  @server_selector ||= ServerSelector.get(read_preference || ServerSelector::PRIMARY)
end

#start_session(options = {}) ⇒ Session

Note:

A Session cannot be used by multiple threads at once; session objects are not thread-safe.

Start a session.

If the deployment does not support sessions, raises Mongo::Error::InvalidSession. This exception can also be raised when the driver is not connected to a data-bearing server, for example during failover.

Examples:

Start a session.

client.start_session(causal_consistency: true)

Parameters:

  • options (Hash) (defaults to: {})

    The session options. Accepts the options that Session#initialize accepts.

Returns:

Since:

  • 2.5.0



601
602
603
604
# File 'lib/mongo/client.rb', line 601

def start_session(options = {})
  cluster.send(:get_session, self, options.merge(implicit: false)) ||
    (raise Error::InvalidSession.new(Session::SESSIONS_NOT_SUPPORTED))
end

#summaryString

Note:

This method is experimental and subject to change.

Get a summary of the client state.

Examples:

Inspect the client.

client.summary

Returns:

  • (String)

    Summary string.

Since:

  • 2.7.0



386
387
388
# File 'lib/mongo/client.rb', line 386

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

#use(name) ⇒ Mongo::Client

Note:

The new client shares the cluster with the original client, and as a result also shares the monitoring instance and monitoring event subscribers.

Creates a new client configured to use the database with the provided name, and using the other options configured in this client.

Examples:

Create a client for the `users' database.

client.use(:users)

Parameters:

  • name (String, Symbol)

    The name of the database to use.

Returns:

Since:

  • 2.0.0



437
438
439
# File 'lib/mongo/client.rb', line 437

def use(name)
  with(database: name)
end

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

Note:

A change stream only allows 'majority' read concern.

Note:

This helper method is preferable to running a raw aggregation with a $changeStream stage, for the purpose of supporting resumability.

As of version 3.6 of the MongoDB server, a “$changeStream“ pipeline stage is supported in the aggregation framework. As of version 4.0, this stage allows users to request that notifications are sent for all changes that occur in the client's cluster.

Examples:

Get change notifications for the client's cluster.

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

Parameters:

  • pipeline (Array<Hash>) (defaults to: [])

    Optional additional filter operators.

  • options (Hash) (defaults to: {})

    The change stream options.

Options Hash (options):

  • :full_document (String)

    Allowed values: 'default', 'updateLookup'. Defaults to 'default'. When set to 'updateLookup', the change notification for partial updates will include both a delta describing the changes to the document, as well as a copy of the entire document that was changed from some time after the change occurred.

  • :resume_after (BSON::Document, Hash)

    Specifies the logical starting point for the new change stream.

  • :max_await_time_ms (Integer)

    The maximum amount of time for the server to wait on new documents to satisfy a change stream query.

  • :batch_size (Integer)

    The number of documents to return per batch.

  • :collation (BSON::Document, Hash)

    The collation to use.

  • :session (Session)

    The session to use.

  • :start_at_operation_time (BSON::Timestamp)

    Only return changes that occurred at or after the specified timestamp. Any command run against the server will return a cluster time that can be used here. Only recognized by server versions 4.0+.

Returns:

  • (ChangeStream)

    The change stream object.

Since:

  • 2.6.0



639
640
641
642
643
644
645
646
647
# File 'lib/mongo/client.rb', line 639

def watch(pipeline = [], options = {})
  return use(Database::ADMIN).watch(pipeline, options) unless database.name == Database::ADMIN

  Mongo::Collection::View::ChangeStream.new(
    Mongo::Collection::View.new(self["#{Database::COMMAND}.aggregate"]),
    pipeline,
    Mongo::Collection::View::ChangeStream::CLUSTER,
    options)
end

#with(new_options = Options::Redacted.new) ⇒ Mongo::Client

Note:

Depending on options given, the returned client may share the cluster with the original client or be created with a new cluster. If a new cluster is created, the monitoring event subscribers on the new client are set to the default event subscriber set and none of the subscribers on the original client are copied over.

Creates a new client with the passed options merged over the existing options of this client. Useful for one-offs to change specific options without altering the original client.

Examples:

Get a client with changed options.

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

Parameters:

  • new_options (Hash) (defaults to: Options::Redacted.new)

    The new options to use.

Returns:

Since:

  • 2.0.0



459
460
461
462
463
464
465
466
467
468
469
470
# File 'lib/mongo/client.rb', line 459

def with(new_options = Options::Redacted.new)
  clone.tap do |client|
    opts = validate_options!(new_options)
    client.options.update(opts)
    Database.create(client)
    # We can't use the same cluster if some options that would affect it
    # have changed.
    if cluster_modifying?(opts)
      Cluster.create(client)
    end
  end
end

#write_concernMongo::WriteConcern

Get the write concern for this client. If no option was provided, then a default single server acknowledgement will be used.

Examples:

Get the client write concern.

client.write_concern

Returns:

Since:

  • 2.0.0



494
495
496
# File 'lib/mongo/client.rb', line 494

def write_concern
  @write_concern ||= WriteConcern.get(options[:write])
end