diff --git a/source/connect.txt b/source/connect.txt index 0d590257..f2ba6b53 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -25,4 +25,5 @@ Connect to MongoDB Create a Client Stable API Choose a Connection Target + Connection Option Configure TLS diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt new file mode 100644 index 00000000..d07be705 --- /dev/null +++ b/source/connect/connection-options.txt @@ -0,0 +1,290 @@ +.. _ruby-connection-options: + +========================== +Specify Connection Options +========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: connection string, URI, server, Atlas, settings, configure + +Overview +-------- + +This section describes the MongoDB connection and authentication options +available in {+driver-short+}. You can configure your connection by using either +the connection URI (also called a :manual:`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 ``=`` 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``: + +.. code-block:: ruby + + uri = "mongodb://:/?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: + +.. code-block:: ruby + + uri = "mongodb://:" + client = Mongo::Client.new(uri, connect_timeout: 60000, ssl: true) + +Connection Options +------------------ + +The following sections describe the connection options available in the {+driver-short+}. + +Network Compression +~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 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`` + | **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 +~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 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 +~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Connection Option + - Description + + * - **:server_selector** + - | Get the server selector. It either uses the read preference + defined in the client options or defaults to a Primary + server selector. + | + | **Data Type**: ``ServerSelector`` + | **Default**: none + | **Client Example**: ``server_selector: { mode: :secondary_preferred }`` + | **Connection URI Example**: N/A + + * - **: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`` + +Authentication +~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Connection Option + - Description + + * - **:auth_mech** + - | The mechanism that the {+driver-short+} uses to authenticate the application. + | + | **Data Type**: ``Symbol`` + | **Default**: ``nil`` if user credentials are not supplied. + | ``:scram256`` when connecting to MongoDB v4.0 or later. + | **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 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 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`` + + * - **:read** + - | The read preference options. For more information, + see :manual:`Read Preference ` in the 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 + :manual:`Read Concern ` in the 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 :manual:`Write Concern ` in the 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`` + +API Documentation +----------------- + +For more information about ``Mongo::Client`` options for the {+driver-short+}, +see the API documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ .