'\" t .\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "MONGOC_ADVANCED_CONNECTIONS" "3" "Feb 25, 2024" "1.26.0" "libmongoc" .sp The following guide contains information specific to certain types of MongoDB configurations. .sp For an example of connecting to a simple standalone server, see the \fI\%Tutorial\fP\&. To establish a connection with authentication options enabled, see the \fI\%Authentication\fP page. To see an example of a connection with data compression, see the \fI\%Data Compression\fP page. .SH CONNECTING TO A REPLICA SET .sp Connecting to a \fI\%replica set\fP is much like connecting to a standalone MongoDB server. Simply specify the replica set name using the \fB?replicaSet=myreplset\fP URI option. .INDENT 0.0 .INDENT 3.5 .sp .EX #include #include int main (int argc, char *argv[]) { mongoc_client_t *client; mongoc_init (); /* Create our MongoDB Client */ client = mongoc_client_new ( \(dqmongodb://host01:27017,host02:27017,host03:27017/?replicaSet=myreplset\(dq); /* Do some work */ /* TODO */ /* Clean up */ mongoc_client_destroy (client); mongoc_cleanup (); return 0; } .EE .UNINDENT .UNINDENT .sp \fBTIP:\fP .INDENT 0.0 .INDENT 3.5 Multiple hostnames can be specified in the MongoDB connection string URI, with a comma separating hosts in the seed list. .sp It is recommended to use a seed list of members of the replica set to allow the driver to connect to any node. .UNINDENT .UNINDENT .SH CONNECTING TO A SHARDED CLUSTER .sp To connect to a \fI\%sharded cluster\fP, specify the \fBmongos\fP nodes the client should connect to. The C Driver will automatically detect that it has connected to a \fBmongos\fP sharding server. .sp If more than one hostname is specified, a seed list will be created to attempt failover between the \fBmongos\fP instances. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Specifying the \fBreplicaSet\fP parameter when connecting to a \fBmongos\fP sharding server is invalid. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX #include #include int main (int argc, char *argv[]) { mongoc_client_t *client; mongoc_init (); /* Create our MongoDB Client */ client = mongoc_client_new (\(dqmongodb://myshard01:27017/\(dq); /* Do something with client ... */ /* Free the client */ mongoc_client_destroy (client); mongoc_cleanup (); return 0; } .EE .UNINDENT .UNINDENT .SH CONNECTING TO AN IPV6 ADDRESS .sp The MongoDB C Driver will automatically resolve IPv6 addresses from host names. However, to specify an IPv6 address directly, wrap the address in \fB[]\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .EX mongoc_uri_t *uri = mongoc_uri_new (\(dqmongodb://[::1]:27017\(dq); .EE .UNINDENT .UNINDENT .SH CONNECTING WITH IPV4 AND IPV6 .sp If connecting to a hostname that has both IPv4 and IPv6 DNS records, the behavior follows \fI\%RFC\-6555\fP\&. A connection to the IPv6 address is attempted first. If IPv6 fails, then a connection is attempted to the IPv4 address. If the connection attempt to IPv6 does not complete within 250ms, then IPv4 is tried in parallel. Whichever succeeds connection first cancels the other. The successful DNS result is cached for 10 minutes. .sp As a consequence, attempts to connect to a mongod only listening on IPv4 may be delayed if there are both A (IPv4) and AAAA (IPv6) DNS records associated with the host. .sp To avoid a delay, configure hostnames to match the MongoDB configuration. That is, only create an A record if the mongod is only listening on IPv4. .SH CONNECTING TO A UNIX DOMAIN SOCKET .sp On UNIX\-like systems, the C Driver can connect directly to a MongoDB server using a UNIX domain socket. Pass the URL\-encoded path to the socket, which \fImust\fP be suffixed with \fB\&.sock\fP\&. For example, to connect to a domain socket at \fB/tmp/mongodb\-27017.sock\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX mongoc_uri_t *uri = mongoc_uri_new (\(dqmongodb://%2Ftmp%2Fmongodb\-27017.sock\(dq); .EE .UNINDENT .UNINDENT .sp Include username and password like so: .INDENT 0.0 .INDENT 3.5 .sp .EX mongoc_uri_t *uri = mongoc_uri_new (\(dqmongodb://user:pass@%2Ftmp%2Fmongodb\-27017.sock\(dq); .EE .UNINDENT .UNINDENT .SH CONNECTING TO A SERVER OVER TLS .sp These are instructions for configuring TLS/SSL connections. .sp To run a server locally (on port 27017, for example): .INDENT 0.0 .INDENT 3.5 .sp .EX $ mongod \-\-port 27017 \-\-tlsMode requireTLS \-\-tlsCertificateKeyFile server.pem \-\-tlsCAFile ca.pem .EE .UNINDENT .UNINDENT .sp Add \fB/?tls=true\fP to the end of a client URI. .INDENT 0.0 .INDENT 3.5 .sp .EX mongoc_client_t *client = NULL; client = mongoc_client_new (\(dqmongodb://localhost:27017/?tls=true\(dq); .EE .UNINDENT .UNINDENT .sp MongoDB requires client certificates by default, unless the \fB\-\-tlsAllowConnectionsWithoutCertificates\fP is provided. The C Driver can be configured to present a client certificate using the URI option \fBtlsCertificateKeyFile\fP, which may be referenced through the constant \fBMONGOC_URI_TLSCERTIFICATEKEYFILE\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .EX mongoc_client_t *client = NULL; mongoc_uri_t *uri = mongoc_uri_new (\(dqmongodb://localhost:27017/?tls=true\(dq); mongoc_uri_set_option_as_utf8 (uri, MONGOC_URI_TLSCERTIFICATEKEYFILE, \(dqclient.pem\(dq); client = mongoc_client_new_from_uri (uri); .EE .UNINDENT .UNINDENT .sp The client certificate provided by \fBtlsCertificateKeyFile\fP must be issued by one of the server trusted Certificate Authorities listed in \fB\-\-tlsCAFile\fP, or issued by a CA in the native certificate store on the server when omitted. .sp See \fI\%Configuring TLS\fP for more information on the various TLS related options. .SH COMPRESSING DATA TO AND FROM MONGODB .sp This content has been relocated to the \fI\%Data Compression\fP page. .SH ADDITIONAL CONNECTION OPTIONS .sp The full list of connection options can be found in the \fI\%mongoc_uri_t\fP docs. .sp Certain socket/connection related options are not configurable: .TS center; |l|l|l|. _ T{ Option T} T{ Description T} T{ Value T} _ T{ SO_KEEPALIVE T} T{ TCP Keep Alive T} T{ Enabled T} _ T{ TCP_KEEPIDLE T} T{ How long a connection needs to remain idle before TCP starts sending keepalive probes T} T{ 120 seconds T} _ T{ TCP_KEEPINTVL T} T{ The time in seconds between TCP probes T} T{ 10 seconds T} _ T{ TCP_KEEPCNT T} T{ How many probes to send, without acknowledgement, before dropping the connection T} T{ 9 probes T} _ T{ TCP_NODELAY T} T{ Send packets as soon as possible or buffer small packets (Nagle algorithm) T} T{ Enabled (no buffering) T} _ .TE .SH AUTHOR MongoDB, Inc .SH COPYRIGHT 2017-present, MongoDB, Inc .\" Generated by docutils manpage writer. .