DOCSP-45812 Connection Options

source/connect.txt

@@ -25,4 +25,5 @@ Connect to MongoDB
    Create a Client </connect/mongoclient>
    Stable API </connect/stable-api>
    Choose a Connection Target </connect/connection-targets>
+   Connection Option </connect/connection-options>
    Configure TLS </connect/tls>

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 </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``:
+
+.. code-block:: ruby
+
+   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:
+
+.. code-block:: ruby
+
+   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 {+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<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 <https://ruby-doc.org/stdlib-2.7.0/libdoc/zlib/rdoc/Zlib.html>`__ 
+         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 <https://datatracker.ietf.org/doc/html/rfc3986#section-2.1>`__ 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 <https://datatracker.ietf.org/doc/html/rfc3986#section-2.1>`__ 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 </core/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 </reference/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 </reference/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>`__ .