Specify Connection Options

Overview

This page describes the connection options available in the Go driver and explains how to apply them to your MongoDB connection.

How to Specify Connection Options

The following sections describe how you can specify connection options by using a connection string or a ClientOptions struct.

Use the Connection String

You can specify connection options in a connection string by passing a ClientOptions struct to the Connect() method. In the connection string, you can include connection options in the string as <name>=<value> pairs. In the following example, the connection string contains the connectTimeoutMS option with a value of 60000 milliseconds and the tls option with a value of true:

const uri = "mongodb+srv://localhost:27017/?connectTimeoutMS=60000&tls=true"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Use the ClientOptions Struct

You can also chain connection options to the ClientOptions struct to configure connection settings. Configuring the connection this way makes it easier to change settings at runtime, helps you catch errors during compilation, and provides more configuration options than the connection string.

The following code example sets the Timeout option to 60 seconds and enables TLS by passing an empty tls.Config struct to the SetTLSConfig() method:

opts := options.Client().
	SetConnectTimeout(60 * time.Second).
	SetTLSConfig(&tls.Config{})
client, _ := mongo.Connect(opts)

Replica Set Options

Direct Connection

Specifies whether to force dispatch all operations to the host. If you specify this option, the driver doesn't accept the SRV connection format. You must use the standard connection URI format instead. To learn more about the SRV connection and the standard connection formats, see the Connection Strings guide in the MongoDB Server manual.

This property must be set to false if you specify more than one host name.

Data Type: bool

Default Value: false

Example:

const uri = "mongodb://localhost:27017/?directConnection=true"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Replica Set

The name of the replica set to connect to.

Data Type: string

Default Value: nil

Example:

const uri = "mongodb://localhost:27017/?replicaSet=yourReplicaSet"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Direct Connection

This property must be set to false if you specify more than one host name.

Data Type: bool

Default Value: false

Example:

opts := options.Client().
	SetDirect(true)
client, _ := mongo.Connect(opts)

Replica Set

The name of the replica set to connect to.

Data Type: string

Default Value: nil

Example:

opts := options.Client().
	SetReplicaSet("yourReplicaSet")
client, _ := mongo.Connect(opts)

TLS Options

Enable TLS

Specifies whether to require TLS for connections to the server. If you use a scheme of "mongodb+srv" or specify other TLS options, this option defaults to true. Otherwise, it defaults to false.

Data Type: bool

Default Value: nil

Example:

const uri = "mongodb://localhost:27017/?tls=true"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Enable TLS

Specifies whether to require TLS for connections to the server. If you use a scheme of "mongodb+srv" or specify other TLS options, this option defaults to true. Otherwise, it defaults to false.

Data Type: tls.Config

Default Value: false

Example:

opts := options.Client().
	SetTLSConfig(&tls.Config{})
client, _ := mongo.Connect(opts)

For more information on TLS options, see the Enable TLS on a Connection guide.

Timeout Options

Connect Timeout

The length of time the driver tries to establish a single TCP socket connection to the server before timing out.

Data Type: non-negative int

Default Value: 30000 milliseconds

Example:

const uri = "mongodb://localhost:27017/?connectTimeoutMS=60000"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Timeout

The amount of time that a single operation run on the client can execute before returning an error.

Data Type: non-negative int

Default Value: nil

Example:

const uri = "mongodb://localhost:27017/?timeoutMS=30000"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Connect Timeout

The length of time the driver tries to establish a single TCP socket connection to the server before timing out.

Data Type: time.Duration

Default Value: 30 seconds

Example:

opts := options.Client().
	SetConnectTimeout(60 * time.Second)
client, _ := mongo.Connect(opts)

Timeout

The amount of time that a single operation run on the client can execute before returning an error.

Data Type: time.Duration

Default Value: nil

Example:

opts := options.Client().
	SetTimeout(30 * time.Second)
client, _ := mongo.Connect(opts)

Compression Options

Compressors

The preferred compression types, in order, for wire-protocol messages sent to or received from the server. You can enable "snappy", "zlib", and "zstd" as optional build time dependencies. The driver uses the first of these compression types that the server supports.

Data Type: string (values separated by commas)

Default Value: nil

Example:

const uri = "mongodb://localhost:27017/?compressors=zlib,snappy"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Zlib Compression Level

The compression level for zlib to use. This option is ignored if zlib is not specified as a compressor through ApplyURI or SetCompressors. 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 Value: -1

