For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
Docs Menu
Docs Home
/ /
Ruby Driver
Docs Home
/
Client Libraries
/
Ruby
/
Ruby Driver
Docs Home
/
Client Libraries
/
Ruby
/
Ruby Driver

Specify Connection Options

Overview

This section describes the MongoDB connection and authentication options available in Ruby driver. You can configure your connection by using either the connection URI (also called a connection string) or by passing arguments to the Mongo::Client constructor.

Using the Connection URI

If you pass a connection URI to the Mongo::Client constructor, you can include connection options in the string as <name>=<value> pairs. In the following example, the connection URI contains the connectTimeoutMS option with a value of 60000 and the tls option with a value of true:

uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true"
client = Mongo::Client.new(uri)

Using a Mongo::Client

You can pass connection options as arguments to the Mongo::Client constructor instead of including them in your connection URI. When you configure your connection this way, it easier for you to change settings at runtime and catch errors during compilation. The following example shows how to use the Mongo::Client constructor to set connection options:

uri = "mongodb://<hostname>:<port>"
client = Mongo::Client.new(uri, connect_timeout: 60000, ssl: true)

Connection Options

The following sections describe the connection options available in the Ruby driver.

Network Compression

Connection Option
Description

: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 zstd, snappy, and zlib.

Data Type: Array<String>
Default: none
Client Example: compressors: ['snappy', 'zstd', 'zlib']
Connection URI Example: compressors=snappy,zstd,zlib

:zlib_compression_level

The Zlib compression level to use, if using compression. This option accepts an integer value between -1 and 9:

- -1: zlib uses its default compression level (usually 6).
- 0: No compression.
- 1: Fastest speed but lowest compression.
- 9: Best compression but slowest speed.

For more information, see Ruby's ZLib module documentation.

Data Type: Integer
Default: None
Client Example: zlib_compression_level: 3
Connection URI Example: zlibCompressionLevel=3

Timeouts

Connection Option
Description

:connect_timeout

The number of seconds to wait to establish a socket connection before raising an exception. This timeout is also used for SRV DNS record resolution.

nil and 0 mean no timeout. Client creation will fail with an error if an invalid timeout value is passed (such as a negative value or a non-numeric value).

Data Type: Float
Default: 10.0
Client Example: connect_timeout: 10.0
Connection URI Example: connectTimeoutMS=10000

:timeout_ms

The number of milliseconds to wait for an operation to execute before raising an exception.

0 means no timeout. Client creation will fail with an error if an invalid timeout value is passed (such as a negative value or a non-numeric value).

Data Type: Integer
Default: none
Client Example: timeout_ms: 5000
Connection URI Example: timeoutMS=5000

Server Selection

Connection Option
Description

:load_balanced

Whether to expect to connect to a load balancer.

Data Type: Boolean
Default: false
Client Example: load_balanced: { true }
Connection URI Example: N/A

:server_monitoring_mode

The server monitoring protocol to use. When this option is set to :auto, the monitoring mode is determined by the environment in which the driver is running. The driver uses polling mode in function-as-a-service (FaaS) environments, such as AWS Lambda, and the streaming mode in other environments.

Data Type: Symbol
Default: :auto
Client Example: server_monitoring_mode: :poll
Connection URI Example: serverMonitoringMode=poll

:server_selection_timeout

The maximum amount of time, in seconds, the driver waits for server selection to succeed before throwing an exception.

Data Type: Integer
Default: 30
Client Example: server_selection_timeout: 30
Connection URI Example: serverSelectionTimeoutMS=30000

For more information on server selection, see the Server Selection guide.

Authentication

Connection Option
Description

:auth_mech

The mechanism that the Ruby driver uses to authenticate the application.

Data Type: Symbol
Default: :scram256
nil if user credentials are not supplied.
Client Example: auth_mech: :scram256
Connection URI Example: authMechanism=SCRAM-SHA-256

:auth_mech_properties

Options specific to the authentication mechanism. This option isn't needed for all authentication mechanisms.

