Skip to content
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

DOCSP-41123: cxn options #40

Merged
merged 7 commits into from
Aug 21, 2024
Merged

DOCSP-41123: cxn options #40

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
8921a0f
DOCSP-41123: connection options
rustagir Aug 20, 2024
b386c7e
fix
rustagir Aug 20, 2024
f13400c
fix
rustagir Aug 20, 2024
66bad83
wip
rustagir Aug 20, 2024
e040907
MM suggestion
rustagir Aug 20, 2024
c426518
RL tech PR fixes 1
rustagir Aug 21, 2024
580e9ec
spacing fix
rustagir Aug 21, 2024
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
11 changes: 6 additions & 5 deletions source/connect.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,10 +39,11 @@ This page contains code examples that show how to use the
{+driver-short+} to connect your application to MongoDB by specifying
various settings.

.. .. tip::
..
.. To learn more about the connection options on this page, see the link
.. provided in each section.
.. tip:: Connection Options

To learn more about the connection options on this page, see the link
provided in each section. You can also view the
:ref:`kotlin-sync-connection-options` guide to learn more.

To use a connection example from this page, copy the code example into the
:ref:`sample application <kotlin-sync-connect-sample>` or your own application.
Expand Down Expand Up @@ -188,4 +189,4 @@ The following code shows how to specify Stable API settings within a

val client = MongoClient.create(settings)

.. To learn more about the {+stable-api+}, see :ref:`kotlin-sync-stable-api`.
To learn more about the {+stable-api+}, see :ref:`kotlin-sync-stable-api`.
316 changes: 314 additions & 2 deletions source/connect/connection-options.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Specify Connection Options
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:depth: 2
:class: singlecol

.. facet::
Expand All @@ -18,4 +18,316 @@ Specify Connection Options
:keywords: connection string, URI, server, Atlas, settings, configure

rustagir marked this conversation as resolved.
Show resolved Hide resolved
Overview
--------
--------

This section describes the MongoDB connection and authentication options
available in the {+driver-short+}. You can configure your connection by
setting options in either the connection URI or within a
``MongoClientSettings`` instance.

.. _kotlin-sync-connection-uri-settings:

Set Options in the Connection URI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you pass a connection URI to the ``MongoClient.create()`` method, 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:: kotlin

val uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true"
val mongoClient = MongoClient.create(uri)

.. _kotlin-sync-mongoclientsettings:

Set Options in MongoClientSettings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can set connection options in a ``MongoClientSettings`` instance by
using methods from the ``MongoClientSettings.Builder`` class, then passing
the settings object to the ``MongoClient.create()`` method.

Configuring the connection this way makes it easier to
change settings at runtime and can help you catch errors at compile time.

Copy link
Member

Choose a reason for hiding this comment

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

Recommend adding a section just using the MongoClientSettings.builder eg:

        MongoClientSettings
            .builder()
            .applyToClusterSettings { it.hosts(listOf(ServerAddress("127.0.0.1"))) }
            .applyToSocketSettings { it.connectTimeout(60000, TimeUnit.MILLISECONDS) }
            .applyToSslSettings { it.enabled(true) }
            .build()

Then give the example below mixing a connection string and settings.

The following example shows how to set options when creating a
``MongoClientSettings`` instance:

.. code-block:: kotlin

val uri = "<connection string>"

val settings = MongoClientSettings.builder()
.applyConnectionString(ConnectionString(uri))
.retryWrites(true)
.build()

val mongoClient = MongoClient.create(settings)

Connection Options
------------------

The following sections describe the connection options available in the
{+driver-short+}. Each option shows the option-value pair you can use in a
connection URI and, if available, the driver method to set it within a
``MongoClientSettings`` instance.

Network Compression
~~~~~~~~~~~~~~~~~~~

.. list-table::
:header-rows: 1
:widths: 30 70

* - Connection Option
- Description

* - **compressors**
- | The preferred compression types, in order, for wire-protocol messages sent to
or received from the server. The driver uses the first of these compression types
that the server supports.
|
| **Data Type**: comma-delimited string
| **MongoClientSettings**: ``compressorList(listOf(<MongoCompressor>))``
| **Connection URI**: ``compressors=snappy,zstd,zlib``

* - **zlibCompressionLevel**
- | The compression level for zlib to use. This option accepts
an integer value between ``-1`` and ``9``, corresponding to the
following settings:
|
| - **-1:** (Default). zlib uses its default compression level (usually ``6``).
| - **0:** No compression.
| - **1:** Fastest speed but lowest compression.
| - **9:** Best compression but slowest speed.
|
| **Data Type**: integer
| **Default**: ``-1``
| **MongoClientSettings**: ``compressorList(listOf(zlib.withProperty(MongoCompressor.LEVEL, 3)))``
| **Connection URI**: ``zlibCompressionLevel=3``

Timeouts
~~~~~~~~

.. list-table::
:header-rows: 1
:widths: 30 70

* - Connection Option
- Description

* - **connectTimeoutMS**
- | The time in milliseconds to attempt a connection before timing out.
|
| **Data Type**: integer
| **Default**: ``10000``
| **MongoClientSettings**:

.. code-block:: kotlin

