/ /

Specify Connection Options

Overview

This page describes the connection options available in the C driver and explains how to specify them for your MongoDB connection by using a connection string or URI option.

How to Specify Connection Options

The following sections describe the ways in which you can specify connection options.

Use the Connection String

If you pass a connection string to the monogoc_client_t structure, 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 and the tls option with a value of true:

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

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

Use the URI Options API

You can use URI options to configure connection settings in code rather than in a connection string. 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.

To set connection options by using the URI option, perform the following steps:

Create a mongoc_uri_t struct with your connection string
Use a URI option function to specify your desired connection option
Create a new client with the URI by passing the URI to mongoc_client_new_from_uri()

The following code example shows how to perform the preceding steps:

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

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: boolean

Default Value: false

Example:

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

Replica Set

The name of the replica set to connect to.

Data Type: char*

Default Value: NULL

Example:

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

Direct Connection

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

Data Type: boolean

Default Value: false

Example:

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_DIRECTCONNECTION, true);

Replica Set

The name of the replica set to connect to.

Data Type: char*

Default Value: NULL

Example:

mongoc_uri_set_option_as_utf8(uri, MONGOC_URI_REPLICASET, "yourReplicaSet");

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: boolean

Default Value: false

Example:

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

Allow Insecure TLS

Specifies whether to relax TLS constraints as much as possible. This can include allowing invalid certificates or hostname mismatches.

Data Type: boolean

Default Value: false

Example:

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

TLS Disable Certificate Revocation Check

Whether to disable certificate revocation checking during the TLS handshake.

Data Type: boolean

Default Value: false

Example:

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

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: boolean

Default Value: false

Example:

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_TLS, true);

Allow Insecure TLS

Specifies whether to relax TLS constraints as much as possible. This can include allowing invalid certificates or hostname mismatches.

Data Type: boolean

Default Value: false

Example:

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_TLSINSECURE, true);

TLS Disable Certificate Revocation Check

Whether to disable certificate revocation checking during the TLS handshake.

Data Type: boolean

Default Value: false

Example:

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_TLSDISABLECERTIFICATEREVOCATIONCHECK, true);

For more information on TLS options, see the Configure Transport Layer Security (TLS) 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: integer

Default Value: 10000 (10 seconds)

Example:

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

Socket Timeout

The length of time the driver tries to send or receive on a socket before timing out. The default value is set by the operating system.

Data Type: integer

Default Value: 300000 (5 minutes)

Example:

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

Connect Timeout

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

Data Type: integer

Default Value: 10000 (10 seconds)

Example:

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_CONNECTTIMEOUTMS, 60000);

Socket Timeout

The length of time the driver tries to send or receive on a socket before timing out. The default value is set by the operating system.

Data Type: integer

Default Value: 300000 (5 minutes)

Example:

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_SOCKETTIMEOUTMS, 60000);

Compression Options

Compressors

Data Type: char*

Default Value: NULL

Example:

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

Compressors

Data Type: char*

Default Value: NULL

Example:

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

Connection Pool Options

Max Pool Size

Data Type: integer

Default Value: 100

Example:

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

Wait Queue Timeout

Data Type: integer

Default Value: -1 (no timeout)

Example:

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

Max Connection Pool Size

Data Type: integer

Default Value: 100

Example:

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_MAXPOOLSIZE, 150)

You can also set the max connection pool size by using a mongoc_client_pool_t structure:

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

Wait Queue Timeout

Data Type: integer

Default Value: 0

Example:

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_WAITQUEUETIMEOUTMS, 30000);

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

Write Concern Options

w

Data Type: integer or char*

Default Value: 1 or "majority"

Example:

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

w Timeout

Data Type: integer

Default Value: 0

Example:

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

Journal

The j component of the write concern, which requests acknowledgment that the MongoDB instances have written to the on-disk journal.

Data Type: boolean

Default Value: false

To learn more about the j option, see Write Concern in the MongoDB Server manual.

Example:

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

w

Data Type: integer or char*

Default Value: 1 or "majority"

You can set w by using the MONGOC_URI_W option:

Example:

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

You can also set w by using a mongoc_write_concern_t structure:

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

w Timeout

Data Type: integer

Default Value: 0

