Skip to content

DOCS-11940: uri option compressors and zlibcompressionlevel #3519

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 11, 2018
Merged

DOCS-11940: uri option compressors and zlibcompressionlevel #3519

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 109 additions & 47 deletions source/reference/connection-string.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,13 +55,13 @@ The components of this string are:

- Required. It identifies a server
address to connect to. It identifies either a hostname, IP
address, or UNIX domain socket.
address, or UNIX domain socket.

.. include:: /includes/fact-uri-rs-hostnames.rst

For a sharded cluster, specify the hostname of the
:binary:`~bin.mongos` instance.


* - ``:port1``

Expand Down Expand Up @@ -153,7 +153,7 @@ DNS SRV record. The driver or :binary:`~bin.mongo` shell will then
query the DNS for the record to determine which hosts are running the
:binary:`~bin.mongod` instances.

.. note::
.. note::

Use of the ``+srv`` connection string modifier
automatically sets the ``ssl`` option to ``true`` for the connection.
Expand All @@ -164,9 +164,9 @@ The following example shows a typical connection string for a DNS
seedlist connection string:

.. code-block:: none

mongodb+srv://server.example.com/

The corresponding DNS configuration might resemble:

.. code-block:: none
Expand All @@ -181,7 +181,7 @@ The corresponding DNS configuration might resemble:
domain (in this example, ``example.com``) as the given hostname. If
the parent domains and hostname do not match, you will not be able to
connect.

Like the standard connection string, the DNS seedlist connection string
supports specifying options as a query string. With a DNS seedlist
connection string, you can *also* specify the following options via a
Expand Down Expand Up @@ -217,14 +217,14 @@ of the DNS entry above.
.. code-block:: none

mongodb+srv://server.example.com/?connectTimeoutMS=300000&authSource=aDifferentAuthDB

Given the override for the ``authSource``, the equivalent connection
string in the standard format would be:

.. code-block:: none

mongodb://mongodb1.example.com:27317,mongodb2.example.com:27017/?connectTimeoutMS=300000&replicaSet=mySet&authSource=aDifferentAuthDB

.. note::
The ``mongodb+srv`` option will fail if there is no available DNS
with records that correspond to the hostname identified in the
Expand Down Expand Up @@ -323,12 +323,74 @@ Connection Options
timeout, though different drivers might vary. See the
:ecosystem:`driver </drivers>` documentation.

* - .. urioption:: compressors
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rendered view:

https://docs-mongodbcom-staging.corp.mongodb.com/kay/compressors-11940/reference/connection-string.html#urioption.compressors


- Comma-delimited string of compressors to enable
network compression for communication between this
client and:

- a :binary:`~bin.mongod` instance

- a :binary:`~bin.mongos` instance.

You can specify the following compressors:

- :term:`snappy`

- :term:`zlib` (Available in MongoDB 3.6 or greater)

If you specify multiple compressors, then the order in which you list
the compressors matter as well as the communication initiator. For
example, if the client specifies the following network
compressors ``"zlib,snappy"`` and the :binary:`~bin.mongod` specifies
``"snappy,zlib"``, messages between the client and the
:binary:`~bin.mongod` uses ``zlib``.

.. important::

Messages are compressed when both parties enable network
compression. Otherwise, messages between the parties are
uncompressed.

If the parties do not share at least one common compressor,
messages between the parties are uncompressed.


* - .. urioption:: zlibCompressionLevel
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rendered view:

https://docs-mongodbcom-staging.corp.mongodb.com/kay/compressors-11940/reference/connection-string.html#urioption.zlibCompressionLevel


- An integer that specifies the compression level if using
:term:`zlib` for :urioption:`network compression <compressors>`.

You can specify an integer value ranging from ``-1`` to ``9``:

.. list-table::
:header-rows: 1
:widths: 25 75

* - Value
- Notes

* - ``-1``

- Default compression level, usually level ``6`` compression.

* - ``0``
- No compression

* - ``1`` - ``9``

- Increasing level of compression but at the cost of speed, with:

- ``1`` providing the best speed but least compression, and

- ``9`` providing the best compression but at the slowest speed.

.. _connection-pool-options:

Connection Pool Options
~~~~~~~~~~~~~~~~~~~~~~~

Most drivers implement some kind of connection pool handling.
Most drivers implement some kind of connection pool handling.
Some drivers do not support connection
pools. See your :ecosystem:`driver </drivers>` documentation
for more information on the connection pooling implementation. These
Expand Down Expand Up @@ -460,7 +522,7 @@ isolation for their reads from replica sets.
* - .. urioption:: readConcernLevel

- The level of isolation. Can accept one of the following values:

- :readconcern:`local <"local">`
- :readconcern:`majority <"majority">`
- :readconcern:`linearizable <"linearizable">`
Expand Down Expand Up @@ -488,8 +550,8 @@ on a per-connection basis in the connection string:
* - .. urioption:: readPreference

- Specifies the :term:`replica set` read preference for this
connection.
connection.

The read preference values are the following:

- :readmode:`primary`
Expand All @@ -507,33 +569,33 @@ on a per-connection basis in the connection string:
.. include:: /includes/extracts/transactions-read-pref.rst

* - .. urioption:: maxStalenessSeconds

- .. versionadded:: 3.4

Specifies, in seconds, how stale a secondary can be before the client
stops using it for read operations. For details, see:
:ref:`replica-set-read-preference-max-staleness`.