applyToSocketSettings{ builder ->
builder.connectTimeout(10, TimeUnit.SECONDS)
}

| **Connection URI**: ``timeoutMs=10000``

* - **socketTimeoutMS**
- | The time in milliseconds to attempt a send or receive on a
connection before the attempt times out.
|
| **Data Type**: integer
| **Default**: no timeout
| **MongoClientSettings**:

.. code-block:: kotlin

applyToSocketSettings{ builder ->
builder.readTimeout(5, TimeUnit.SECONDS)
}

| **Connection URI**: ``socketTimeoutMS=5000``

Server Selection
~~~~~~~~~~~~~~~~

.. list-table::
:header-rows: 1
:widths: 30 70

* - Connection Option
- Description

* - **serverSelectionTimeoutMS**
- | The maximum amount of time, in milliseconds, the driver waits
for server selection to succeed before throwing an
exception.
|
| **Data Type**: integer
| **Default**: ``30000``
| **MongoClientSettings**:

.. code-block:: kotlin

applyToClusterSettings{ builder ->
builder.serverSelectionTimeout(30, TimeUnit.SECONDS)
}

| **Connection URI**: ``serverSelectionTimeoutMS=30000``

Authentication
~~~~~~~~~~~~~~

.. TODO To learn more about authentication options, see the :ref:`kotlin-sync-auth` guide.

.. list-table::
:header-rows: 1
:widths: 30 70

* - Connection Option
- Description

* - **authMechanism**
- | The mechanism that the {+driver-short+} uses to authenticate
the application.
|
| **Data Type**: string
| **Default**: ``"SCRAM-SHA-256"`` when connecting to MongoDB
v4.0 or later
| **MongoClientSettings**:

.. code-block:: kotlin

credential(
MongoCredential.createScramSha256Credential(...)
)

| **Connection URI**: ``authMechanism=SCRAM-SHA-256``

* - **authMechanismProperties**
- | Options specific to the authentication mechanism. This option
isn't needed for all authentication mechanisms.
|
| **Data Type**: string
| **Connection URI**: ``authMechanismProperties=AWS_SESSION_TOKEN:12435``

* - **authSource**
- | The database to authenticate against.
|
| **Data Type**: string
| **Default**: ``"admin"``
| **Connection URI**: ``authSource=admin``

* - **username**
- | The username for authentication. When this option is included in a connection
URI, you must percent-encode it.
|
| **Data Type**: string
| **Connection URI**: ``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
| **Connection URI**: ``password=strong+password``

Read and Write Operations
~~~~~~~~~~~~~~~~~~~~~~~~~

To learn more about connecting to different types of MongoDB
deployments, see the :ref:`kotlin-sync-connection-targets` guide.

.. list-table::
:header-rows: 1
:widths: 30 70

* - Connection Option
- Description

* - **replicaSet**
- | Specifies the name of the replica set to connect to.
|
| **Data Type**: string
| **Connection URI**: ``replicaSet=myRS``

* - **directConnection**
- | Whether to connect only to the primary member of the replica set.
|
| **Data Type**: boolean
| **Default**: ``false``
| **MongoClientSettings**:

.. code-block:: kotlin

applyToClusterSettings{ builder ->
builder.mode(ClusterConnectionMode.SINGLE)
}

| **Connection URI**: ``directConnection=true``

* - **readPreference**
- | Specifies the client's read preference. For more information,
see :manual:`Read Preference </core/read-preference/>` in the
Server manual.
|
| **Data Type**: string
| **Default**: ``primary``
| **MongoClientSettings**: ``readPreference(ReadPreference.primary())``
| **Connection URI**: ``readPreference=primary``

* - **readConcern**
- | Specifies the client's read concern. For more information, see
:manual:`Read Concern </reference/read-concern/>` in the Server
manual.
|
| **Data Type**: string
| **MongoClientSettings**: ``readConcern(ReadConcern.MAJORITY)``
| **Connection URI**: ``readConcern=majority``

* - **writeConcern**
- | Specifies the client's write concern. For more information, see
:manual:`Write Concern </reference/write-concern/>` in the
Server manual.
|
| **Data Type**: string
| **MongoClientSettings**: ``writeConcern(WriteConcern.MAJORITY)``
| **Connection URI**: ``writeConcern=majority``

* - **localThresholdMS**
- | The latency window 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**: integer
| **Default**: ``15``
| **MongoClientSettings**:

.. code-block:: kotlin

applyToClusterSettings{ builder ->
builder.localThreshold(35, TimeUnit.MILLISECONDS)
}

| **Connection URI**: ``localThresholdMS=35``

Additional Information
----------------------

To view a full list of connection options, see
:manual:`Connection Strings </reference/connection-string/>` in the
Server manual.

API Documentation
~~~~~~~~~~~~~~~~~

To learn more about the classes and methods mentioned in this guide, see
the following API documentation:

- `MongoClientSettings <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html>`__
- `MongoClientSettings.Builder <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__
- `ConnectionString <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__
- `SocketSettings <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/connection/SocketSettings.html>`__
- `ClusterSettings <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/connection/ClusterSettings.html>`__
- `MongoCredential <{+java-api+}/apidocs/mongodb-driver-core/com/mongodb/MongoCredential.html>`__
Loading