1MONGOC_ADVANCED_CONNECTIONS(3) libmongoc MONGOC_ADVANCED_CONNECTIONS(3)
2
6 mongoc_advanced_connections - Advanced Connections
7 The following guide contains information specific to certain types of
9 MongoDB configurations.
10 For an example of connecting to a simple standalone server, see the Tu‐
12 torial. To establish a connection with authentication options enabled,
13 see the Authentication page.
14
16 Connecting to a replica set is much like connecting to a standalone
17 MongoDB server. Simply specify the replica set name using the ?repli‐
18 caSet=myreplset URI option.
19 #include <bson/bson.h>
21 #include <mongoc/mongoc.h>
22 int
24 main (int argc, char *argv[])
25 {
26 mongoc_client_t *client;
27 mongoc_init ();
29 /* Create our MongoDB Client */
31 client = mongoc_client_new (
32 "mongodb://host01:27017,host02:27017,host03:27017/?replicaSet=myreplset");
33 /* Do some work */
35 /* TODO */
36 /* Clean up */
38 mongoc_client_destroy (client);
39 mongoc_cleanup ();
40 return 0;
42 }
43 TIP:
45 Multiple hostnames can be specified in the MongoDB connection string
46 URI, with a comma separating hosts in the seed list.
47 It is recommended to use a seed list of members of the replica set
49 to allow the driver to connect to any node.
50
52 To connect to a sharded cluster, specify the mongos nodes the client
53 should connect to. The C Driver will automatically detect that it has
54 connected to a mongos sharding server.
55 If more than one hostname is specified, a seed list will be created to
57 attempt failover between the mongos instances.
58 WARNING:
60 Specifying the replicaSet parameter when connecting to a mongos
61 sharding server is invalid.
62 #include <bson/bson.h>
64 #include <mongoc/mongoc.h>
65 int
67 main (int argc, char *argv[])
68 {
69 mongoc_client_t *client;
70 mongoc_init ();
72 /* Create our MongoDB Client */
74 client = mongoc_client_new ("mongodb://myshard01:27017/");
75 /* Do something with client ... */
77 /* Free the client */
79 mongoc_client_destroy (client);
80 mongoc_cleanup ();
82 return 0;
84 }
85
87 The MongoDB C Driver will automatically resolve IPv6 addresses from
88 host names. However, to specify an IPv6 address directly, wrap the ad‐
89 dress in [].
90 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://[::1]:27017");
92
94 If connecting to a hostname that has both IPv4 and IPv6 DNS records,
95 the behavior follows RFC-6555. A connection to the IPv6 address is at‐
96 tempted first. If IPv6 fails, then a connection is attempted to the
97 IPv4 address. If the connection attempt to IPv6 does not complete
98 within 250ms, then IPv4 is tried in parallel. Whichever succeeds con‐
99 nection first cancels the other. The successful DNS result is cached
100 for 10 minutes.
101 As a consequence, attempts to connect to a mongod only listening on
103 IPv4 may be delayed if there are both A (IPv4) and AAAA (IPv6) DNS
104 records associated with the host.
105 To avoid a delay, configure hostnames to match the MongoDB configura‐
107 tion. That is, only create an A record if the mongod is only listening
108 on IPv4.
109
111 On UNIX-like systems, the C Driver can connect directly to a MongoDB
112 server using a UNIX domain socket. Pass the URL-encoded path to the
113 socket, which must be suffixed with .sock. For example, to connect to a
114 domain socket at /tmp/mongodb-27017.sock:
115 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://%2Ftmp%2Fmongodb-27017.sock");
117 Include username and password like so:
119 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://user:pass@%2Ftmp%2Fmongodb-27017.sock");
121
123 These are instructions for configuring TLS/SSL connections.
124 To run a server locally (on port 27017, for example):
126 $ mongod --port 27017 --tlsMode requireTLS --tlsCertificateKeyFile server.pem --tlsCAFile ca.pem
128 Add /?tls=true to the end of a client URI.
130 mongoc_client_t *client = NULL;
132 client = mongoc_client_new ("mongodb://localhost:27017/?tls=true");
133 MongoDB requires client certificates by default, unless the --tlsAllow‐
135 ConnectionsWithoutCertificates is provided. The C Driver can be config‐
136 ured to present a client certificate using the URI option tlsCertifi‐
137 cateKeyFile, which may be referenced through the constant MON‐
138 GOC_URI_TLSCERTIFICATEKEYFILE.
139 mongoc_client_t *client = NULL;
141 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017/?tls=true");
142 mongoc_uri_set_option_as_utf8 (uri, MONGOC_URI_TLSCERTIFICATEKEYFILE, "client.pem");
143 client = mongoc_client_new_from_uri (uri);
145 The client certificate provided by tlsCertificateKeyFile must be issued
147 by one of the server trusted Certificate Authorities listed in
148 --tlsCAFile, or issued by a CA in the native certificate store on the
149 server when omitted.
150 See configuring_tls for more information on the various TLS related op‐
152 tions.
153
155 MongoDB 3.4 added Snappy compression support, zlib compression in 3.6,
156 and zstd compression in 4.2. To enable compression support the client
157 must be configured with which compressors to use:
158 mongoc_client_t *client = NULL;
160 client = mongoc_client_new ("mongodb://localhost:27017/?compressors=snappy,zlib,zstd");
161 The compressors option specifies the priority order of compressors the
163 client wants to use. Messages are compressed if the client and server
164 share any compressors in common.
165 Note that the compressor used by the server might not be the same com‐
167 pressor as the client used. For example, if the client uses the con‐
168 nection string compressors=zlib,snappy the client will use zlib com‐
169 pression to send data (if possible), but the server might still reply
170 using snappy, depending on how the server was configured.
171 The driver must be built with zlib and/or snappy and/or zstd support to
173 enable compression support, any unknown (or not compiled in) compressor
174 value will be ignored. Note: to build with zstd requires cmake 3.12 or
175 higher.
176
178 The full list of connection options can be found in the mongoc_uri_t
179 docs.
180 Certain socket/connection related options are not configurable:
182 ┌──────────────┬─────────────────────┬─────────────────────┐
184 │Option │ Description │ Value │
185 ├──────────────┼─────────────────────┼─────────────────────┤
186 │SO_KEEPALIVE │ TCP Keep Alive │ Enabled │
187 ├──────────────┼─────────────────────┼─────────────────────┤
188 │TCP_KEEPIDLE │ How long a connec‐ │ 120 seconds │
189 │ │ tion needs to re‐ │ │
190 │ │ main idle before │ │
191 │ │ TCP starts sending │ │
192 │ │ keepalive probes │ │
193 ├──────────────┼─────────────────────┼─────────────────────┤
194 │TCP_KEEPINTVL │ The time in seconds │ 10 seconds │
195 │ │ between TCP probes │ │
196 └──────────────┴─────────────────────┴─────────────────────┘
197 │TCP_KEEPCNT │ How many probes to │ 9 probes │
200 │ │ send, without ac‐ │ │
201 │ │ knowledgement, be‐ │ │
202 │ │ fore dropping the │ │
203 │ │ connection │ │
204 ├──────────────┼─────────────────────┼─────────────────────┤
205 │TCP_NODELAY │ Send packets as │ Enabled (no buffer‐ │
206 │ │ soon as possible or │ ing) │
207 │ │ buffer small pack‐ │ │
208 │ │ ets (Nagle algo‐ │ │
209 │ │ rithm) │ │
210 └──────────────┴─────────────────────┴─────────────────────┘
211
213 MongoDB, Inc
214
216 2017-present, MongoDB, Inc
2171.21.1 Mar 02, 2022 MONGOC_ADVANCED_CONNECTIONS(3)