Navigation
This version of the documentation is archived and no longer supported.

Creating a Client

On this page

Using Mongo::Client

To start a Ruby driver connection, create a Mongo::Client object. Provide a list of hosts and options or a connection URI to the Mongo::Client constructor. The client’s oselected database defaults to admin.

To create a client to a standalone server, provide one host in the seed list. Optionally, you can force the cluster topology to be standalone without going through the auto-discovery steps.

copy 
Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'mydb')
Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'mydb', :connect => :direct)
Mongo::Client.new('mongodb://127.0.0.1:27017/mydb')

To connect to a replica set, pass one or more hosts and the replica set name. The driver’s auto-discovery feature finds all members of the replica set if they are not all provided.

copy 
Mongo::Client.new([ '127.0.0.1:27017', '127.0.0.1:27018' ], :database => 'mydb', replica_set: 'myapp')
Mongo::Client.new('mongodb://127.0.0.1:27017,127.0.0.1:27018/mydb?replicaSet=myapp')

To create a client to a sharded cluster, pass one or more mongos hosts. The auto-discovery feature can determine that the servers are mongos instances, but if you would like to bypass the auto-discovery, pass the sharded option to the client.

copy 
Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'mydb')
Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'mydb', :connect => :sharded)
Mongo::Client.new('mongodb://127.0.0.1:27017/mydb?connect=sharded')

The URI parser in the driver can also accept the protocol mongodb+srv as a logical pre-processing step before it considers the connection string and other options. In this protocol, the comma separated list of host names is replaced with a single host name. The format is:

copy 
Mongo::Client.new('mongodb+srv://test5.test.build.mongodb.cc')

Client Options

A number of different options can be passed to a Mongo::Client to configure driver behavior, either by providing them in the options hash to the constructor or by providing them in the URI.

Since the URI options are required in camel case, which is not the Ruby standard, the following table shows the option in the URI and its corresponding option if passed to the constructor in Ruby.

Note

The options passed directly should be symbols.

The options are explained in detail in the Connection URI reference.

Note

Options that are set in milliseconds in the URI are represented as a float in Ruby and the units are seconds.

URI Options Conversions

URI Option Ruby Option
replicaSet=String :replica_set => String
connect=String :connect => Symbol
ssl=Boolean :ssl => true|false
connectTimeoutMS=Integer :connect_timeout => Float
socketTimeoutMS=Integer :socket_timeout => Float
serverSelectionTimeoutMS=Integer :server_selection_timeout => Float
localThresholdMS=Integer :local_threshold => Float
maxPoolSize=Integer :max_pool_size => Integer
minPoolSize=Integer :min_pool_size => Integer
waitQueueTimeoutMS=Integer :wait_queue_timeout => Float
w=Integer|String { :write => { :w => Integer|String }}
wtimeoutMS=Integer { :write => { :wtimeout => Float }}
journal=Boolean { :write => { :j => true|false }}
fsync=Boolean { :write => { :fsync => true|false }}
readPreference=String { :read => { :mode => Symbol }}
readPreferenceTags=Strings { :read => { :tag_sets => Array<String> }}
authSource=String :auth_source => String
authMechanism=String :auth_mech => Symbol
authMechanismProperties=Strings { :auth_mech_properties => { :service_realm => String, :canonicalize_host_name => true|false, :service_name => String } }
appName=String :app_name => String
compressors=Strings :compressors => Array<String>
zlibCompressionLevel=Integer :zlib_compression_level => Integer

Ruby Options

