指定连接选项

Overview

本页介绍了 Go 驱动程序中可用的连接选项，并说明了如何将这些选项应用于 MongoDB 连接。

如何指定连接选项

以下部分介绍如何使用连接字符串或 ClientOptions 结构指定连接选项。

使用连接字符串

您可以通过将 ClientOptions 结构体传递给 Connect() 方法，在连接字符串中指定连接选项。在连接字符串中，您可以将连接选项作为 <name>=<value> 对包含在 string 中。在以下示例中，连接字符串包含值为 60000 毫秒的 connectTimeoutMS 选项和值为 true 的 tls 选项：

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

使用 ClientOptions Struct

您还可以将连接选项链接到 ClientOptions 结构以配置连接设置。以这种方式配置连接可以更轻松地在运行时更改设置，帮助您在编译期间捕获错误，并且提供比连接字符串更多的配置选项。

以下代码示例将 Timeout 选项设置为 60 秒，并通过将空 tls.Config 结构传递给 SetTLSConfig() 方法来启用 TLS：

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

副本集选项

DirectConnection

指定是否强制将所有操作分派到托管。如果指定此选项，驱动程序将不接受 SRV 连接格式。必须使用标准连接 URI 格式。要了解有关 SRV 连接和标准连接格式的更多信息，请参阅 MongoDB Server 手册中的连接字符串指南。

如果指定多个托管名，则必须将此属性设立为 false。

数据类型： bool

默认值： false

示例：

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

副本集(Replica Set)

要连接的副本集的名称。

数据类型： string

默认值： nil

示例：

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

DirectConnection

如果指定多个托管名，则必须将此属性设立为 false。

数据类型： bool

默认值： false

示例：

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

副本集(Replica Set)

要连接的副本集的名称。

数据类型： string

默认值： nil

示例：

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

TLS 选项

启用 TLS

指定是否需要 TLS 来连接到服务器。如果使用 "mongodb+srv" 模式或指定其他 TLS 选项，则此选项默认为 true。否则，默认为 false。

数据类型： bool

默认值： nil

示例：

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

禁用证书撤销

tlsDisableCertificateRevocationCheck 选项禁用 TLS 连接的证书吊销检查。当您将此选项设置为 true 时，驱动程序不会验证证书的吊销状态，但仍会验证证书链和主机名。即使将其设置为 false，设置此选项也会隐式启用 TLS。请勿将此选项与 tlsInsecure 或 tlsDisableOCSPEndpointCheck 结合使用。

数据类型： bool

默认值： false

示例：

uri := os.Getenv("MONGODB_URI")
if uri == "" {
	log.Fatal("Set your 'MONGODB_URI' environment variable")
}
// Use an ampersand instead of a question mark if the connection string
// already contains query options.
separator := "?"
if strings.Contains(uri, "?") {
	separator = "&"
}
uriOptions := options.Client().
	ApplyURI(uri + separator + "tlsDisableCertificateRevocationCheck=true")

启用 TLS

指定是否需要 TLS 来连接到服务器。如果使用 "mongodb+srv" 模式或指定其他 TLS 选项，则此选项默认为 true。否则，默认为 false。

数据类型： tls.Config

默认值： false

示例：

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

禁用证书撤销

SetDisableCertificateRevocationCheck() 方法会禁用 TLS 连接的证书吊销检查。当您将此选项设置为 true 时，驱动程序不会验证证书的吊销状态，但仍会验证证书链和主机名。设置此选项不会隐式启用 TLS。请勿将此选项与 tlsInsecure 或 tlsDisableOCSPEndpointCheck 结合使用。

数据类型： bool

默认值： false

示例：

settingsOptions := options.Client().
	SetDisableCertificateRevocationCheck(true)

有关 TLS 选项的更多信息，请参阅在连接上启用 TLS指南。

超时选项

ConnectTimeout

驱动程序在超时前尝试与服务器建立单个 TCP 套接字连接的时间长度。

数据类型：非负 int

默认值： 30000 毫秒

示例：

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

超时

timeoutMS 选项指定在客户端上运行的单个操作在返回错误之前可以执行的时间量。

数据类型：非负 int

默认值： nil

示例：

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

ConnectTimeout

驱动程序在超时前尝试与服务器建立单个 TCP 套接字连接的时间长度。

数据类型： time.Duration

默认值： 30 秒数

示例：

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

超时

SetTimeout() 方法指定在客户端上运行的单个操作在返回错误之前可以执行的时间量。

数据类型： time.Duration

默认值： nil

示例：

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

压缩选项

compressors

首选压缩类型（按顺序），用于发送到服务器或从服务器接收的传输协议消息。您可以将“snappy”、“zlib”和“zstd”作为可选的构建时依赖项启用。驱动程序使用服务器支持的第一种压缩类型。

数据类型： string （值以逗号分隔）

默认值： nil

示例：

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

zlibCompressionLevel

zlibCompressionLevel 选项设置 zlib 使用的压缩级别。如果未通过 ApplyURI 或 SetCompressors 将 zlib 指定为压缩器，则会忽略此选项。此选项接受 -1 和 9 之间的整数值：

