Creating a Client

Using Mongo::Client

To connect to a MongoDB deployment, create a Mongo::Client object. Provide a list of hosts and options or a connection string URI to the``Mongo::Client`` constructor. The client's selected database defaults to admin.

By default, the driver will automatically detect the topology used by the deployment and connect appropriately.

To connect to a local standalone MongoDB deployment, specify the host and port of the server. In most cases you would also specify the database name to connect to; if no database name is specified, the client will use the admin database:

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")

To connect to MongoDB Atlas, specify the Atlas deployment URI:

Mongo::Client.new("mongodb+srv://username:myRealPassword@cluster0.mongodb.net/mydb?w=majority")

The driver will discover all nodes in the cluster and connect to them as needed.

Mongo::Client.new(...) do |client|
  # work with the client
end

Database Selection

By default, the client will connect to the admin database.

The admin database is a special database in MongoDB often used for administrative tasks and storing administrative data such as users and roles (although users and roles may also be defined in other databases). In a sharded cluster, the admin database exists on the config servers rather than the shard servers. Although it is possible to use the admin database for ordinary operations (such as storing application data), this is not recommended and the application should explicitly specify the database it wishes to use.

The database can be specified during Client construction:

# Using Ruby client options:
client = Mongo::Client.new(['localhost'], database: 'mydb')
# Using a MongoDB URI:
client = Mongo::Client.new('mongodb://localhost/mydb')

Given a Client instance, the use method can be invoked to obtain a new Client instance configured with the specified database:

client = Mongo::Client.new(['localhost'], database: 'mydb')
admin_client = client.use('admin')
# Issue an administrative command
admin_client.database.command(replSetGetConfig: 1).documents.first

There are other special databases in MongoDB which should be only used for their stated purposes:

• The config database.

• The local database.

• The $external database, which is used with PLAIN, Kerberos and X.509 authentication mechanisms.

Connection Types

The driver will, by default, discover the type of deployment it is instructed to connect to (except for load-balanced deployments) and behave in the manner that matches the deployment type. The subsections below describe how the driver behaves in each of the deployment types as well as how to force particular behavior, bypassing automatic deployment type detection.

Note that the detection of deployment type happens when the driver receives the first reply from any of the servers it is instructed to connect to (unless the load-balancing mode is requested, see below). The driver will remain in the discovered or configured topology even if the underlying deployment is replaced by one of a different type. 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.

Automatic discovery of load-balanced deployments is currently not supported. Load-balanced deployments will be treated as deployments of their underlying type, which would generally be sharded clusters. The driver will fail to correctly operate when treating a load-balanced deployment as a sharded cluster, therefore when the deployment is a load-balanced one the client must be explicitly configured to connect to a load balancer.

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 Notes

When the driver connects to a mongodb+srv protocol URI, keep in mind the following:

1. SRV URI lookup is performed synchronously when the client is constructed. If this lookup fails for any reason, client construction will fail with an exception. When a client is constructed with a list of hosts, the driver will attempt to contact and monitor those hosts for as long as the client object exists. If one of these hosts does not resolve initially but becomes resolvable later, the driver will be able to establish a connection to such a host when it becomes available. The initial SRV URI lookup must succeed on the first attempt; subsequent host lookups will be retried by the driver as needed.

2. The driver looks up URI options in the DNS TXT records corresponding to the SRV records. These options can be overridden by URI options specified in the URI and by Ruby options, in this order.

3. Because the URI options are retrieved in a separate DNS query from the SRV lookup, in environments with unreliable network connectivity the URI option query may fail when the SRV lookup succeeds. Such a failure would cause the driver to use the wrong auth source leading to authentication failures. This can be worked around by explicitly specifying the auth source:

   Mongo::Client.new("mongodb+srv://username:myRealPassword@cluster0.mongodb.net/test?w=majority&authSource=admin")

4. If the topology of the constructed Client object is unknown or a sharded cluster, the driver will begin monitoring the specified SRV DNS records for changes and will automatically update the list of servers in the cluster. The updates will stop if the topology becomes a single or a replica set.

Client Options

Mongo::Client's constructor accepts a number of options configuring the behavior of the driver. The options can be provided in the options hash as Ruby options, in the URI as URI options, or both. If both a Ruby option and the analogous URI option are provided, the Ruby option takes precedence.

{ read:
  { mode: :secondary,
    tag_sets: [ "data_center" => "berlin" ],
    max_staleness: 5,
  }
}

{ write_concern: { w: 2 } }

Timeout Options

TLS Connections

To connect to the MongoDB deployment using TLS:

• Enable TLS connections in Mongo::Client.

