1MONGOC_ADVANCED_CONNECTIONS(3) libmongoc MONGOC_ADVANCED_CONNECTIONS(3)
2The following guide contains information specific to certain types of MongoDB
6configurations.
7For an example of connecting to a simple standalone server, see the Tutorial.
9To establish a connection with authentication options enabled, see the
11see the Data Compression page.
12
14 Connecting to a replica set is much like connecting to a standalone
15 MongoDB server. Simply specify the replica set name using the ?repli‐
16 caSet=myreplset URI option.
17 #include <bson/bson.h>
19 #include <mongoc/mongoc.h>
20 int
22 main (int argc, char *argv[])
23 {
24 mongoc_client_t *client;
25 mongoc_init ();
27 /* Create our MongoDB Client */
29 client = mongoc_client_new (
30 "mongodb://host01:27017,host02:27017,host03:27017/?replicaSet=myreplset");
31 /* Do some work */
33 /* TODO */
34 /* Clean up */
36 mongoc_client_destroy (client);
37 mongoc_cleanup ();
38 return 0;
40 }
41 TIP:
43 Multiple hostnames can be specified in the MongoDB connection string
44 URI, with a comma separating hosts in the seed list.
45 It is recommended to use a seed list of members of the replica set
47 to allow the driver to connect to any node.
48
50 To connect to a sharded cluster, specify the mongos nodes the client
51 should connect to. The C Driver will automatically detect that it has
52 connected to a mongos sharding server.
53 If more than one hostname is specified, a seed list will be created to
55 attempt failover between the mongos instances.
56 WARNING:
58 Specifying the replicaSet parameter when connecting to a mongos
59 sharding server is invalid.
60 #include <bson/bson.h>
62 #include <mongoc/mongoc.h>
63 int
65 main (int argc, char *argv[])
66 {
67 mongoc_client_t *client;
68 mongoc_init ();
70 /* Create our MongoDB Client */
72 client = mongoc_client_new ("mongodb://myshard01:27017/");
73 /* Do something with client ... */
75 /* Free the client */
77 mongoc_client_destroy (client);
78 mongoc_cleanup ();
80 return 0;
82 }
83
85 The MongoDB C Driver will automatically resolve IPv6 addresses from
86 host names. However, to specify an IPv6 address directly, wrap the ad‐
87 dress in [].
88 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://[::1]:27017");
90
92 If connecting to a hostname that has both IPv4 and IPv6 DNS records,
93 the behavior follows RFC-6555. A connection to the IPv6 address is at‐
94 tempted first. If IPv6 fails, then a connection is attempted to the
95 IPv4 address. If the connection attempt to IPv6 does not complete
96 within 250ms, then IPv4 is tried in parallel. Whichever succeeds con‐
97 nection first cancels the other. The successful DNS result is cached
98 for 10 minutes.
99 As a consequence, attempts to connect to a mongod only listening on
101 IPv4 may be delayed if there are both A (IPv4) and AAAA (IPv6) DNS
102 records associated with the host.
103 To avoid a delay, configure hostnames to match the MongoDB configura‐
105 tion. That is, only create an A record if the mongod is only listening
106 on IPv4.
107
109 On UNIX-like systems, the C Driver can connect directly to a MongoDB
110 server using a UNIX domain socket. Pass the URL-encoded path to the
111 socket, which must be suffixed with .sock. For example, to connect to a
112 domain socket at /tmp/mongodb-27017.sock:
113 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://%2Ftmp%2Fmongodb-27017.sock");
115 Include username and password like so:
117 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://user:pass@%2Ftmp%2Fmongodb-27017.sock");
119
121 These are instructions for configuring TLS/SSL connections.
122 To run a server locally (on port 27017, for example):
124 $ mongod --port 27017 --tlsMode requireTLS --tlsCertificateKeyFile server.pem --tlsCAFile ca.pem
126 Add /?tls=true to the end of a client URI.
128 mongoc_client_t *client = NULL;
130 client = mongoc_client_new ("mongodb://localhost:27017/?tls=true");
131 MongoDB requires client certificates by default, unless the --tlsAllow‐
133 ConnectionsWithoutCertificates is provided. The C Driver can be config‐
134 ured to present a client certificate using the URI option tlsCertifi‐
135 cateKeyFile, which may be referenced through the constant MON‐
136 GOC_URI_TLSCERTIFICATEKEYFILE.
137 mongoc_client_t *client = NULL;
139 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017/?tls=true");
140 mongoc_uri_set_option_as_utf8 (uri, MONGOC_URI_TLSCERTIFICATEKEYFILE, "client.pem");
141 client = mongoc_client_new_from_uri (uri);
143 The client certificate provided by tlsCertificateKeyFile must be issued
145 by one of the server trusted Certificate Authorities listed in
146 --tlsCAFile, or issued by a CA in the native certificate store on the
147 server when omitted.
148 See Configuring TLS for more information on the various TLS related op‐
150 tions.
151
153 This content has been relocated to the Data Compression page.
154
156 The full list of connection options can be found in the mongoc_uri_t
157 docs.
158 Certain socket/connection related options are not configurable:
160 ┌──────────────┬─────────────────────┬─────────────────────┐
162 │Option │ Description │ Value │
163 ├──────────────┼─────────────────────┼─────────────────────┤
164 │SO_KEEPALIVE │ TCP Keep Alive │ Enabled │
165 ├──────────────┼─────────────────────┼─────────────────────┤
166 │TCP_KEEPIDLE │ How long a connec‐ │ 120 seconds │
167 │ │ tion needs to re‐ │ │
168 │ │ main idle before │ │
169 │ │ TCP starts sending │ │
170 │ │ keepalive probes │ │
171 ├──────────────┼─────────────────────┼─────────────────────┤
172 │TCP_KEEPINTVL │ The time in seconds │ 10 seconds │
173 │ │ between TCP probes │ │
174 ├──────────────┼─────────────────────┼─────────────────────┤
175 │TCP_KEEPCNT │ How many probes to │ 9 probes │
176 │ │ send, without ac‐ │ │
177 │ │ knowledgement, be‐ │ │
178 │ │ fore dropping the │ │
179 │ │ connection │ │
180 ├──────────────┼─────────────────────┼─────────────────────┤
181 │TCP_NODELAY │ Send packets as │ Enabled (no buffer‐ │
182 │ │ soon as possible or │ ing) │
183 │ │ buffer small pack‐ │ │
184 │ │ ets (Nagle algo‐ │ │
185 │ │ rithm) │ │
186 └──────────────┴─────────────────────┴─────────────────────┘
187
189 MongoDB, Inc
190
192 2017-present, MongoDB, Inc
1931.25.1 Nov 08, 2023 MONGOC_ADVANCED_CONNECTIONS(3)