Docs Menu
Docs Home
/
Languages
/
Python
/
PyMongo
/
Connect

Specify Connection Options

On this page

  • Overview
  • Using the Connection URI
  • Using a MongoClient
  • Connection Options
  • Network Compression
  • Timeouts
  • Server Selection
  • Connection Pools
  • Authentication
  • Read and Write Operations

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

Connection Pools

A connection pool is a cache of open database connections maintained by PyMongo. When your application requests a connection to MongoDB, PyMongo gets a connection from the pool, performs operations, and returns the connection to the pool for reuse. Connection pools help reduce application latency and the number of times that PyMongo must create new connections.

To learn more about connection pools, see Connection Pool Overview in the MongoDB Server manual.

Setting
Description

connectTimeoutMS

The time that PyMongo waits when connecting a new socket before timing out.

Data Type: int
Default: 20000
MongoClient Example: connectTimeoutMS = 40000
Connection URI Example: connectTimeoutMS=40000

maxConnecting

The maximum number of connections that each pool can establish concurrently. If this limit is reached, further requests wait until a connection is established or another in-use connection is checked back into the pool.

Data Type: int
Default: 2
MongoClient Example: maxConnecting = 3
Connection URI Example: maxConnecting=3

maxIdleTimeMS

The maximum time that a connection can remain idle in the pool.

Data Type: int
Default: None (no limit)
MongoClient Example: maxIdleTimeMS = 60000
Connection URI Example: maxIdleTimeMS=60000

maxPoolSize

The maximum number of concurrent connections that the pool maintains. If the maximum pool size is reached, further requests wait until a connection becomes available.

Data Type: int
Default: 100
MongoClient Example: maxPoolSize = 150
Connection URI Example: maxPoolSize=150

minPoolSize

The minimum number of concurrent connections that the pool maintains. If the number of open connections falls below this value due to network errors, PyMongo attempts to create new connections to maintain this minimum.

Data Type: int
Default: 0
MongoClient Example: minPoolSize = 3
Connection URI Example: minPoolSize=3

socketTimeoutMS

The length of time that PyMongo waits for a response from the server before timing out.

Data Type: int
Default: None (no timeout)
MongoClient Example: socketTimeoutMS = 100000
Connection URI Example: socketTimeoutMS=100000

waitQueueTimeoutMS

How long a thread waits for a connection to become available in the connection pool before timing out.

Data Type: int
Default: None (no timeout)
MongoClient Example: waitQueueTimeoutMS = 100000
Connection URI Example: waitQueueTimeoutMS=100000

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

retryReads

Specifies whether the client retries supported read operations. For more information, see Retryable Reads in the MongoDB Server manual.

Data Type: bool
Default: True
MongoClient Example: retryReads=False
Connection URI Example: retryReads=false

retryWrites

Specifies whether the client retries supported write operations. For more information, see Retryable Writes in the MongoDB Server manual.

Data Type: bool
Default: True
MongoClient Example: retryWrites=False
Connection URI Example: retryWrites=false

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

Back

Choose a Connection Target

Next

Configure TLS