/ /

指定连接选项

Overview

本页介绍了C驾驶员中可用的连接选项，并解释了如何使用连接字符串或 URI 选项为MongoDB连接指定这些选项。

如何指定连接选项

以下部分介绍了指定连接选项的方法。

使用连接字符串

如果将连接字符串传递给 monogoc_client_t 结构，则可以将连接选项作为 <name>=<value> 对包含在该 string 中。在以下示例中，连接字符串包含值为 60000 的 connectTimeoutMS 选项和值为 true 的 tls 选项：

mongoc_init();
// Specifies the connection options in the connection string
const char *uri = "mongodb+srv://localhost:27017/?connectTimeoutMS=60000&tls=true";
// Creates a new client
mongoc_client_t *client = mongoc_client_new_from_uri_with_error(uri, &error);
if (!client) {
    fprintf(stderr, "%s\n", error.message);
    goto cleanup;
}
// Use client...
cleanup:
    mongoc_client_destroy(client);
    mongoc_uri_destroy(uri);

要了解有关可在连接字符串中指定的选项的更多信息，请参阅MongoDB Server手册中的连接字符串选项。

使用 URI 选项API

您可以使用 URI 选项在代码中而不是在连接字符串中配置连接设置。以这种方式配置连接可以更轻松地在运行时更改设置，帮助您在编译期间捕获错误，并提供比连接字符串更多的配置选项。

要使用 URI 选项设立连接选项，请执行以下步骤：

使用连接字符串创建一个 mongoc_uri_t 结构
使用 URI 选项函数指定所需的连接选项
创建具有该 URI 的新客户端，方法是将 URI 传递给 mongoc_client_new_from_uri()

以下代码示例展示了如何执行上述步骤：

mongoc_uri_t *uri = mongoc_uri_new_with_error("mongodb+srv://localhost:27017/", &error);
if (!uri) {
    fprintf(stderr, "%s\n", error.message);
    goto cleanup;
}
// Specifies the connection options by using the URI options API
if (!mongoc_uri_set_option_as_int32(uri, MONGOC_URI_CONNECTTIMEOUTMS, 60000)) {
    fprintf(stderr, "Failed to set '%s'\n", MONGOC_URI_CONNECTTIMEOUTMS);
    goto cleanup;
}
if (!mongoc_uri_set_option_as_bool(uri, MONGOC_URI_TLS, true)) {
    fprintf(stderr, "Failed to set '%s'\n", MONGOC_URI_TLS);
    goto cleanup;
}
// Creates a new client
client = mongoc_client_new_from_uri_with_error(uri, &error);
if (!client) { 
    fprintf(stderr, "%s\n", error.message);
    goto cleanup;
 }
// Use client...
cleanup:
    mongoc_client_destroy(client);
    mongoc_uri_destroy(uri);

副本集选项

DirectConnection

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

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

数据类型： boolean

默认值： false

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb://localhost:27017/?directConnection=true");

副本集(Replica Set)

要连接的副本集的名称。

数据类型： char*

默认值： NULL

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?replicaSet=yourReplicaSet");

DirectConnection

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

数据类型： boolean

默认值： false

示例：

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_DIRECTCONNECTION, true);

副本集(Replica Set)

要连接的副本集的名称。

数据类型： char*

默认值： NULL

示例：

mongoc_uri_set_option_as_utf8(uri, MONGOC_URI_REPLICASET, "yourReplicaSet");

TLS 选项

启用 TLS

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

数据类型： boolean

默认值： false

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?tls=true");

允许不安全的 TLS

指定是否尽可能放宽 TLS 约束。这可能包括允许无效证书或主机名不匹配。

数据类型： boolean

默认值： false

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?tls=true&tlsInsecure=true");

TLS 禁用证书撤销检查

是否在 TLS 握手期间禁用证书吊销检查。

数据类型： boolean

默认值： false

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?tls=true&tlsDisableCertificateRevocationCheck=true");

启用 TLS

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

数据类型： boolean

默认值： false

示例：

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_TLS, true);

允许不安全的 TLS

指定是否尽可能放宽 TLS 约束。这可能包括允许无效证书或主机名不匹配。

数据类型： boolean

默认值： false

示例：

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_TLSINSECURE, true);

TLS 禁用证书撤销检查

是否在 TLS 握手期间禁用证书吊销检查。

数据类型： boolean

默认值： false

示例：

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_TLSDISABLECERTIFICATEREVOCATIONCHECK, true);

有关 TLS 选项的更多信息，请参阅配置传输层安全性 (TLS)指南。

超时选项

ConnectTimeout

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

数据类型： integer

默认值： 10000 （10 秒）

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?connectTimeoutMS=60000");

SocketTimeout

驱动程序在超时之前尝试在套接字上发送或接收的时间长度。默认值由操作系统设立。

数据类型： integer

默认值： 300000 （5 分钟）

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?socketTimeoutMS=60000");

ConnectTimeout

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

数据类型： integer

默认值： 10000 （10 秒）

示例：

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_CONNECTTIMEOUTMS, 60000);

SocketTimeout

