Specify Connection Options

On this page

Overview

Connection Options

Overview

This section describes the MongoDB connection and authentication options available in PyMongo. You can configure your connection using either the connection URI or arguments to the MongoClient constructor.

Using the Connection URI

If you pass a connection URI to the MongoClient constructor, 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:

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

Using a `MongoClient`

You can pass connection options as arguments to the MongoClient constructor instead of including them in your connection URI. Configuring the connection this way makes it easier to change settings at runtime and helps you catch errors during compilation. The following example shows how to use the MongoClient constructor to set connection options:

uri = "mongodb://<hostname>:<port>"
client = pymongo.MongoClient(uri, connectTimeoutMS=60000, tls=True)

Connection Options

The following sections describe the connection options available in PyMongo. If a MongoClient parameter maps to more than one option in the connection string, the Connection URI Example shows all relevant options.

Network Compression

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: str
Default: None
MongoClient Example: compressors = "snappy,zstd,zlib"
Connection URI Example: compressors=snappy,zstd,zlib

zlibCompressionLevel

The compression level for zlib to use. This option accepts
an integer value between -1 and 9:

- -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: int
Default: -1
MongoClient Example: zlibCompressionLevel = 3
Connection URI Example: zlibCompressionLevel=3

Timeouts

Connection Option	Description
timeoutMS	The number of milliseconds each driver operation must complete within. If an operation doesn't finish in the specified time, PyMongo raises a timeout exception. For more information, see Limit Server Execution Time. Data Type: `int` Default: `None` MongoClient Example: `timeoutMS = 10000` Connection URI Example: `timeoutMs=10000`

Server Selection

Connection Option	Description
server_selector	A user-defined Python function called by PyMongo to choose the server to run an operation against. For more information, see Customize Server Selection. Data Type: `callable` Default: `None` MongoClient Example: `server_selector = your_function` Connection URI Example: N/A

Authentication

Connection Option	Description
authMechanism	The mechanism PyMongo uses to authenticate the application. Valid options are defined in MECHANISMS. Data Type: `str` Default: `"SCRAM-SHA-256"` when connecting to MongoDB v4.0 or later. `"SCRAM-SHA-1"` when connecting to MongoDB v3.0 through v3.13. MongoClient Example: `authMechanism = "MONGODB-X509"` Connection URI Example: `authMechanism=MONGODB-X509`
authMechanismProperties	Options specific to the authentication mechanism. Not needed for all authentication mechanisms. Data Type: `str` Default: `""` MongoClient Example: `authMechanismProperties = "AWS_SESSION_TOKEN:12345"` Connection URI Example: `authMechanismProperties=AWS_SESSION_TOKEN:12435`
authSource	The database to authenticate against. Data Type: `str` Default: The database in the connection URI, or `"admin"` if none is provided MongoClient Example: `authSource = "admin"` Connection URI Example: `authSource=admin`
username	The username for authentication. When this option is included in a connection URI, you must percent-escape it. Data Type: `str` Default: `""` MongoClient Example: `username = "my user"` Connection URI Example: `username=my+user`
password	The password for authentication. When this option is included in a connection URI, you must percent-escape it. Data Type: `str` Default: `""` MongoClient Example: `password = "strong password"` Connection URI Example: `password=strong+password`

For more information about the connection option in this section, see Authentication Mechanisms.

Read and Write Operations

Connection Option	Description
replicaSet	Specifies the name of the replica set to connect to. Data Type: `str` Default: `null` MongoClient Example: `replicaSet='replicaSetName'` Connection URI Example: `replicaSet=replicaSetName`
directConnection	Whether to connect only to the primary member of the replica set. Data Type: `bool` Default: `False` MongoClient Example: `directConnection=True` Connection URI Example: `directConnection=true`
readPreference	Specifies the client's read-preference settings. Data Type: read_preferences Default: `ReadPreference.Primary` MongoClient Example: `readPreference=ReadPreference.SECONDARY_PREFERRED` Connection URI Example: `readPreference=secondaryPreferred`
readConcern	Specifies the client's read-concern settings. For more information, see /reference/read-concern/. Data Type: `str` Default: `None` MongoClient Example: `readConcern="majority"` Connection URI Example: `readConcern=majority`
writeConcern	Specifies the client's write-concern settings. For more information, see /reference/write-concern/. Data Type: `str` Default: `None` MongoClient Example: `writeConcern="majority"` Connection URI Example: `writeConcern=majority`
localThresholdMS	The latency window for a replica-set members 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: read_preferences Default: ``int`` MongoClient Example: `localThresholdMS=35` Connection URI Example: `localThresholdMS=35`

For more information about the connection option in this section, see Databases and Collections.

Back

Choose a Connection Target

Configure Transport Layer Security (TLS)