对于 AI 代理：可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。

指定连接选项

Overview

本页面介绍了 C 驱动程序中可用的连接选项，并说明了如何通过使用连接字符串或 URI 选项为您的 MongoDB 连接指定这些选项。

如何指定连接选项

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

使用连接字符串

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

mongoc_init();
// Specifies the connection options in the connection stringconst char *uri = "mongodb+srv://localhost:27017/?connectTimeoutMS=60000&tls=true";
// Creates a new clientmongoc_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 选项设立连接选项，请执行以下步骤：

  1. 使用连接字符串创建一个 mongoc_uri_t 结构

  2. 使用 URI 选项函数指定所需的连接选项

  3. 创建具有该 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 APIif (!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 clientclient = 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");

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)指南。

超时选项

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");

压缩选项

compressors

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

数据类型： char*

默认值： NULL

示例：

mongoc_uri_t *uri = mongoc_uri_new("mongodb+srv://localhost:27017/?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");

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

写关注选项

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 手册中的 写关注（write concern）。

示例：

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

读关注选项

读关注级别

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

数据类型： char*

默认值： local

示例：

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

读取偏好选项

读取偏好

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

数据类型： 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 进行身份验证的机制。如果您未指定身份验证机制，驱动程序将使用 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");

服务器选择和发现选项

心跳频率

服务器监控检查之间的时间间隔。必须大于或等于 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");

重试选项

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");

注意

智能工作负载管理 (IWM) 中的负载削减

如果带有 SystemOverloadedError 或 RetryableError 标签的错误导致您的应用程序出现故障或出现在您的应用程序日志中，则说明您的集群上可能已启用负载削减 (Load Shedding)，并且您的驱动程序可能未升级到支持该功能的版本。我们建议将您的 MongoDB C 驱动程序升级到 2.3 或更高版本。如果您在升级后仍然看到这些错误，可以通过服务器端更改（例如查看您的负载削减配置）或通过应用程序端更改（例如实现自定义错误处理或客户端请求限制）来解决这些错误。根据您的情况，应用程序端更改可能是更可取或必要的。

负载削减 (Load Shedding) 是 IWM 的一项功能，有助于在持续过载期间通过拒绝多余的操作来管理服务器负载。此功能适用于 MongoDB 9.0 及更高版本。

有关 IWM 或处理超载错误的更多信息，请参阅 智能工作负载管理 页面或 超载错误 页面中的 Atlas 文档。

其他选项

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");

更多信息

有关此页面上使用的类型的更多信息，请参阅以下API文档：

后退
创建 MongoClient
来年
网络压缩
给本页内容打分

在此页面上