By default, there is no maximum staleness and clients will not consider a
secondary's lag when choosing where to direct a read operation.

The minimum :urioption:`maxStalenessSeconds` value is 90
seconds. Specifying a value between 0 and 90 seconds will produce
an error. MongoDB drivers treat a ``maxStalenessSeconds`` value
of ``-1`` as "no max staleness", the same as if
``maxStalenessSeconds`` is omitted.

.. important::
To use ``maxStalenessSeconds``, all of the
MongoDB instances in your deployment must be using MongoDB 3.4 or
later. If any instances are on an earlier version of MongoDB, the
driver or :binary:`~bin.mongos` will raise an error.

The following specifies a maxStalenessSeconds value of 120 seconds
with the :readmode:`secondary` read preference mode:

.. code-block:: none

mongodb://host.example.com/?readPreference=secondary&maxStalenessSeconds=120

* - .. urioption:: readPreferenceTags
Expand Down Expand Up @@ -615,30 +677,30 @@ Authentication Options
* - .. urioption:: authMechanismProperties

- Specify properties for the specified :urioption:`authMechanism`
as a comma-separated list of colon-separated key-value pairs.
For example:
as a comma-separated list of colon-separated key-value pairs.
For example:

.. code-block:: shell
:copyable: false

authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:true

The :urioption:`authMechanismProperties` option is only supported
when :urioption:`authMechanism` is
The :urioption:`authMechanismProperties` option is only supported
when :urioption:`authMechanism` is
:ref:`GSSAPI <security-auth-kerberos>`. Possible values are:

``SERVICE_NAME:<string>``
Set the Kerberos service name when connecting to Kerberized
MongoDB instances. This value must match the service name set
on MongoDB instances to which you are connecting.
on MongoDB instances to which you are connecting.

``SERVICE_NAME`` defaults to ``mongodb`` for all clients and
``SERVICE_NAME`` defaults to ``mongodb`` for all clients and
MongoDB instances. If you change the
:parameter:`saslServiceName` setting on a MongoDB instance, you
must set ``SERVICE_NAME`` to match that setting.

``CANONICALIZE_HOST_NAME:true|false``
Canonicalize the hostname of the client host machine when
Canonicalize the hostname of the client host machine when
connecting to the Kerberos server. This may be required when
hosts report different hostnames than what is in the Kerberos
database. Defaults to ``false``.
Expand All @@ -660,10 +722,10 @@ Authentication Options
must set :urioption:`gssapiServiceName` to match that setting.

:urioption:`gssapiServiceName` is a deprecated aliases for
:urioption:`authMechanismProperties=SERVICE_NAME:mongodb
<authMechanismProperties>`. For more information on which
options your driver supports and their relative priority to each
other, reference the documentation for your preferred driver
:urioption:`authMechanismProperties=SERVICE_NAME:mongodb
<authMechanismProperties>`. For more information on which
options your driver supports and their relative priority to each
other, reference the documentation for your preferred driver
version.

.. _selection-discovery-options:
Expand All @@ -678,16 +740,16 @@ or write operations.
.. list-table::
:header-rows: 1
:widths: 30 70

* - Connection Option
- Description

* - .. urioption:: localThresholdMS

- The size (in milliseconds) of the latency window for selecting
among multiple suitable MongoDB instances. *Default*: 15
milliseconds.

All drivers use :urioption:`localThresholdMS`. Use the
``localThreshold`` alias when specifying the latency window size
to :binary:`~bin.mongos`.
Expand All @@ -706,7 +768,7 @@ or write operations.
error. When ``false``, the driver blocks and searches for a
server up to the :urioption:`serverSelectionTimeoutMS` value.
*Default*: ``true``.

Multi-threaded drivers and :binary:`~bin.mongos` do not support
:urioption:`serverSelectionTryOnce`.

Expand All @@ -716,13 +778,13 @@ or write operations.
checks the state of the MongoDB deployment. Specify the interval
(in milliseconds) between checks, counted from the end of the
previous check until the beginning of the next one.

*Default*:

- Single-threaded drivers: 60 seconds.
- Multi-threaded drivers: 10 seconds.
:binary:`~bin.mongos` does not support changing the frequency of

:binary:`~bin.mongos` does not support changing the frequency of
the heartbeat checks.

Miscellaneous Configuration
Expand All @@ -736,23 +798,23 @@ Miscellaneous Configuration
- Description

* - .. urioption:: appName
- Specify a custom app name. The app name appears in

- Specify a custom app name. The app name appears in

- :binary:`~bin.mongod` and :binary:`~bin.mongos` :doc:`logs
</reference/log-messages>`,

- the :data:`currentOp.appName` field in the :dbcommand:`currentOp`
command and :method:`db.currentOp()` method output,

- the :data:`system.profile.appName` field in the :doc:`database
profiler </reference/database-profiler>` output.

If you do not specify a custom app name, the :binary:`~bin.mongo`
shell uses the default "``MongoDB Shell``".

.. versionadded:: 4.0

* - .. urioption:: retryWrites

- Enable :ref:`retryable writes <retryable-writes>`.
Expand Down Expand Up @@ -830,7 +892,7 @@ UNIX Domain Socket
~~~~~~~~~~~~~~~~~~

Use a URL encoded connection string when connecting to a UNIX domain
socket.
socket.

The following connects to a UNIX domain socket with file path
``/tmp/mongodb-27017.sock``:
Expand Down