connection-options.txt

.. _node-connection-options:

==================
Connection Options
==================

.. facet::
   :name: genre
   :values: reference

.. meta:: 
   :keywords: node.js, customize

This section explains the MongoDB connection and authentication options
supported by the driver. You can pass the connection options as
parameters of the connection URI to specify the behavior of the client.

.. 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
       :ref:`authentication mechanism <node-authentication-mechanisms>` 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`` disables the connection timeout.

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

       You can also set UTF-8 validation in your :ref:`Node.js code
       <nodejs-utf-8-validation>`. To learn more about UTF-8 characters, 
       see `UTF-8 <https://en.wikipedia.org/wiki/UTF-8>`__ on Wikipedia.

   * - **heartbeatFrequencyMS**
     - integer greater than or equal to 500
     - ``null``
     - Specifies the interval, in milliseconds, between regular server monitoring checks.

   * - **journal**
     - boolean
     - ``null``
     - Specifies the journal write concern for the client. See
       :ref:`write concern <wc-j>` for more information.

   * - **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
       <read-concern>` for more information.

   * - **readPreference**
     - string
     - ``"primary"``
     - Specifies the default read preference for the client (excluding tags). See :ref:`read preference <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.

   * - **serverSelectionTryOnce**
     - boolean
     - ``true``
     - Specifies to scan the topology only once after a server selection
       failure instead of repeatedly until the server selection times out.

   * - **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 no timeout.

   * - **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 <https://datatracker.ietf.org/doc/html/rfc6335#section-5.1>`_
     - ``"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 <node-tls-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 <node-tls-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.

   * - **w**
     - non-negative integer or string
     - ``null``
     - Specifies the default write concern ``"w"`` field for the client.

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

   * - **wTimeoutMS**
     - non-negative integer
     - ``null``
     - Specifies the default write concern timeout field for the client.

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