<commit_before>=================
Creating a Client
=================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

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.

.. code-block:: ruby

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

.. _ruby-driver-connect-replica-set:

To connect to a :manual:`replica set</replication/>`,
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.

.. code-block:: ruby

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

.. _ruby-driver-connect-sharded-cluster:

To create a client to a :manual:`sharded cluster</sharding/>`,
pass one or more :manual:`mongos</reference/program/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.

.. code-block:: ruby

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

.. _ruby-driver-client-options:

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 :manual:`Connection URI reference
</reference/connection-string/>`. 

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

.. list-table::
   :header-rows: 1
   :widths: 40 105

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

.. list-table::
   :header-rows: 1
   :widths: 25 40 10 15

   * - 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``.

       .. code-block:: ruby

         { :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``.

       .. code-block:: ruby

         { :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 <https://github.com/mongodb/specifications/blob/
  master/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst#socket-timeout-for-monitoring
  -is-connecttimeoutms>`_ 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 <https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst#socket-timeout-for-monitoring-is-connecttimeoutms>`_
  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 :manual:`elections</core/replica-set-elections/>`
  during a failover into account. See the 
  `serverSelectionTimeoutMS specification
  <https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#serverselectiontimeoutms>`_
  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 
  <https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#localthresholdms>`_.

``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 <https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst>`_ 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:

.. code-block:: ruby

    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``:

.. code-block:: ruby

    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:

.. code-block:: ruby

    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:

.. code-block:: ruby

    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``)
<commit_msg>RUBY-1282 Add SRV record support to Tutorial documentation<commit_after>=================
Creating a Client
=================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

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.

.. code-block:: ruby

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

.. _ruby-driver-connect-replica-set:

To connect to a :manual:`replica set</replication/>`,
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.

.. code-block:: ruby

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

.. _ruby-driver-connect-sharded-cluster:

To create a client to a :manual:`sharded cluster</sharding/>`,
pass one or more :manual:`mongos</reference/program/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.

.. code-block:: ruby

  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:

.. code-block:: ruby

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

.. _ruby-driver-client-options:

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 :manual:`Connection URI reference
</reference/connection-string/>`. 

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

.. list-table::
   :header-rows: 1
   :widths: 40 105

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

.. list-table::
   :header-rows: 1
   :widths: 25 40 10 15

   * - 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``.

       .. code-block:: ruby

         { :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``.

       .. code-block:: ruby

         { :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 <https://github.com/mongodb/specifications/blob/
  master/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst#socket-timeout-for-monitoring
  -is-connecttimeoutms>`_ 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 <https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst#socket-timeout-for-monitoring-is-connecttimeoutms>`_
  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 :manual:`elections</core/replica-set-elections/>`
  during a failover into account. See the 
  `serverSelectionTimeoutMS specification
  <https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#serverselectiontimeoutms>`_
  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 
  <https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#localthresholdms>`_.

``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 <https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst>`_ 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:

.. code-block:: ruby

    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``:

.. code-block:: ruby

    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:

.. code-block:: ruby

    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:

.. code-block:: ruby

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

{'fraction_non_alphanumeric': 0.11084058826422705, 'fraction_numerical': 0.011042250750086075, 'mean_word_length': 3.058993811139948, 'pattern_counts': {'":': 0, '<': 31, '<?xml version=': 0, '>': 125, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 20, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1680702', 'n_tokens_mistral': 11865, 'n_tokens_neox': 11122, 'n_words': 4550}