• Specify the client TLS certificate.

• Specify the CA certificate to verify the server's TLS certificate.

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 Connections

When a client is constructed with localhost as the host name, it will attempt an IPv4 connection only (i.e. if localhost resolves to 127.0.0.1 and ::1, the driver will only try to connect to 127.0.0.1).

When a client is constructed with hostnames other than localhost, it will attempt both IPv4 and IPv6 connections depending on the addresses that the hostnames resolve to. The driver respects the order in which getaddrinfo returns the addresses, and will attempt to connect to them sequentially. The first successful connection will be used.

The driver does not currently implement the Happy Eyeballs algorithm.

TCP Keepalive Configuration

Where allowed by system configuration and the Ruby language runtime, the driver enables TCP keepalive and, for each of the keepalive parameters listed below, sets the value of the respective parameter to the specified value if the system value can be determined and is higher than the listed driver value:

• tcp_keepalive_time: 120 seconds

• tcp_keepalive_intvl: 10 seconds

• tcp_keepalive_cnt: 9 probes

To use lower values, or to change the parameters in environments like JRuby that do not expose the required APIs, please adjust the parameters at the system level as described in the MongoDB Diagnostics FAQ keepalive section.

Connection Pooling

Mongo::Client instances have a connection pool per server that the client is connected to. The pool creates connections on demand to support concurrent MongoDB operations issued by the application. There is no thread-affinity for connections.

The client instance opens one additional connection per known server 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 the 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 size, the thread waits for a connection to be returned to the pool by another thread. If max_pool_size is set to zero, there is no limit for the maximum number of connections in the pool.

Each pool has a limit on the number of connections that can be concurrently connecting to a server. This limit is called max_connecting and defaults to 2. If the number of connections that are currently connecting to a server reaches this limit, the pool will wait for a connection attempt to succeed or fail before attempting to create a new connection. If your application has a large number of threads, you may want to increase max_connecting to avoid having threads wait for a connection to be established.

The number of seconds the thread will wait for a connection to become available is configurable. This setting, called wait_queue_timeout, is defined in seconds. If this timeout is reached, a Timeout::Error is raised. The default is 1 second.

As of driver version 2.11, the driver eagerly creates connections up to min_pool_size setting. Prior to driver version 2.11, the driver always created connections on demand. In all versions of the driver, once a connection is established, it will be kept in the pool by the driver as long as the pool size does not exceed min_pool_size.

Note that, if min_pool_size is set to a value greater than zero, the driver will establish that many connections to secondaries in replica set deployments even if the application does not perform secondary reads. The purpose of these connections is to provide faster failover when the primary changes.

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:

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:

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

To support extremely high numbers of threads that share the same client within one process, increase max_connecting:

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

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:

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:

client.close

Note that when creating a client using the block syntax described above, the client is automatically closed after the block finishes executing.

Usage with Forking Servers

When using the Mongo Ruby driver in a Web application with a forking web server such as Puma, or when the application otherwise forks, each process (parent and child) must have its own client connections. This is because:

1. Background Ruby threads, such as those used by the Ruby MongoDB driver to monitor connection state, are not transferred to the child process.

2. File descriptors like network sockets are shared between parent and child processes, which can cause I/O conflicts.

Regarding (1), if you do not restart the driver's monitoring threads on the child process after forking, although your child may initially appear to function correctly, you will eventually see Mongo::Error::NoServerAvailable exceptions if/when your MongoDB cluster state changes, for example due to network errors or a maintenance event.

Regarding (2), if a child process reuses the parent's file descriptors, you will see Mongo::Error::SocketError errors with messages such as Errno::EPIPE: Broken pipe and EOFError: end of file reached.

When the Ruby driver is used in a web application, if possible, we recommend to not create any Mongo::Client instances in the parent process (prior to the workers being forked), and instead only create client instances in the workers.

# 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>]>>"

Retryable Reads

The driver implements two mechanisms for retrying reads: modern and legacy. As of driver version 2.9.0, the modern mechanism is used by default, and the legacy mechanism is deprecated.

Retryable Writes

The driver implements two mechanisms for retrying writes: modern and legacy. As of driver version 2.9.0, the modern mechanism is used by default on servers that support it, and the legacy mechanism is deprecated and disabled by default on all server versions.

The following write methods used in day-to-day operations on collections are subject to write retries:

• 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)

Logging

You can either use the default global driver logger or set your own. To set your own:

Mongo::Logger.logger = other_logger

See the Ruby Logger documentation for more information on the default logger API and available levels.

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 )

Compression