驱动程序在超时之前尝试在套接字上发送或接收的时间长度。默认值由操作系统设立。

数据类型： integer

默认值： 300000 （5 分钟）

示例：

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_SOCKETTIMEOUTMS, 60000);

压缩选项

compressors

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

数据类型： char*

默认值： NULL

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?compressors=zlib,snappy");

compressors

数据类型： char*

默认值： NULL

示例：

mongoc_uri_set_option_as_utf8(uri, MONGOC_URI_COMPRESSORS, "zlib,snappy");

连接池选项

maxPoolSize

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

数据类型： integer

默认值： 100

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?maxPoolSize=150");

WaitQueueTimeout

驱动程序在超时之前尝试从服务器的连接池检出连接的时间长度。

数据类型： integer

默认值： -1 （无超时）

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?waitQueueTimeoutMS=30000");

MaxConnectionPoolSize

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

数据类型： integer

默认值： 100

示例：

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_MAXPOOLSIZE, 150)

还可以使用 mongoc_client_pool_t 结构设立最大连接池大小：

mongoc_client_pool_t *pool = mongoc_client_pool_new(uri);
// Specifies max pool size 
mongoc_client_pool_max_size(pool, 150);

WaitQueueTimeout

驱动程序在超时之前尝试从服务器的连接池检出连接的时间长度。

数据类型： integer

默认值： 0

示例：

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_WAITQUEUETIMEOUTMS, 30000);

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

写关注选项

w

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

数据类型： integer or char*

默认值： 1 or "majority"

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?w=2");

wtimeout

写关注（write concern）的 wtimeoutms 组件，用于指定写关注（write concern）的时间限制。要学习；了解有关 wtimeout 选项的更多信息，请参阅MongoDB Server手册中的写关注。

数据类型： integer

默认值： 0

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?wTimeoutMS=5000");

日志

写关注（write concern）的 j 组件，请求确认MongoDB实例已写入磁盘上日志。

数据类型： boolean

默认值： false

要学习；了解有关j 选项的更多信息，请参阅MongoDB Server手册中的写关注。

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?journal=true");

w

数据类型： integer or char*

默认值： 1 or "majority"

您可以使用 MONGOC_URI_W 选项设立w：

示例：

// Use the int32 version of the mongoc_uri_t set function to set integer values
mongoc_uri_set_option_as_int32(uri, MONGOC_URI_W, 2); 
// Use the utf8 version of the mongoc_uri_t set function to set string values 
mongoc_uri_set_option_as_utf8(uri, MONGOC_URI_W, "majority");

您还可以使用 mongoc_write_concern_t 结构设立w：

// Creates a write concern structure
mongoc_write_concern_t *write_concern = mongoc_write_concern_new();
// Sets w=2
mongoc_write_concern_set_w(write_concern, 2);
mongoc_client_set_write_concern(client, write_concern);

wtimeout

数据类型： integer

默认值： 0

您可以使用 MONGOC_URI_WTIMEOUTMS 选项设立wtimeoutms：

示例：

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_WTIMEOUTMS, 5000);

您还可以使用 mongoc_write_concern_t 结构设立wtimeoutms：

// Creates a write concern structure
mongoc_write_concern_t *write_concern = mongoc_write_concern_new();
// Sets w=2
mongoc_write_concern_set_wtimeout(write_concern, 5000);
// Apply write concern to client
mongoc_client_set_write_concern(client, write_concern);

日志

写关注（write concern）的 j 组件，请求确认MongoDB实例已写入磁盘上日志。默认值取决于 writeConcernMajorityJournalDefault 设置中的值。要学习；了解有关 j 选项的更多信息，请参阅MongoDB Server手册中的写关注。

数据类型： boolean

默认值： false

您可以使用 MONGOC_URI_JOURNAL 选项设立journal：

示例：

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_JOURNAL, true);

您还可以使用 mongoc_write_concern_t 结构设立journal：

// Creates a write concern structure
mongoc_write_concern_t *write_concern = mongoc_write_concern_new();
// Sets journal to true
mongoc_write_concern_set_journal(write_concern, true);
// Apply write concern to client
mongoc_client_set_write_concern(client, write_concern);

读关注选项

读关注级别

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

数据类型： char*

默认值： local

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?readConcernLevel=local");

读关注级别

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

数据类型： char*

默认值： local

您可以使用 MONGOC_URI_READCONCERNLEVEL 选项设立读关注（read concern）级别：

示例：

mongoc_uri_set_option_as_utf8(uri, MONGOC_URI_READCONCERNLEVEL, "local")

您还可以使用 mongoc_read_concern_t 结构设立读关注（read concern）级别：

mongoc_read_concern_t *read_concern = mongoc_read_concern_new();
// Set the read concern level to "local"
mongoc_read_concern_set_level(read_concern, MONGOC_READ_CONCERN_LEVEL_LOCAL);
mongoc_client_set_read_concern(client, read_concern);

读取偏好选项

读取偏好

客户端的默认读取偏好设置。有关更多信息，请参阅MongoDB Server手册中的读取偏好。

数据类型： char*

默认值： primary

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?readPreference=primaryPreferred");

maxstaleness