-1: (默认).zlib 使用其默认压缩级别（通常为 6）。
0: 无压缩。
1: 速度最快，但压缩最低。
9: 压缩最佳，但速度最慢。

数据类型： int

默认值： -1

示例：

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

Zstandard 压缩级别

zstdCompressionLevel 选项设置 zstd 使用的压缩级别。如果未通过 ApplyURI 或 SetCompressors 将 zstd 指定为压缩程序，则会忽略此选项。此选项接受 1 到 20 之间的整数值：

1: 速度最快，但压缩最低。
20: 压缩最佳，但速度最慢。

数据类型： int

默认值： 6

示例：

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

compressors

数据类型： []string

默认值： nil

示例：

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

zlibCompressionLevel

SetZlibLevel() 方法设置 zlib 要使用的压缩级别。如果未通过 ApplyURI 或 SetCompressors 将 zlib 指定为压缩程序，则会忽略此选项。此选项接受 -1 和 9 之间的整数值：

-1：（默认）。zlib 使用其默认压缩级别（通常为 6）。
0 ：无压缩。
1 ：速度最快，但压缩率最低。
9 ：压缩最佳，但速度最慢。

数据类型： int

默认值： -1

示例：

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

Zstandard 压缩级别

SetZstdLevel() 方法设置 zstd 使用的压缩级别。如果未通过 ApplyURI 或 SetCompressors 将 zstd 指定为压缩器，则会忽略此选项。此选项接受 1 和 20 之间的整数值：

数据类型： int

默认值： 6

示例：

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

有关压缩的更多信息，请参阅压缩网络流量指南。

连接池选项

maxPoolSize

驱动程序可在其连接池中创建的客户端或连接的最大数量。此计数包括正在使用的连接。

数据类型：非负 int

默认值： 100

示例：

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

minPoolSize

即使没有发生任何操作，驱动程序在连接池中创建并保持的连接数。此计数包括正在使用的连接。

数据类型：非负 int

默认值： 0

示例：

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

MaxConnectionIdleTime

在驱动程序关闭连接之前，该连接可处于空闲状态的时间长度。

数据类型：非负 int

默认值： 0

示例：

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

MaxConnecting

maxConnecting 选项设置连接池可以同时建立的最大连接数。

数据类型：非负 int

默认值： 2

示例：

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

maxPoolSize

驱动程序可在其连接池中创建的客户端或连接的最大数量。此计数包括正在使用的连接。

数据类型：非负 uint64

默认值： 100

示例：

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

minPoolSize

即使没有发生任何操作，驱动程序在连接池中创建并保持的连接数。此计数包括正在使用的连接。

数据类型：非负 uint64

默认值： 0

示例：

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

MaxConnectionIdleTime

在驱动程序关闭连接之前，该连接可处于空闲状态的时间长度。

数据类型： time.Duration

默认值： 0

示例：

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

MaxConnecting

SetMaxConnecting() 方法设置连接池可以同时建立的最大连接数。

数据类型：非负 uint64

默认值： 2

示例：

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

要学习有关连接池的更多信息，请参阅连接池指南。

写关注选项

写关注

写关注（write concern）的 w 组件，请求确认写入操作已传播到指定数量的MongoDB实例。默认值为 "majority" 或 1，具体取决于仲裁节点和投票节点的数量。要学习；了解有关 w 选项的更多信息，请参阅MongoDB Server手册中的写关注。

数据类型： int or string

默认值： 1 or "majority"

示例：

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

写关注

数据类型： writeconcern.WriteConcern

默认值： 1 or "majority"

示例：

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

读关注选项

读关注 (read concern)

客户端的读关注（read concern）级别。有关更多信息，请参阅MongoDB Server手册中的读关注（read concern）参考。

数据类型： string

默认值： local

示例：

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

读关注 (read concern)

客户端的读关注（read concern）级别。有关更多信息，请参阅MongoDB Server手册中的读关注（read concern）参考。

数据类型： readconcern.ReadConcern

默认值： nil

示例：

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

读取偏好选项

读取偏好

客户端的默认读取偏好（read preference）设置。有关详细信息，请参阅 MongoDB Server 手册中的读取偏好（read preference）。

数据类型： string

默认值： primary

示例：

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

读取偏好

客户端的默认读取偏好（read preference）设置。有关详细信息，请参阅 MongoDB Server 手册中的读取偏好（read preference）。

数据类型： readpref.ReadPref

默认值： readpref.Primary()

示例：

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

身份验证选项

身份验证机制

驱动程序用于向 MongoDB Server 进行身份验证的机制。如果您未指定身份验证机制，驱动程序将使用 SCRAM-SHA-1 或 SCRAM-SHA-256，具体取决于服务器版本。

要了解有关可用身份验证机制的更多信息，请参阅《身份验证机制》指南。

数据类型： string

默认值：空（无身份验证），或在启用身份验证后为 SCRAM-SHA-256

示例：

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

身份验证机制