You can set wtimeoutms by using the MONGOC_URI_WTIMEOUTMS option:

Example:

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_WTIMEOUTMS, 5000);

You can also set wtimeoutms by using a mongoc_write_concern_t structure:

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

Journal

Data Type: boolean

Default Value: false

You can set journal by using the MONGOC_URI_JOURNAL option:

Example:

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_JOURNAL, true);

You can also set journal by using a mongoc_write_concern_t structure:

// 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 Options

Read Concern Level

Data Type: char*

Default Value: local

Example:

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

Read Concern Level

Data Type: char*

Default Value: local

You can set the read concern level by using the MONGOC_URI_READCONCERNLEVEL option:

Example:

mongoc_uri_set_option_as_utf8(uri, MONGOC_URI_READCONCERNLEVEL, "local")

You can also set the read concern level by using a mongoc_read_concern_t structure:

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

Read Preference Options

Read Preference

Data Type: char*

Default Value: primary

Example:

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

Max Staleness

Data Type: integer

Default Value: -1

Example:

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

Local Threshold

Data Type: integer

Default Value: 15

Example:

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

Read Preference

Data Type: char*

Default Value: primary

You can set the read preference by using a mongoc_read_prefs_t structure:

Example:

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

You can also set the read preference by using the MONGOC_URI_READPREFERENCE option:

mongoc_uri_set_option_as_utf8(uri, MONGOC_URI_READPREFERENCE, "primaryPreferred")

Max Staleness

Data Type: integer

Default Value: -1

Example:

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

Local Threshold

Data Type: integer

Default Value: 15

Example:

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_LOCALTHRESHOLDMS, 150);

Authentication Options

Authentication Mechanism

To learn more about available authentication mechanisms, see the Authentication Mechanisms or the Enterprise Authentication Mechanisms guide.

Data Type: char*

Default Value: SCRAM-SHA-256 (for MongoDB 4.0 and later)

Example:

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

Authentication Mechanism

To learn more about available authentication mechanisms, see the Authentication Mechanisms or the Enterprise Authentication Mechanisms guide.

Data Type: char*

Default Value: SCRAM-SHA-256 (for MongoDB 4.0 and later)

Example:

mongoc_uri_set_auth_mechanism(uri, "GSSAPI");

Server Selection and Discovery Options

Heartbeat Frequency

Data Type: integer

Default Value: 10000 for pooled clients, 60000 for single-threaded clients

Example:

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

Server Selection Timeout

Data Type: integer

Default Value: 30000

Example:

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

Socket Check Interval

Data Type: integer

Default Value: 5000

Example:

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

Heartbeat Frequency

Data Type: integer

Default Value: 10000

Example:

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_HEARTBEATFREQUENCYMS, 5000);

Server Selection Timeout

Data Type: integer

Default Value: 30000

Example:

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_SERVERSELECTIONTIMEOUTMS, 40000);

Socket Check Interval

Data Type: integer

Default Value: 5000

Example:

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_SOCKETCHECKINTERVALMS, 10000);

Retry Options

Retry Reads

Data Type: boolean

Default Value: true

Example:

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

Retry Writes

Data Type: boolean

Default Value: true with TLS support, false otherwise

Example:

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

Retry Reads

Data Type: boolean

Default Value: true

Example:

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_RETRYREADS, false)

Retry Writes

Data Type: boolean

Default Value: true

Example:

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_RETRYWRITES, false);

Miscellaneous Options

Application Name

Data Type: char*

Default Value: empty

Example:

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

Load Balanced

Data Type: boolean

Default Value: false

Example:

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

SrvMaxHosts

Data Type: integer

Default Value: 0

Example:

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

Application Name

Data Type: char*

Default Value: empty

Example:

mongoc_uri_set_option_as_utf8(uri, MONGOC_URI_APPNAME, "yourAppName");

Load Balanced

Data Type: boolean

Default Value: false

Example:

mongoc_uri_set_option_as_bool(uri, MONGOC_URI_LOADBALANCED, true);

SrvMaxHosts

Data Type: integer

Default Value: 0

Example:

mongoc_uri_set_option_as_int32(uri, MONGOC_URI_SRVMAXHOSTS, 5);

Additional Information

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

Back

Create a MongoClient

Network Compression