1MONGOC_ADVANCED_CONNECTIONS(3) MongoDB C Driver 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
12 Tutorial. To establish a connection with authentication options
13 enabled, 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
89 address 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
96 attempted 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 --sslMode requireSSL --sslPEMKeyFile server.pem --sslCAFile ca.pem
128 Add /?ssl=true to the end of a client URI.
130 mongoc_client_t *client = NULL;
132 client = mongoc_client_new ("mongodb://localhost:27017/?ssl=true");
133 MongoDB requires client certificates by default, unless the --sslAllow‐
135 ConnectionsWithoutCertificates is provided. The C Driver can be config‐
136 ured to present a client certificate using a mongoc_ssl_opt_t:
137 const mongoc_ssl_opt_t *ssl_default = mongoc_ssl_opt_get_default ();
139 mongoc_ssl_opt_t ssl_opts = { 0 };
140 /* optionally copy in a custom trust directory or file; otherwise the default is used. */
142 memcpy (&ssl_opts, ssl_default, sizeof ssl_opts);
143 ssl_opts.pem_file = "client.pem"
144 mongoc_client_set_ssl_opts (client, &ssl_opts);
146 The client certificate provided by pem_file must be issued by one of
148 the server trusted Certificate Authorities listed in --sslCAFile, or
149 issued by a CA in the native certificate store on the server when omit‐
150 ted.
151 To verify the server certificate against a specific CA, provide a PEM
153 armored file with a CA certificate, or concatenated list of CA certifi‐
154 cates using the ca_file option, or c_rehash directory structure of CAs,
155 pointed to using the ca_dir option. When no ca_file or ca_dir is pro‐
156 vided, the driver will use CAs provided by the native platform certifi‐
157 cate store.
158 See mongoc_ssl_opt_t for more information on the various SSL related
160 options.
161
163 MongoDB 3.4 added Snappy compression support, and zlib compression in
164 3.6. To enable compression support the client must be configured with
165 which compressors to use:
166 mongoc_client_t *client = NULL;
168 client = mongoc_client_new ("mongodb://localhost:27017/?compressors=snappy,zlib");
169 The compressors option specifies the priority order of compressors the
171 client wants to use. Messages are compressed if the client and server
172 share any compressors in common.
173 Note that the compressor used by the server might not be the same com‐
175 pressor as the client used. For example, if the client uses the con‐
176 nection string compressors=zlib,snappy the client will use zlib com‐
177 pression to send data (if possible), but the server might still reply
178 using snappy, depending on how the server was configured.
179 The driver must be built with zlib and/or snappy support to enable com‐
181 pression support, any unknown (or not compiled in) compressor value
182 will be ignored.
183
185 The full list of connection options can be found in the mongoc_uri_t
186 docs.
187 Certain socket/connection related options are not configurable:
189 ┌──────────────┬─────────────────────┬─────────────────────┐
191 │Option │ Description │ Value │
192 ├──────────────┼─────────────────────┼─────────────────────┤
193 │SO_KEEPALIVE │ TCP Keep Alive │ Enabled │
194 └──────────────┴─────────────────────┴─────────────────────┘
195 │TCP_KEEPIDLE │ How long a connec‐ │ 300 seconds │
200 │ │ tion needs to │ │
201 │ │ remain idle before │ │
202 │ │ TCP starts sending │ │
203 │ │ keepalive probes │ │
204 ├──────────────┼─────────────────────┼─────────────────────┤
205 │TCP_KEEPINTVL │ The time in seconds │ 10 seconds │
206 │ │ between TCP probes │ │
207 ├──────────────┼─────────────────────┼─────────────────────┤
208 │TCP_KEEPCNT │ How many probes to │ 9 probes │
209 │ │ send, without │ │
210 │ │ acknowledgement, │ │
211 │ │ before dropping the │ │
212 │ │ connection │ │
213 ├──────────────┼─────────────────────┼─────────────────────┤
214 │TCP_NODELAY │ Send packets as │ Enabled (no buffer‐ │
215 │ │ soon as possible or │ ing) │
216 │ │ buffer small pack‐ │ │
217 │ │ ets (Nagle algo‐ │ │
218 │ │ rithm) │ │
219 └──────────────┴─────────────────────┴─────────────────────┘
220
222 MongoDB, Inc
223
225 2017-present, MongoDB, Inc
2261.13.1 Jan 24, 2019 MONGOC_ADVANCED_CONNECTIONS(3)