驱动程序用于向 MongoDB Server 进行身份验证的机制。如果您未指定身份验证机制，驱动程序将使用 SCRAM-SHA-1 或 SCRAM-SHA-256，具体取决于服务器版本。

要了解有关可用身份验证机制的更多信息，请参阅《身份验证机制》指南。

数据类型： Credential

默认值：空（无身份验证），或在启用身份验证后为 SCRAM-SHA-256

示例：

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

服务器选择选项

ServerSelectionTimeout

驱动程序在超时之前尝试选择服务器的时间长度。

数据类型：非负 int

默认值： 30000 毫秒

示例：

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

LocalThreshold

服务器资格的延迟窗口。如果服务器的往返时间长于最快服务器的往返时间加上此值，则该服务器没有资格被选中。

数据类型：非负 int

默认值： 15 毫秒

示例：

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

ServerSelectionTimeout

驱动程序在超时之前尝试选择服务器的时间长度。

数据类型： time.Duration

默认值： 30 秒数

示例：

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

LocalThreshold

服务器资格的延迟窗口。如果服务器的往返时间长于最快服务器的往返时间加上此值，则该服务器没有资格被选中。

数据类型： time.Duration

默认值： 15 毫秒

示例：

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

重试选项

retryReads

允许重试读取。

数据类型： bool

默认值： true

示例：

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

retryWrites

启用可重试写入。

数据类型： bool

默认值： true

示例：

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

最大自适应重试

maxAdaptiveRetries 选项设置了驱动程序在遇到服务器端过载错误时应重试操作的最大次数。

数据类型：非负 int

默认值： 2

示例：

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

retryReads

允许重试读取。

数据类型： bool

默认值： true

示例：

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

retryWrites

启用可重试写入。

数据类型： bool

默认值： true

示例：

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

最大自适应重试

SetMaxAdaptiveRetries() 方法设置驱动程序应重试因服务器端过载错误而失败的操作的最大次数。

数据类型：非负 uint

默认值： 2

示例：

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

其他选项

ApplicationName

驱动程序在连接握手过程中作为客户端元数据的一部分传递给服务器的应用名称。服务器建立连接后，会将此值打印到 MongoDB 日志中。该值还会记录在慢速查询日志和配置文件集合中。

数据类型： string

默认值： nil

示例：

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

LoadBalanced

指定驱动程序是否正在连接到负载均衡器。仅当满足以下所有条件时，才能将此属性设立为 true：

您仅指定一个托管名
您没有连接到副本集
您没有使用 SrvMaxHosts属性
您没有使用 DirectConnection属性

数据类型： bool

默认值： false

示例：

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

SrvMaxHosts

初始填充种子列表或在 SRV 轮询期间向拓扑结构添加新主机时要随机选择的 SRV 结果的最大数量。

仅当连接字符串模式设立为 ConnectionStringScheme.MongoDBPlusSrv 时才能使用此属性。连接到副本集时无法使用它。

数据类型：非负 int

默认值： 0

示例：

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

srvServiceName

SRV 资源记录的服务名称，驱动程序会检索该服务名称以构建您的种子列表。驱动程序使用该服务名称创建 SRV URI，其格式如下：

_{srvServiceName}._tcp.{hostname}.{domainname}

此属性会覆盖发现和轮询中 SRV 查找的默认服务名称。默认值为 "mongodb"。

仅当连接字符串模式设立为 ConnectionStringScheme.MongoDBPlusSrv 时才能使用此属性。连接到副本集时无法使用它。

数据类型： string

默认值： mongodb

示例：

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

ApplicationName

数据类型： string

默认值： nil

示例：

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

LoadBalanced

指定驱动程序是否正在连接到负载均衡器。仅当满足以下所有条件时，才能将此属性设立为 true：

您仅指定一个托管名
您没有连接到副本集
您没有使用 SrvMaxHosts属性
您没有使用 DirectConnection属性

数据类型： bool

默认值： false

示例：

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

Server API

SetServerAPIOptions() 方法配置运行命令时发送到服务器的 API 版本。有关服务器 API 的更多信息，请参阅 Stable API 指南。

数据类型： ServerAPIOptions

默认值： nil

示例：

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

SrvMaxHosts

初始填充种子列表或在 SRV 轮询期间向拓扑结构添加新主机时要随机选择的 SRV 结果的最大数量。

仅当连接字符串模式设立为 ConnectionStringScheme.MongoDBPlusSrv 时才能使用此属性。连接到副本集时无法使用它。

数据类型：非负 int

默认值： 0

示例：

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

srvServiceName

SRV 资源记录的服务名称，驱动程序会检索该服务名称以构建您的种子列表。驱动程序使用该服务名称创建 SRV URI，其格式如下：

_{srvServiceName}._tcp.{hostname}.{domainname}

此属性会覆盖发现和轮询中 SRV 查找的默认服务名称。默认值为 "mongodb"。

仅当连接字符串模式设立为 ConnectionStringScheme.MongoDBPlusSrv 时才能使用此属性。连接到副本集时无法使用它。

数据类型： string

默认值： mongodb

示例：

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