Provided by: libmongoc-doc_1.15.0-1_all bug

NAME

       mongoc_advanced_connections - Advanced Connections

       The   following   guide   contains  information  specific  to  certain  types  of  MongoDB
       configurations.

       For an example of connecting to a simple standalone server, see the Tutorial. To establish
       a connection with authentication options enabled, see the Authentication page.

CONNECTING TO A REPLICA SET

       Connecting to a replica set is much like connecting to a standalone MongoDB server. Simply
       specify the replica set name using the ?replicaSet=myreplset URI option.

          #include <bson/bson.h>
          #include <mongoc/mongoc.h>

          int
          main (int argc, char *argv[])
          {
             mongoc_client_t *client;

             mongoc_init ();

             /* Create our MongoDB Client */
             client = mongoc_client_new (
                "mongodb://host01:27017,host02:27017,host03:27017/?replicaSet=myreplset");

             /* Do some work */
             /* TODO */

             /* Clean up */
             mongoc_client_destroy (client);
             mongoc_cleanup ();

             return 0;
          }

       TIP:
          Multiple hostnames can be specified in the MongoDB connection string URI, with a  comma
          separating hosts in the seed list.

          It  is recommended to use a seed list of members of the replica set to allow the driver
          to connect to any node.

CONNECTING TO A SHARDED CLUSTER

       To connect to a sharded cluster, specify the mongos nodes the client  should  connect  to.
       The C Driver will automatically detect that it has connected to a mongos sharding server.

       If  more  than  one hostname is specified, a seed list will be created to attempt failover
       between the mongos instances.

       WARNING:
          Specifying the replicaSet parameter when connecting to  a  mongos  sharding  server  is
          invalid.

          #include <bson/bson.h>
          #include <mongoc/mongoc.h>

          int
          main (int argc, char *argv[])
          {
             mongoc_client_t *client;

             mongoc_init ();

             /* Create our MongoDB Client */
             client = mongoc_client_new ("mongodb://myshard01:27017/");

             /* Do something with client ... */

             /* Free the client */
             mongoc_client_destroy (client);

             mongoc_cleanup ();

             return 0;
          }

CONNECTING TO AN IPV6 ADDRESS

       The  MongoDB  C Driver will automatically resolve IPv6 addresses from host names. However,
       to specify an IPv6 address directly, wrap the address in [].

          mongoc_uri_t *uri = mongoc_uri_new ("mongodb://[::1]:27017");

CONNECTING WITH IPV4 AND IPV6

       If connecting to a hostname that has both IPv4 and IPv6 DNS records, the behavior  follows
       RFC-6555.  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.

       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.

       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.

CONNECTING TO A UNIX DOMAIN SOCKET

       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 must be suffixed with .sock.
       For example, to connect to a domain socket at /tmp/mongodb-27017.sock:

          mongoc_uri_t *uri = mongoc_uri_new ("mongodb://%2Ftmp%2Fmongodb-27017.sock");

       Include username and password like so:

          mongoc_uri_t *uri = mongoc_uri_new ("mongodb://user:pass@%2Ftmp%2Fmongodb-27017.sock");

CONNECTING TO A SERVER OVER SSL

       These are instructions for configuring TLS/SSL connections.

       To run a server locally (on port 27017, for example):

          $ mongod --port 27017 --sslMode requireSSL --sslPEMKeyFile server.pem --sslCAFile ca.pem

       Add /?ssl=true to the end of a client URI.

          mongoc_client_t *client = NULL;
          client = mongoc_client_new ("mongodb://localhost:27017/?ssl=true");

       MongoDB     requires     client     certificates     by      default,      unless      the
       --sslAllowConnectionsWithoutCertificates  is  provided.  The C Driver can be configured to
       present a client certificate using a mongoc_ssl_opt_t:

          const mongoc_ssl_opt_t *ssl_default = mongoc_ssl_opt_get_default ();
          mongoc_ssl_opt_t ssl_opts = { 0 };

          /* optionally copy in a custom trust directory or file; otherwise the default is used. */
          memcpy (&ssl_opts, ssl_default, sizeof ssl_opts);
          ssl_opts.pem_file = "client.pem"

          mongoc_client_set_ssl_opts (client, &ssl_opts);

       The client certificate provided by pem_file must be issued by one of  the  server  trusted
       Certificate Authorities listed in --sslCAFile, or issued by a CA in the native certificate
       store on the server when omitted.

       To verify the server certificate against a specific CA, provide a PEM armored file with  a
       CA  certificate,  or  concatenated  list  of  CA certificates using the ca_file option, or
       c_rehash directory structure of CAs, pointed to using the ca_dir option. When  no  ca_file
       or ca_dir is provided, the driver will use CAs provided by the native platform certificate
       store.

       See mongoc_ssl_opt_t for more information on the various SSL related options.

COMPRESSING DATA TO AND FROM MONGODB

       MongoDB  3.4  added  Snappy  compression  support,  zlib  compression  in  3.6,  and  zstd
       compression  in  4.2.   To  enable  compression support the client must be configured with
       which compressors to use:

          mongoc_client_t *client = NULL;
          client = mongoc_client_new ("mongodb://localhost:27017/?compressors=snappy,zlib,zstd");

       The compressors option specifies the priority order of compressors  the  client  wants  to
       use. Messages are compressed if the client and server share any compressors in common.

       Note that the compressor used by the server might not be the same compressor as the client
       used.  For example, if the client uses the connection string  compressors=zlib,snappy  the
       client  will  use  zlib compression to send data (if possible), but the server might still
       reply using snappy, depending on how the server was configured.

       The driver must be built with zlib and/or snappy and/or zstd support to enable compression
       support, any unknown (or not compiled in) compressor value will be ignored. Note: to build
       with zstd requires cmake 3.12 or higher.

ADDITIONAL CONNECTION OPTIONS

       The full list of connection options can be found in the mongoc_uri_t docs.

       Certain socket/connection related options are not configurable:

                  ┌──────────────┬──────────────────────────┬────────────────────────┐
                  │Option        │ Description              │ Value                  │
                  ├──────────────┼──────────────────────────┼────────────────────────┤
                  │SO_KEEPALIVE  │ TCP Keep Alive           │ Enabled                │
                  ├──────────────┼──────────────────────────┼────────────────────────┤
                  │TCP_KEEPIDLE  │ How  long  a  connection │ 300 seconds            │
                  │              │ needs   to  remain  idle │                        │
                  │              │ before    TCP     starts │                        │
                  │              │ sending keepalive probes │                        │
                  ├──────────────┼──────────────────────────┼────────────────────────┤
                  │TCP_KEEPINTVL │ The   time   in  seconds │ 10 seconds             │
                  │              │ between TCP probes       │                        │
                  ├──────────────┼──────────────────────────┼────────────────────────┤
                  │TCP_KEEPCNT   │ How many probes to send, │ 9 probes               │
                  │              │ without acknowledgement, │                        │
                  │              │ before   dropping    the │                        │
                  │              │ connection               │                        │
                  ├──────────────┼──────────────────────────┼────────────────────────┤
                  │TCP_NODELAY   │ Send  packets as soon as │ Enabled (no buffering) │
                  │              │ possible or buffer small │                        │
                  │              │ packets           (Nagle │                        │
                  │              │ algorithm)               │                        │
                  └──────────────┴──────────────────────────┴────────────────────────┘

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2017-present, MongoDB, Inc