Example:

const uri = "mongodb://localhost:27017/?compressors=zlib&zlibCompressionLevel=6"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Zstandard Compression Level

The compression level for zstd to use. This option is ignored if zstd is not specified as a compressor through ApplyURI or SetCompressors. This option accepts integer values between 1 and 20:

1: Fastest speed but lowest compression.
20: Best compression but slowest speed.

Data Type: int

Default Value: 6

Example:

const uri = "mongodb://localhost:27017/?compressors=zstd&zstdCompressionLevel=6"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Compressors

Data Type: []string

Default Value: nil

Example:

opts := options.Client().
	SetCompressors([]string{"zlib", "snappy"})
client, _ := mongo.Connect(opts)

Zlib Compression Level

-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 Value: -1

Example:

opts := options.Client().
	SetCompressors([]string{"zlib"}).
	SetZlibLevel(6)
client, _ := mongo.Connect(opts)

Zstandard Compression Level

Data Type: int

Default Value: 6

Example:

opts := options.Client().
	SetCompressors([]string{"zstd"}).
	SetZstdLevel(8)
client, _ := mongo.Connect(opts)

For more information on compression, see the Compress Network Traffic guide.

Connection Pool Options

Max Pool Size

The greatest number of clients or connections the driver can create in its connection pool. This count includes connections in use.

Data Type: non-negative int

Default Value: 100

Example:

const uri = "mongodb://localhost:27017/?maxPoolSize=150"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Min Pool Size

The number of connections the driver creates and keeps in the connection pool even when no operations are occurring. This count includes connections in use.

Data Type: non-negative int

Default Value: 0

Example:

const uri = "mongodb://localhost:27017/?minPoolSize=3"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Max Connection Idle Time

The length of time a connection can be idle before the driver closes it.

Data Type: non-negative int

Default Value: 0

Example:

const uri = "mongodb://localhost:27017/?maxIdleTimeMS=8000"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Max Connecting

The maximum number of connections a connection pool may establish simultaneously.

Data Type: non-negative int

Default Value: 2

Example:

const uri = "mongodb://localhost:27017/?maxConnecting=3"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Max Pool Size

Data Type: non-negative uint64

Default Value: 100

Example:

opts := options.Client().
	SetMaxPoolSize(150)
client, _ := mongo.Connect(opts)

Min Pool Size

Data Type: non-negative uint64

Default Value: 0

Example:

opts := options.Client().
	SetMinPoolSize(3)
client, _ := mongo.Connect(opts)

Max Connection Idle Time

Data Type: time.Duration

Default Value: 0

Example:

opts := options.Client().
	SetMaxConnIdleTime(8 * time.Second)
client, _ := mongo.Connect(opts)

Max Connecting

The maximum number of connections a connection pool may establish simultaneously.

Data Type: non-negative uint64

Default Value: 2

Example:

opts := options.Client().
	SetMaxConnecting(3)
client, _ := mongo.Connect(opts)

To learn more about connection pools, see the Connection Pools guide.

Write Concern Options

Write Concern

Data Type: int or string

Default Value: 1 or "majority"

Example:

const uri = "mongodb://localhost:27017/?w=2"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Write Concern

Data Type: writeconcern.WriteConcern

Default Value: 1 or "majority"

Example:

wc := &writeconcern.WriteConcern{
	W: 2,
}
opts := options.Client().SetWriteConcern(wc)
client, _ := mongo.Connect(opts)

Read Concern Options

Read Concern

Data Type: string

Default Value: local

Example:

const uri = "mongodb://localhost:27017/?readConcernLevel=majority"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Read Concern

Data Type: readconcern.ReadConcern

Default Value: nil

Example:

opts := options.Client().
	SetReadConcern(readconcern.Majority())
client, _ := mongo.Connect(opts)

Read Preference Options

Read Preference

Data Type: string

Default Value: primary

Example:

const uri = "mongodb://localhost:27017/?readPreference=primaryPreferred"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Read Preference

Data Type: readpref.ReadPref

Default Value: readpref.Primary()

Example:

opts := options.Client().
	SetReadPreference(readpref.PrimaryPreferred())
client, _ := mongo.Connect(opts)

Authentication Options

Authentication Mechanism

To learn more about available authentication mechanisms, see the Authentication Mechanism guides.

Data Type: string

Default Value: empty (no authentication), or SCRAM-SHA-256 once authentication is enabled

Example:

const uri = "mongodb://user:password@localhost:27017/?authMechanism=PLAIN&authSource=admin"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Authentication Mechanism

To learn more about available authentication mechanisms, see the Authentication Mechanism guides.

Data Type: Credential

Default Value: empty (no authentication), or SCRAM-SHA-256 once authentication is enabled

Example:

credential := options.Credential{
	AuthMechanism: "PLAIN",
	AuthSource:    "admin",
	Username:      "user",
	Password:      "password",
}
opts := options.Client().SetAuth(credential)
client, _ := mongo.Connect(opts)

Server Selection Options

Server Selection Timeout

Data Type: non-negative int

Default Value: 30000 milliseconds

Example:

const uri = "mongodb://localhost:27017/?serverSelectionTimeoutMS=40000"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Local Threshold

Data Type: non-negative int

Default Value: 15 milliseconds

Example:

const uri = "mongodb://localhost:27017/?localThresholdMS=20000"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Server Selection Timeout

Data Type: time.Duration

Default Value: 30 seconds

Example:

opts := options.Client().
	SetServerSelectionTimeout(40 * time.Second)
client, _ := mongo.Connect(opts)

Local Threshold

Data Type: time.Duration

Default Value: 15 milliseconds

Example:

opts := options.Client().
	SetLocalThreshold(20 * time.Millisecond)
client, _ := mongo.Connect(opts)

Retry Options

Retry Reads

Data Type: bool

Default Value: true

Example:

const uri = "mongodb://localhost:27017/?retryReads=false"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Retry Writes

Data Type: bool

Default Value: true

Example:

const uri = "mongodb://localhost:27017/?retryWrites=false"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Max Adaptive Retries

The maximum number of times the driver should retry operations that fail with a server-side overload error.

Data Type: non-negative int

Default Value: 2

Example:

const uri = "mongodb://localhost:27017/?maxAdaptiveRetries=3"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Retry Reads

Data Type: bool

Default Value: true

Example:

opts := options.Client().
	SetRetryReads(false)
client, _ := mongo.Connect(opts)

Retry Writes

Data Type: bool

Default Value: true

Example:

opts := options.Client().
	SetRetryWrites(false)
client, _ := mongo.Connect(opts)

Max Adaptive Retries

The maximum number of times the driver should retry operations that fail with a server-side overload error.

Data Type: non-negative uint

Default Value: 2

Example:

const uri = "mongodb://localhost:27017/?maxAdaptiveRetries=3"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Miscellaneous Options

Application Name

Data Type: string

Default Value: nil

Example:

const uri = "mongodb://localhost:27017/?appName=yourAppName"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Load Balanced

Data Type: bool

Default Value: false

Example:

const uri = "mongodb://localhost:27017/?loadBalanced=true"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

SRV Max Hosts

Data Type: non-negative int

Default Value: 0

Example:

opts := options.Client().
	SetSRVMaxHosts(5)
client, _ := mongo.Connect(opts)

SRV Service Name

Data Type: string

Default Value: mongodb

Example:

const uri = "mongodb+srv://localhost/?srvServiceName=yourServiceName"
client, _ := mongo.Connect(options.Client().ApplyURI(uri))

Application Name

Data Type: string

Default Value: nil

Example:

opts := options.Client().
	SetAppName("yourAppName")
client, _ := mongo.Connect(opts)

Load Balanced

Data Type: bool

Default Value: false

Example:

opts := options.Client().
	SetLoadBalanced(true)
client, _ := mongo.Connect(opts)

Server API

Configure the API version sent to the server when running commands. For more information on the Server API, see the Stable API guide.

Data Type: ServerAPIOptions

Default Value: nil

Example:

opts := options.Client().
	SetServerAPIOptions(options.ServerAPI(options.ServerAPIVersion1))
client, _ := mongo.Connect(opts)

SRV Max Hosts

Data Type: non-negative int

Default Value: 0

Example:

opts := options.Client().
	SetSRVMaxHosts(5)
client, _ := mongo.Connect(opts)

SRV Service Name

Data Type: string

Default Value: mongodb

Example:

opts := options.Client().
	SetSRVServiceName("yourServiceName")
client, _ := mongo.Connect(opts)

Additional Information

To learn more about the options that you can specify in a connection string, see Connection String Options in the MongoDB Server manual.

For more information about the types used on this page, see the following API documentation:

Back

Choose a Connection Target

Compress Network Traffic