To use wire protocol compression, at least one compressor must be explicitly requested using either the :compressors Ruby option or the compressors URI option. If no compressors are explicitly requested, the driver will not use compression, even if the required dependencies for one or more compressors are present on the system.

The driver chooses the first compressor of the ones requested that is also supported by the server. The driver currently supports zstd, snappy and zlib compressors. zstd compressor is recommended as it produces the highest compression at the same CPU consumption compared to the other compressors. For maximum server compatibility all three compressors can be specified, e.g. as compressors: ["zstd", "snappy", "zlib"].

zstd compressor requires the zstd-ruby library to be installed. snappy compressor requires the snappy library to be installed. If zstd or snappy compression is requested, and the respective library is not loadable, the driver will raise an error during Mongo::Client creation. zlib compression requires the zlib standard library extension to be present.

The server support for various compressors is as follows:

• zstd requires and is enabled by default in MongoDB 4.2 or higher.

• snappy requires MongoDB 3.4 or higher and is enabled by default in MongoDB 3.6 or higher.

• zlib requires MongoDB 3.6 or higher and is enabled by default in MongoDB 4.2 and higher.

Server API Parameters

Starting with MongoDB 5.0, applications can request that the server behaves in accordance with a particular server API version.

Server API parameters can be specified via the :server_api option to Client. These parameters cannot be provided via a URI.

Currently the only defined API version is "1". It can be requested as follows:

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

MongoDB server defines API versions as string values. For convenience, if the API version is provided as an integer, the Ruby driver will stringify it and send it to the server as a string:

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

Note that the server may define API versions that are not stringified integers. Applications must not assume that all legal API versions can be expressed as integers.

When a particular API version is requested, operations which are part of that API version behave as specified in that API version. Operations which are not part of the specified API version behave as they would had the API version not been specified at all. Operations whose behavior is subject to the configured API version are commands including command arguments, queries, aggregation pipeline stages and arguments.

Applications may request that the server rejects all operations which are not part of the specified API version by setting the :strict option:

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

For example, since the :tailable option is not part of the server API version 1, the following query would fail:

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))

Applications may request that the server rejects all operations which are deprecated in the specified API version by setting the :deprecation_errors option:

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

Note that, as of this writing, there are no deprecated operations in API version "1".

If the server API parameters have been defined on a Client object, they will be sent by the client as part of each [1] executed operation.

MongoDB servers prior to 5.0 do not recognize the API parameters, and will produce a variety of errors should the application configure them. The Ruby driver will send the API parameters to all MongoDB 3.6 and newer servers, but the API parameters should only be configured when the application is communicating with MongoDB 5.0 or newer servers. The API parameters cannot be sent to MongoDB 3.4 and older servers that use the legacy wire protocol; if an application configures the API parameters and connects to MongoDB 3.4 or older servers, the driver will produce an error on every operation.

The command helper permits the application to send manually constructed commands to the server. If the client is not configured with server API parameters, the command helper may be used to issue commands with API parameters:

client.database.command(
  ping: 1,
  apiVersion: "1",
  apiStrict: false,
  apiDeprecationErrors: false,
)

If the client is configured with server API parameters, the command helper may not be used to issue commands with server API parameters. This includes the case when the server API parameters provided to the client and to the command helper are identical. If a client is constructed with server API parameters, to send different API parameters (or none at all) a new client must be constructed, either from scratch or using the with method.

The server API parameters may only be specified on the client level. They may not be specified on the database, collection, session, transaction or individual operation level.

Development Configuration

Driver's default configuration is suitable for production deployment. In development, some settings can be adjusted to provide a better developer experience.

• :server_selection_timeout: set this to a low value (e.g., 1) if your MongoDB server is running locally and you start it manually. A low server selection timeout will cause the driver to fail quickly when there is no server running.

Production Configuration

Please consider the following when deploying an application using the Ruby driver in production:

• As of driver version 2.11, the :min_pool_size client option is completely respected - the driver will create that many connections to each server identified as a standalone, primary or secondary. In previous driver versions the driver created connections on demand. Applications using :min_pool_size will see an increase in the number of idle connections to all servers as of driver version 2.11, and especially to secondaries in replica set deployments and to nodes in sharded clusters.

• If the application is reverse proxied to by another web server or a load balancer, server_selection_timeout should generally be set to a lower value than the reverse proxy's read timeout. For exampe, Heroku request timeout is 30 seconds and is not configurable; if deploying a Ruby application using MongoDB to Heroku, consider lowering server selection timeout to 20 or 15 seconds.

Feature Flags

The following is a list of feature flags that the Mongo Ruby Driver provides:

These feature flags can be set directly on the Mongo module or using the options method:

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