Data Type: Hash
Default: When you use the GSSAPI authentication mechanism,
the default properties are {service_name: "mongodb"}.
Otherwise, the default is nil.
Client Example: auth_mech_properties: {aws_session_token: '12345'}
Connection URI Example: authMechanismProperties=AWS_SESSION_TOKEN:12345

:auth_source

The database to authenticate against.

Data Type: String
Default: admin, if credentials are supplied
Client Example: auth_source: admin
Connection URI Example: authSource=admin

:user

The username for authentication. When this option is included in a connection URI, you must percent-encode it.

Data Type: String
Default: none
Client Example: user: my+user
Connection URI Example: username=my+user

:password

The password for authentication. When this option is included in a connection URI, you must percent-encode it.

Data Type: String
Default: none
Client Example: password: strong+password
Connection URI Example: password=strong+password

Read and Write Operations

Connection Option
Description

:replica_set

Specifies the name of the replica set to connect to.

Data Type: String
Default: none
Client Example: replica_set: 'myRS'
Connection URI Example: replicaSet=myRS

:direct_connection

Whether to connect directly to the specified host

Data Type: Boolean
Default: false
Client Example: direct_connection: true
Connection URI Example: directConnection=true

:enable_overload_retargeting

Whether the driver deprioritizes a server that returns an overload error, reducing the likelihood of retrying on the same overloaded server.

Data Type: Boolean
Default: false
Client Example: enable_overload_retargeting: true
Connection URI Example: enableOverloadRetargeting=true

:max_adaptive_retries

The maximum number of retries to attempt when the driver encounters overload errors.

Data Type: Integer
Default: 2
Client Example: max_adaptive_retries: 3
Connection URI Example: maxAdaptiveRetries=3

:read

The read preference options. For more information, see Read Preference in the MongoDB Server manual.

Data Type: Hash
Default: { mode: :primary }
Client Example: read: { mode: :primary }
Connection URI Example: readPreference=primary

:read_concern

Specifies the read concern options. For more information, see Read Concern in the MongoDB Server manual.

Data Type: Hash
Default: none
Client Example: read: { level: :majority }
Connection URI Example: readConcern=majority

:write_concern

Specifies the client's write concern. For more information, see Write Concern in the MongoDB Server manual.

Data Type: Hash
Default: write_concern: { w: 1 }
Client Example: write_concern: { w: 2 }
Connection URI Example: w=2

:local_threshold

The latency window, in seconds, for a replica-set member's eligibility. If a member's round trip ping takes longer than the fastest server's round-trip ping time plus this value, the server isn't eligible for selection.

Data Type: Float
Default: 0.015
Client Example: local_threshold: 0.020
Connection URI Example: localThresholdMS=20

Connection Pools

Connection Option
Description

:max_pool_size

The maximum number of concurrent connections that the pool maintains. If the number of in-use connections to a server reaches the specified value, the next request to that server waits until a connection becomes available. Setting this option to 0 creates an unlimited connection pool.

Data Type: Integer
Default: 100
Client Example: max_pool_size: 100
Connection URI Example: maxPoolSize=100

:max_connecting

The maximum number of connections that each pool can establish concurrently.

Data Type: Integer
Default: 2
Client Example: max_connecting: 2
Connection URI Example: maxConnecting=2

:min_pool_size

The minimum number of concurrent connections that the pool maintains.

Data Type: Integer
Default: 0
Client Example: min_pool_size: 1
Connection URI Example: minPoolSize=1

:max_idle_time

The maximum number of seconds that a connection can remain idle in the pool.

Data Type: Integer
Default: 0 (no limit)
Client Example: max_idle_time: 10
Connection URI Example: maxIdleTimeMS=10000

For more information on connection pools, see the Connection Pools guide.

API Documentation

For more information about Mongo::Client options for the Ruby driver, see the API documentation for Mongo::Client.

Back

Choose a Connection Target

Next

Compress Network Traffic

On this page