Option Description Type Default
:replica_set When connecting to a replica set, this is the name of the set to filter servers by. String none
:ssl Tell the client to connect to the servers via SSL. Boolean false
:ssl_cert The certificate file path used to identify the connection against MongoDB. This option, if present, takes precedence over the values of :ssl_cert_string and :ssl_cert_object. String none
:ssl_cert_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. String none
:ssl_cert_object The OpenSSL::X509::Certificate used to identify the connection against MongoDB. OpenSSL::X509::Certificate none
:ssl_key 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. String none
:ssl_key_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. String none
:ssl_key_object The private key used to identify the connection against MongoDB. OpenSSL::PKey none
:ssl_key_pass_phrase A passphrase for the private key. String none
:ssl_ca_cert The file path containing a set of concatenated certification authority certifications 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. String none
:ssl_ca_cert_string A string containing a set of concatenated certification authority certifications 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. String none
:ssl_ca_cert_object An array of OpenSSL::X509::Certificate representing the certification authority certifications 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. Array<OpenSSL::X509::Certificate> none
:ssl_verify Whether or not to do peer certification validation. Boolean false
:connect_timeout The number of seconds to wait to establish a socket connection before raising an exception. Float 10 seconds
:socket_timeout The number of seconds to wait for an operation to execute on a socket before raising an exception. Float 5 seconds
:max_pool_size The maximum size of the connection pool for each server. Integer 5
:min_pool_size The minimum number of connections in the connection pool for each server. Integer 1
:wait_queue_timeout The number of seconds to wait for a connection in the connection pool to become available. Float 1
:write

Specifies write concern options as a Hash. Keys in the hash can be :w, :wtimeout, :j, :fsync.

copy 
{ :write => { :w => 2 } }
Hash { :w => 1 }
:read

Specifies the read preference mode and tag sets for selecting servers as a Hash. Keys in the hash are :mode and :tag_sets.

copy 
{ :read =>
  { :mode => :secondary,
    :tag_sets => [ "berlin" ]
  }
}
Hash { :mode => :primary }
:auth_source Specifies the authentication source. String For MongoDB 2.6 and later: admin if credentials are supplied, otherwise the current database
:auth_mech Specifies the authenticaion mechanism to use. Can be one of: :mongodb_cr, :mongodb_x509, :plain, :scram. Symbol MongoDB 3.0 and later: :scram if user credentials are supplied but an :auth_mech is not. 2.6 and earlier: :mongodb_cr
:auth_mech_properties Provides additional authentication mechanism properties. Hash none
:user The name of the user to authenticate with. String none
:password The password of the user to authenticate with. String none
:connect Overrides the auto-discovery feature of the driver and forces the cluster topology to a specific type. Choices: :direct, :replica_set or :sharded. Symbol none
:heartbeat_frequency The number of seconds for the server monitors to refresh server states asynchronously. Float 10
:database The name of the database to connect to. String admin
:server_selection_timeout The number of seconds to wait for an appropriate server to be selected for an operation to be executed before raising an exception. Float 30
:local_threshold Specifies the maximum latency in seconds between the nearest server and the servers that can be available for selection to operate on. Float 0.015
:app_name Application name that is printed to the mongod logs upon establishing a connection in server versions >= 3.4. String none
:compressors 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’. Array<String> none
:id_generator A custom object to generate ids for documents. Must respond to #generate. Object none
:logger A custom logger. Object Logger
:max_idle_time The maximum seconds a socket can remain idle since it has been checked in to the pool. Integer none
:max_read_retries The maximum number of read retries on mongos query failures. Integer 1
:monitoring The monitoring object. Object none
:platform Platform information to include in the metadata printed to the mongod logs upon establishing a connection in server versions >= 3.4. String none
:read_retry_interval The interval, in seconds, in which reads on a mongos are retried. Integer 5
:truncate_logs Whether to truncate the logs at the default 250 characters. Boolean true
:zlib_compression_level The Zlib compression level to use, if using compression. See Ruby’s Zlib module for valid levels. Integer none
:retry_writes If a single-statement write operation fails from a network error, the driver automatically retries it once when connected to server versions 3.6+. Boolean false

Details on Timeout Options

connect_timeout
On initialization of a connection to a server, this setting is the number of seconds to wait to connect before raising an exception. This timeout is also used when monitor threads ping their servers. The default is 10 seconds. See the socket timeout for monitoring specification for further explanation.
socket_timeout
The number of seconds to wait for an operation to execute on a socket before raising a timeout exception. It should take into account network latency and operation duration. The default is no value; the default is effectively infinity. Please consider using max_time_ms per-operation instead, as the socket_timeout does not stop the operation on the server; a long-running operation will continue to run on the server, beyond a socket timeout being reached. See the socket timeout for monitoring specification documentation for further information relating to server discovery and monitoring.
server_selection_timeout
The number of seconds to wait for the driver to find an appropriate server to which an operation can be sent before raising an exception. Defaults to 30. It should take the speed of elections during a failover into account. See the serverSelectionTimeoutMS specification for further information.
local_threshold
The maximum latency in seconds between the nearest server and the servers that can be considered available to send an operation to. Defaults to 0.015.

