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

.. default-domain:: mongodb

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

Using ``Mongo::Client``
-----------------------

To connect to a MongoDB cluster, create a ``Mongo::Client`` object.
Provide a list of hosts and options or a connection URI to the
``Mongo::Client`` constructor. The client's selected 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

   * - appName=String
     - ``:app_name => String``

   * - authMechanism=String
     - ``:auth_mech => Symbol``

   * - authMechanismProperties=Strings
     - ``{ :auth_mech_properties => { :service_realm => String, :canonicalize_host_name => true|false, :service_name => String } }``

       Specified as comma-separated key:value pairs, e.g. ``"SERVICE_REALM:foo,CANONICALIZE_HOST_NAME:TRUE"``.

   * - authSource=String
     - ``:auth_source => String``

   * - compressors=Strings
     - ``:compressors => Array<String>``

       Specified as a comma-separated list. Note that the Ruby driver only supports zlib
       compression; however, other drivers may support snappy. For maximum compatibility with
       drivers, specify ``"snappy,zlib"``; if compatibility with other drivers is not a concern,
       specify ``"zlib".`` Compression is not enabled by default and when using MongoDB 4.0 and
       earlier, so zlib compression must be manually enabled on the server in order for the Ruby
       driver to compress wire protocol data.

   * - connect=String
     - ``:connect => Symbol``

   * - connectTimeoutMS=Integer
     - ``:connect_timeout => Float``

   * - fsync=Boolean
     - ``{ :write => { :fsync => true|false }}``

   * - heartbeatFrequencyMS=Integer
     - ``:heartbeat_frequency => Float``

   * - journal=Boolean
     - ``{ :write => { :j => true|false }}``

   * - localThresholdMS=Integer
     - ``:local_threshold => Float``

   * - maxIdleTimeMS=Integer
     - ``:max_idle_time => Float``

   * - maxStalenessSeconds=Integer
     - ``:max_staleness => Float``

   * - maxPoolSize=Integer
     - ``:max_pool_size => Integer``

   * - minPoolSize=Integer
     - ``:min_pool_size => Integer``

   * - readConcernLevel=String
     - ``:read_concern => Hash``

   * - readPreference=String
     - ``{ :read => { :mode => Symbol }}``

   * - readPreferenceTags=Strings
     - ``{ :read => { :tag_sets => Array<Hash> }}``

       Each instance of the readPreferenceTags field is a comma-separated key:value pair which will appear in the :tag_sets array in the order they are specified. For instance, ``"readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny"`` will be converted to ``[ { 'dc' => 'ny', 'rack' => '1' }, { 'dc' => 'ny' }]``.

   * - replicaSet=String
     - ``:replica_set => String``

   * - retryWrites=Boolean
     - ``:retry_writes => boolean``

   * - serverSelectionTimeoutMS=Integer
     - ``:server_selection_timeout => Float``

   * - socketTimeoutMS=Integer
     - ``:socket_timeout => Float``

   * - ssl=Boolean
     - ``:ssl => true|false``

   * - tls=Boolean
     - ``:ssl => boolean``

   * - tlsAllowInvalidCertificates=Boolean
     - ``:ssl_verify_certificate => boolean``

       Because ``tlsAllowInvalidCertificates`` uses ``true`` to signify that verification
       should be disabled and ``ssl_verify_certificate`` uses ``false`` to signify that
       verification should be disabled, the boolean is inverted before being used to set
       ``ssl_verify_certificate``.

   * - tlsAllowInvalidHostnames=Boolean
     - ``:ssl_verify_hostname => boolean``

       Because ``tlsAllowInvalidHostnames`` uses ``true`` to signify that verification
       should be disabled and ``ssl_verify_hostname`` uses ``false`` to signify that
       verification should be disabled, the boolean is inverted before being used to set
       ``ssl_verify_hostname``.

   * - tlsCAFile=String
     - ``:ssl_ca_cert => String``

   * - tlsCertificateKeyFile=String
     - ``:ssl_cert => String``

   * - tlsCertificateKeyFile=String
     - ``:ssl_key => String``

   * - tlsCertificateKeyFilePassword=String
     - ``:ssl_key_pass_phrase => String``

   * - tlsInsecure=Boolean
     - ``:ssl_verify => boolean``<commit_msg>Fix RUBY-1766 Typo in tlsAllowInvalidCertificates and tlsAllowInvalidHostnames<commit_after>=================
Creating a Client
=================

.. default-domain:: mongodb

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

Using ``Mongo::Client``
-----------------------