Max Staleness Seconds 表示从节点(secondary node from replica set)可能出现但仍有资格被选择服务器的最长复制延迟（以挂钟时间为单位）。maxStalenessSeconds 的最小允许值为 90 秒。此选项必须与非主节点读取偏好（read preference）一起使用。

数据类型： integer

默认值： -1

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?readPreference=secondary&maxStalenessSeconds=120");

LocalThreshold

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

数据类型： integer

默认值： 15

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?localThresholdMS=150");

读取偏好

客户端的默认读取偏好设置。有关更多信息，请参阅MongoDB Server手册中的读取偏好。

数据类型： char*

默认值： primary

您可以使用 mongoc_read_prefs_t 结构设立读取偏好（read preference）：

示例：

mongoc_client_t *client = mongoc_client_new("mongodb+srv://localhost:27017/");
// Specifies the read preference 
mongoc_read_prefs_t *read_prefs = mongoc_read_prefs_new(MONGOC_READ_PRIMARY_PREFERRED);
mongoc_client_set_read_prefs(client, read_prefs);

您还可以使用 MONGOC_URI_READPREFERENCE 选项设立读取偏好（read preference）：

mongoc_uri_set_option_as_utf8(uri, MONGOC_URI_READPREFERENCE, "primaryPreferred")

maxstaleness

数据类型： integer

默认值： -1

示例：

mongoc_client_t *client = mongoc_client_new("mongodb+srv://localhost:27017/");
mongoc_read_prefs_t *read_prefs = mongoc_read_prefs_new(MONGOC_READ_SECONDARY);
// Specifies max staleness to 120 seconds
mongoc_read_prefs_set_max_staleness_seconds(read_prefs, 120);
mongoc_client_set_read_prefs(client, read_prefs);

LocalThreshold

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

数据类型： integer

默认值： 15

示例：

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_LOCALTHRESHOLDMS, 150);

身份验证选项

身份验证机制

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

要学习；了解有关可用身份验证机制的更多信息，请参阅身份验证机制或企业版身份验证机制指南。

数据类型： char*

默认值： SCRAM-SHA-256 （适用于MongoDB 4.0 及更高版本）

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?authSource=admin&authMechanism=GSSAPI");

身份验证机制

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

要学习；了解有关可用身份验证机制的更多信息，请参阅身份验证机制或企业版身份验证机制指南。

数据类型： char*

默认值： SCRAM-SHA-256 （适用于MongoDB 4.0 及更高版本）

示例：

mongoc_uri_set_auth_mechanism(uri, "GSSAPI");

服务器选择和发现选项

心跳频率

服务器监控检查之间的时间间隔。必须大于或等于 500 毫秒。在池化（多线程）模式下，默认值为 10000 毫秒（10 秒）；在非池化（单线程）模式下，默认值为 60000 毫秒（60 秒）。

数据类型： integer

默认值： 10000 对于池化客户端，60000 对于单线程客户端

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?heartbeatFrequencyMS=5000");

ServerSelectionTimeout

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

数据类型： integer

默认值： 30000

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?serverSelectionTimeoutMS=40000");

套接字检查间隔

仅适用于单线程客户端。如果在此时间内未使用套接字，驾驶员会使用快速的“hello”消息来检查连接。再次使用之前调用。

数据类型： integer

默认值： 5000

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?socketCheckIntervalMS=10000");

心跳频率

数据类型： integer

默认值： 10000

示例：

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_HEARTBEATFREQUENCYMS, 5000);

ServerSelectionTimeout

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

数据类型： integer

默认值： 30000

示例：

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_SERVERSELECTIONTIMEOUTMS, 40000);

套接字检查间隔

仅适用于单线程客户端。如果在此时间内未使用套接字，驾驶员会使用快速的“hello”消息来检查连接。再次使用之前调用。

数据类型： integer

默认值： 5000

示例：

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_SOCKETCHECKINTERVALMS, 10000);

重试选项

retryReads

允许重试读取。

数据类型： boolean

默认值： true

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?retryReads=false");

retryWrites

启用可重试写入。

数据类型： boolean

默认值： true 且支持TLS，否则为 false

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?retryWrites=false");

retryReads

允许重试读取。

数据类型： boolean

默认值： true

示例：

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_RETRYREADS, false)

retryWrites

启用可重试写入。

数据类型： boolean

默认值： true

示例：

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_RETRYWRITES, false);

其他选项

ApplicationName

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

数据类型： char*

默认值：空

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?appName=yourAppName");

LoadBalanced

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

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

数据类型： boolean

默认值： false

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?loadBalanced=true");

SrvMaxHosts

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

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

数据类型： integer

默认值： 0

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?srvMaxHosts=5");

ApplicationName

数据类型： char*

默认值： empty

示例：

mongoc_uri_set_option_as_utf8(uri, MONGOC_URI_APPNAME, "yourAppName");

LoadBalanced

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

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

数据类型： boolean

默认值： false

示例：

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_LOADBALANCED, true);

SrvMaxHosts

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

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

数据类型： integer

默认值： 0

示例：

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_SRVMAXHOSTS, 5);