Note

This is not the latency window between the driver and a server, but rather the latency between the nearest server and other servers. See the localThresholdMS specification.

wait_queue_timeout
The number of seconds to wait for a connection in the connection pool to become available. You should consider increasing this number if you are seeing many Timeout errors while using many threads or when operations are long-running. Defaults to 1 second.
max_pool_size
Maximum size of the connection pool for each server. Defaults to 5 connections.
min_pool_size
Minimum number of connections in the connection pool for each server. Increase this number to create connections when the pool is initialized and to reduce the overhead of creating new connections later on. Defaults to 1.
max_time_ms
Specified as an option on a particular operation. It defines a cumulative time limit in milliseconds for processing operations on a cursor. Consider using this option instead of a socket_timeout, if the operation should be interrupted on the server. See the CRUD specification for details on operations that support this option.

Details on Connection Pooling

Mongo::Client instances have a connection pool per server in your MongoDB topology. The pool opens connections on demand to support the number of concurrent MongoDB operations your application requires. There is no thread-affinity for connections.

The client instance opens one additional connection per server in your MongoDB topology for monitoring the server’s state.

The size of each connection pool is capped at max_pool_size, which defaults to 5. When a thread in your application begins an operation on MongoDB, it tries to retrieve a connection from the pool to send that operation on. If there are some connections available in the pool, it checks out a connection from the pool and uses it for the operation. If there are no connections available and the size of the pool is less than the max_pool_size, a new connection will be created. If all connections are in use and the pool has reached its maximum, the thread waits for a connection to be returned to the pool by another thread.

The number of seconds the thread will wait is configurable. This setting, called wait_queue_timeout, is defined in seconds. It determines how long a thread will wait for a connection to be returned to the pool, when there are no connections available. If this timeout is reached, a Timeout::Error is raised. The default is 1 second.

You can also set the number of connections initialized when the pool is created with the min_pool_size setting. This is helpful if your application experiences load spikes and you want to avoid the latency of creating new connections at the beginning of a spike. The default min_pool_size is 1.

Here is an example of estimating the number of connections a multi-threaded application will open: A client connected to a 3-node replica set opens 3 monitoring sockets. It also opens as many sockets as needed to support a multi-threaded application’s concurrent operations on each server, up to max_pool_size. If the application only uses the primary (the default), then only the primary connection pool grows and the total connections is at most 8 (5 connections for the primary pool + 3 monitoring connections). If the application uses a read preference to query the secondaries, their pools also grow and the total connections can reach 18 (5 + 5 + 5 + 3).

The default configuration for a Mongo::Client works for most applications:

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

Create this client once for each process, and reuse it for all operations. It is a common mistake to create a new client for each request, which is very inefficient and not what the client was designed for.

To support extremely high numbers of concurrent MongoDB operations within one process, increase max_pool_size:

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

Any number of threads are allowed to wait for connections to become available, and they can wait the default (1 second) or the wait_queue_timeout setting:

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

When #close is called on a client by any thread, all connections are closed:

copy 
client.close

Details on Retryable Writes

If the retry_writes option is set to true, the driver will retry single-statement write operations that fail from a network error. The driver automatically retries the operation once.

Most of the write methods you use day-to-day on a collection will be retryable in 3.6. They are:

  • 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 (for all single statement ops, i.e. not for update_many or delete_many)

TCP keepalive configuration

The driver sets TCP keepalive by default. The following default values are also set if the system value can be determined and if the driver default value is less than the system value.

  • tcp_keepalive_time: 300 seconds
  • tcp_keepalive_intvl: 10 seconds
  • tcp_keepalive_cnt: 9 probes

Please see the MongoDB Diagnostics FAQ keepalive section for instructions on setting these values at the system level.

←   Tutorials CRUD Operations  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.