To connect to a MongoDB cluster, create a ``Mongo::Client`` object.
Provide a list of hosts and options or a connection URI to the
``Mongo::Client`` constructor. The client's selected 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

   * - appName=String
     - ``:app_name => String``

   * - authMechanism=String
     - ``:auth_mech => Symbol``

   * - authMechanismProperties=Strings
     - ``{ :auth_mech_properties => { :service_realm => String, :canonicalize_host_name => true|false, :service_name => String } }``

       Specified as comma-separated key:value pairs, e.g. ``"SERVICE_REALM:foo,CANONICALIZE_HOST_NAME:TRUE"``.

   * - authSource=String
     - ``:auth_source => String``

   * - compressors=Strings
     - ``:compressors => Array<String>``

       Specified as a comma-separated list. Note that the Ruby driver only supports zlib
       compression; however, other drivers may support snappy. For maximum compatibility with
       drivers, specify ``"snappy,zlib"``; if compatibility with other drivers is not a concern,
       specify ``"zlib".`` Compression is not enabled by default and when using MongoDB 4.0 and
       earlier, so zlib compression must be manually enabled on the server in order for the Ruby
       driver to compress wire protocol data.

   * - connect=String
     - ``:connect => Symbol``

   * - connectTimeoutMS=Integer
     - ``:connect_timeout => Float``

   * - fsync=Boolean
     - ``{ :write => { :fsync => true|false }}``

   * - heartbeatFrequencyMS=Integer
     - ``:heartbeat_frequency => Float``

   * - journal=Boolean
     - ``{ :write => { :j => true|false }}``

   * - localThresholdMS=Integer
     - ``:local_threshold => Float``

   * - maxIdleTimeMS=Integer
     - ``:max_idle_time => Float``

   * - maxStalenessSeconds=Integer
     - ``:max_staleness => Float``

   * - maxPoolSize=Integer
     - ``:max_pool_size => Integer``

   * - minPoolSize=Integer
     - ``:min_pool_size => Integer``

   * - readConcernLevel=String
     - ``:read_concern => Hash``

   * - readPreference=String
     - ``{ :read => { :mode => Symbol }}``

   * - readPreferenceTags=Strings
     - ``{ :read => { :tag_sets => Array<Hash> }}``

       Each instance of the readPreferenceTags field is a comma-separated key:value pair which will appear in the :tag_sets array in the order they are specified. For instance, ``"readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny"`` will be converted to ``[ { 'dc' => 'ny', 'rack' => '1' }, { 'dc' => 'ny' }]``.

   * - replicaSet=String
     - ``:replica_set => String``

   * - retryWrites=Boolean
     - ``:retry_writes => boolean``

   * - serverSelectionTimeoutMS=Integer
     - ``:server_selection_timeout => Float``

   * - socketTimeoutMS=Integer
     - ``:socket_timeout => Float``

   * - ssl=Boolean
     - ``:ssl => true|false``

   * - tls=Boolean
     - ``:ssl => boolean``

   * - tlsAllowInvalidCertificates=Boolean
     - ``:ssl_verify_certificate => boolean``

       Because ``tlsAllowInvalidCertificates`` uses ``true`` to signify that verification
       should be disabled and ``ssl_verify_certificate`` uses ``false`` to signify that
       verification should be enabled, the boolean is inverted before being used to set
       ``ssl_verify_certificate``.

   * - tlsAllowInvalidHostnames=Boolean
     - ``:ssl_verify_hostname => boolean``

       Because ``tlsAllowInvalidHostnames`` uses ``true`` to signify that verification
       should be disabled and ``ssl_verify_hostname`` uses ``false`` to signify that
       verification should be enabled, the boolean is inverted before being used to set
       ``ssl_verify_hostname``.

   * - tlsCAFile=String
     - ``:ssl_ca_cert => String``

   * - tlsCertificateKeyFile=String
     - ``:ssl_cert => String``

   * - tlsCertificateKeyFile=String
     - ``:ssl_key => String``

   * - tlsCertificateKeyFilePassword=String
     - ``:ssl_key_pass_phrase => String``

   * - tlsInsecure=Boolean
     - ``:ssl_verify => boolean``
{'fraction_non_alphanumeric': 0.1440188315857051, 'fraction_numerical': 0.017690277480562094, 'mean_word_length': 3.4283006948831334, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 111, 'https://': 0, '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': '2130203', 'n_tokens_mistral': 4459, 'n_tokens_neox': 4179, 'n_words': 1307}