From cc21e5ae97a45d6a443c2e80750e35c9bac8739e Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 30 Apr 2025 11:42:34 -0400 Subject: [PATCH 1/2] Backport v6.16 fixes --- source/connect/connection-options.txt | 463 ++++++++++++++++++++++++++ 1 file changed, 463 insertions(+) create mode 100644 source/connect/connection-options.txt diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt new file mode 100644 index 000000000..c40ae4c7f --- /dev/null +++ b/source/connect/connection-options.txt @@ -0,0 +1,463 @@ +.. _node-connection-options: + +========================== +Specify Connection Options +========================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: node.js, customize + :description: Explore connection and authentication options available in the MongoDB Node.js Driver, including settings for app name, authentication mechanisms, and TLS configurations. + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Compress Network Traffic + Stable API + Limit Server Execution Time + Connection Pools + +This section explains the MongoDB connection and authentication options +supported by the {+driver-short+} that you can set within a ``MongoClientOptions`` instance. + +For more information on setting connection options directly in a connection +string, see :manual:`Connection Strings ` in the +{+mdb-server+} manual. + +.. Check if we should add back utf-8 validation page. If so, add this line + back to validation option: + You can also set UTF-8 validation in your :ref:`Node.js code `. + +.. list-table:: + :header-rows: 1 + :widths: 30 20 10 40 + + * - Name + - Accepted Values + - Default Value + - Description + + * - **appName** + - string + - ``null`` + - Specifies the app name the driver passes to the server in the client + metadata as part of the connection handshake. The driver sends the + ``appName`` value to MongoDB when establishing the connection. + This value is recorded in the log file, the slow query logs, and + profile collections. + + * - **authMechanism** + - string + - ``null`` + - Specifies the authentication mechanism method to use for connection to the + server. If you do not specify a value, the driver uses the default mechanism, + either ``SCRAM-SHA-1`` or ``SCRAM-SHA-256`` depending on the server version. See + the :ref:`Authentication Mechanisms ` section for available + authentication mechanisms. + + * - **authMechanismProperties** + - comma separated key:value pairs, for example, "opt1:val1,opt2:val2" + - ``null`` + - Specifies other options provided for authentication, such as the option to enable + hostname canonicalization for GSSAPI. + + * - **authSource** + - string + - ``null`` + - Specifies the database that connections authenticate against. + + * - **autoSelectFamily** + - boolean + - ``true`` + - If set to ``true``, the socket attempts to connect to IPv6 and IPv4 addresses + until a connection is established. If available, the driver will select + the first IPv6 address. + + * - **autoSelectFamilyAttemptTimeout** + - non-negative integer + - ``null`` + - Specifies the amount of time in milliseconds to wait for a connection + attempt to finish before trying the next address when using the + ``autoSelectFamily`` option. If set to a positive integer less than ``10``, + the value ``10`` is used instead. + + * - **compressors** + - comma separated list of strings, for example, "snappy,zlib,zstd" + - ``null`` + - Specifies the allowed compression types for wire protocol messages + sent to or received from the server. See :ref:`node-network-compression` + for more information. + + * - **connectTimeoutMS** + - non-negative integer + - ``30000`` + - Specifies the amount of time in milliseconds to wait to establish a single TCP + socket connection to the server before raising an error. Specifying + ``0`` means your application sets an infinite socket timeout when establishing a socket. + + * - **directConnection** + - boolean + - ``false`` + - Specifies whether to force dispatch **all** operations to the host + specified in the connection URI. + + * - **enableUtf8Validation** + - boolean + - ``true`` + - + Specifying ``true`` enables UTF-8 validation for the + connection. MongoDB throws an error when + it attempts to serialize string data that contains invalid + UTF-8 characters to BSON. This applies to both document keys and + document values, this validation adds processing overhead. + + Specifying ``false`` disables UTF-8 validation for the + connection. MongoDB does not throw errors when + data contains invalid UTF-8 data. If you disable validation, + your application avoids the validation processing overhead. + **Editing data** while validation is disabled + can result in loss of data. Disabling UTF-8 validation is a + temporary workaround to query or export data only. + + To learn more about UTF-8 characters, + see `UTF-8 `__ on Wikipedia. + + * - **heartbeatFrequencyMS** + - integer greater than or equal to 500 + - ``null`` + - Specifies the interval, in milliseconds, between regular server monitoring checks. + + * - **loadBalanced** + - boolean + - ``null`` + - Specifies whether the driver is connecting to a load balancer. + + * - **localThresholdMS** + - non-negative integer + - ``15`` + - Specifies the size of the latency window, in milliseconds, on round trip time for + selecting between suitable servers. Specifying ``0`` means no wait, + meaning the fastest available server. + + * - **maxIdleTimeMS** + - non-negative integer + - ``0`` + - Specifies the amount of time, in milliseconds, a connection can be idle before it's closed. + Specifying ``0`` means no minimum. + + * - **maxPoolSize** + - non-negative integer + - ``100`` + - Specifies the maximum number of clients or connections the driver + can create in its connection pool. This count includes connections + in use. + + * - **maxConnecting** + - non-negative integer + - ``2`` + - Specifies the maximum number of connections a driver's connection + pool may be establishing concurrently. + + * - **maxStalenessSeconds** + - -1, or an integer greater than or equal 90 + - ``null`` + - Specifies the maximum replication lag, in wall clock time, that + a secondary can experience and still be eligible for server selection. + Specifying ``-1`` means no maximum. + + * - **minPoolSize** + - non-negative integer + - ``0`` + - Specifies the number of connections the driver creates and + maintains in the connection pool even when no operations are occurring. + This count includes connections in use. + + * - **proxyHost** + - string + - ``null`` + - Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or domain + name. + + * - **proxyPort** + - non-negative integer + - ``null`` + - Specifies the TCP port number of the SOCKS5 proxy server. If you + set the ``proxyHost`` option, the value of this option defaults + to ``1080``. + + * - **proxyUsername** + - string + - ``null`` + - Specifies the username for authentication to the SOCKS5 + proxy server. If you set + this option to a zero-length string, the driver ignores it. + + * - **proxyPassword** + - string + - ``null`` + - Specifies the password for authentication to the SOCKS5 + proxy server. If you set + this option to a zero-length string, the driver ignores it. + + * - **readConcernLevel** + - string + - ``null`` + - Specifies the default read concern for the client. See :ref:`read concern + ` for more information. + + * - **readPreference** + - string + - ``"primary"`` + - Specifies the default read preference for the client (excluding tags). See :ref:`read preference ` for more information. + + * - **readPreferenceTags** + - comma-separated key:value pairs, for example, "dc:ny,rack:1" and "dc:ny + can be specified multiple times, each instance of this key is a + separate tag set + - ``null`` + - Specifies the default read preference tags for the client. This option is + valid only if the read preference mode is not primary. + + The driver uses the order of the tags in the URI as the order + for the read preference. + + * - **replicaSet** + - string + - ``null`` + - Specifies the name of the replica set to connect to. + + * - **retryReads** + - boolean + - ``true`` + - Enables retryable reads. + + * - **retryWrites** + - boolean + - ``true`` + - Enables retryable writes. + + * - **serverMonitoringMode** + - ``auto``, ``stream``, ``poll`` + - ``auto`` + - Specifies the monitoring mode that the driver monitors use. When + this option is set to ``auto``, the monitoring mode is determined + by the environment in which the driver is running. The driver + uses polling mode in function-as-a-service (FaaS) environments + and the streaming mode in other environments. + + * - **serverSelectionTimeoutMS** + - non-negative integer + - ``30000`` + - Specifies the timeout, in milliseconds, to block for server selection + before raising an error. + + * - **socketTimeoutMS** + - non-negative integer + - ``0`` + - Specifies the amount of time in milliseconds spent attempting to send or receive + on a socket before timing out. Specifying ``0`` means your application sets an + infinite socket timeout when establishing a socket. + + * - **srvMaxHosts** + - non-negative integer + - ``0`` + - Specifies the maximum number of SRV results to randomly select when initially + populating the seedlist or, during SRV polling, adding new hosts to the + topology. + + * - **srvServiceName** + - a valid SRV service name according to `RFC 6335 `_ + - ``"mongodb"`` + - Specifies the service name to use for SRV lookup in initial DNS seedlist discovery. + + * - **ssl** + - boolean + - ``false`` + - The ``ssl`` is an alias for the ``tls`` option. + + * - **tls** + - boolean + - ``false`` + - Specifies whether TLS is required for connections to the server. + Using a ``srvServiceName`` of ``"mongodb+srv"``, or specifying other + ``tls``-prefixed options implicitly sets the value of ``tls`` to + ``true``. + + * - **tlsAllowInvalidCertificates** + - boolean + - ``false`` + - Specifies whether the driver generates an error when the server's + TLS certificate is invalid. Set this option to ``true`` for testing + purposes only. + + * - **tlsAllowInvalidHostnames** + - boolean + - ``false`` + - Specifies whether the driver generates an error when there is a mismatch + between the server's hostname and the hostname specified by the + TLS certificate. Set this option to ``true`` for testing purposes only. + + * - **tlsCAFile** + - string + - ``null`` + - Specifies the path to a file with either a single or bundle of certificate + authorities to trust when making a TLS connection. To learn more + about setting this connection option, see the :ref:`Provide + Certificate Filepaths ` section of the TLS guide. + + * - **tlsCertificateKeyFile** + - string + - ``null`` + - Specifies the path to the client certificate file or the client + private key file. If you need both, you must concatenate the + files. To learn more about setting this connection option, see + the :ref:`Provide Certificate Filepaths ` + section of the TLS guide. + + * - **tlsCertificateKeyFilePassword** + - string + - ``null`` + - Specifies the password to decrypt the client private key to be used + for TLS connections. + + * - **tlsInsecure** + - boolean + - ``false`` + - Specifies to relax TLS constraints as much as possible, such as + allowing invalid certificates or hostname mismatches. Set this option + to ``true`` for testing purposes only. + + * - **waitQueueTimeoutMS** + - non-negative integer + - ``0`` + - Specifies the amount of time, in milliseconds, spent attempting to check out a connection + from a server's connection pool before timing out. + + ``0`` signifies no timeout. + + * - **zlibCompressionLevel** + - integer between ``-1`` and ``9`` (inclusive) + - ``-1`` + - Specifies the level of compression when using zlib to compress wire + protocol messages. ``-1`` signifies the default level, ``0`` signifies + no compression, ``1`` signifies the fastest speed, and ``9`` signifies + the best compression. See :ref:`node-network-compression` for more information. + +Connection Time Out Options +--------------------------- + +.. list-table:: + :widths: 22 78 + :header-rows: 1 + + * - Setting + - Description + + * - **connectTimeoutMS** + - ``connectTimeoutMS`` is a :ref:`connection option + ` that sets the time, in milliseconds, + for an individual connection from your connection pool to + establish a TCP connection to the {+mdb-server+} before + timing out. To modify the allowed time for + `MongoClient.connect <{+api+}/classes/MongoClient.html#connect>`__ to establish a + connection to a {+mdb-server+}, use the ``serverSelectionTimeoutMS`` option instead. + + **Default:** 30000 + + * - **socketTimeoutMS** + - ``socketTimeoutMS`` specifies the amount of time the driver waits + for an inactive socket before closing it. The default value is to + never time out the socket. This option applies only to sockets that + have already been connected. + + * - **maxTimeMS** + - `maxTimeMS <{+api+}/classes/FindCursor.html#maxTimeMS>`__ + specifies the maximum amount of time that the server + waits for an operation to complete after it has reached the + server. If an operation runs over the specified time limit, it + returns a timeout error. You can pass ``maxTimeMS`` only to an + individual operation or to a cursor. + +To specify the optional settings for your ``MongoClient``, declare one or +more available settings in the ``options`` object of the constructor as +follows: + +.. code-block:: javascript + + const client = new MongoClient(uri, { + connectTimeoutMS: , + socketTimeoutMS: + }); + +To see all the available settings, see the +`MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__ +API Documentation. + +To specify ``maxTimeMS``, pass in the ``maxTimeMS`` method as an option with a timeout +specification to an operation that returns a ``Cursor``: + +.. code-block:: javascript + + const Cursor = collection.distinct('my-key', { maxTimeMS: 50 }); + +Close Sockets After Connection +------------------------------ + +If you experience unexpected network behavior or if a MongoDB process +fails with an error, you might not receive confirmation that the +driver correctly closed the corresponding socket. + +To make sure that the driver correctly closes the socket in these cases, +set the ``socketTimeoutMS`` option. When a MongoDB process times out, the driver +will close the socket. We recommend that you select a value +for ``socketTimeoutMS`` that is two to three times longer than the +expected duration of the slowest operation that your application executes. + +Prevent Long-Running Operations From Slowing Down the Server +------------------------------------------------------------ + +You can prevent long-running operations from slowing down the server by +specifying a timeout value. You can chain the ``maxTimeMS()`` method to +an operation that returns a ``Cursor`` to set a timeout on a specific action. + +The following example shows how you can chain the ``maxTimeMS()`` method +to an operation that returns a ``Cursor``: + +.. literalinclude:: /code-snippets/faq/maxTimeMS-example.js + :language: javascript + +.. _node-faq-keepalive: + +keepAlive Connection Option +--------------------------- + +The ``keepAlive`` connection option specifies whether to enable +:wikipedia:`Transmission Control Protocol (TCP) keepalives +` on a TCP socket. If you enable keepalives, +the driver checks whether the connection is active by sending periodic pings +to your MongoDB deployment. This functionality works only if your +operating system supports the ``SO_KEEPALIVE`` socket option. + +The ``keepAliveInitialDelay`` option specifies the number of +milliseconds that the driver waits before initiating a keepalive. + +The 5.3 driver version release deprecated these options. Starting in +version 6.0 of the driver, the ``keepAlive`` option is permanently set +to ``true``, and the ``keepAliveInitialDelay`` is set to 300000 +milliseconds (300 seconds). + +.. warning:: + + If your firewall ignores or drops the keepalive messages, you might + not be able to identify dropped connections. + +Additional Information +---------------------- + +To learn more about connection options that you can set within a +``MongoClientOptions`` instance, see `MongoClientOptions <{+api+}/interfaces/MongoClientOptions.html>`__ +in the API Documentation. From b850db997dc67151a3b8b442495d9ed34ac80f12 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 30 Apr 2025 12:00:15 -0400 Subject: [PATCH 2/2] remove extra ref --- source/monitoring-and-logging/change-streams.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/monitoring-and-logging/change-streams.txt b/source/monitoring-and-logging/change-streams.txt index baeb054da..c08b90070 100644 --- a/source/monitoring-and-logging/change-streams.txt +++ b/source/monitoring-and-logging/change-streams.txt @@ -117,8 +117,6 @@ read events from the change stream: .. include:: /includes/changestream-paradigm-warning.rst -.. _node-usage-watch: - Examples --------