Connect to MongoDB

Overview

This page contains code examples that show how to connect your C++ application to MongoDB with various settings.

Tip

To learn more about the connection options on this page, see the link provided in each section.

To use a connection example from this page, copy the code example into the sample application or your own application. Be sure to replace all placeholders in the code examples, such as <hostname>, with the relevant values for your MongoDB deployment.

Sample Application

You can use the following sample application to test the code examples on this page. To use the sample application, perform the following steps:

Ensure you have the C++ driver installed in a location from which your project can import it.
Copy the following code and paste it into a new .cpp file within your project.
Copy a code example from this page and paste it within the highlighted section of the file.

1 #include <bsoncxx/json.hpp>
2 
3 #include <mongocxx/client.hpp>
4 #include <mongocxx/exception/exception.hpp>
5 #include <mongocxx/instance.hpp>
6 #include <mongocxx/uri.hpp>
7 
8 #include <iostream>
9 
10 int main()
11 {
12     mongocxx::instance instance;
13 
14     try
15     {
16         // Start example code here
17 
18         // End example code here
19 
20         auto admin = client["admin"];
21         admin.run_command(bsoncxx::from_json(R"({ "ping": 1 })"));
22 
23         std::cout << "Successfully pinged the MongoDB server." << std::endl;
24     }
25     catch (const mongocxx::exception &e)
26     {
27         std::cout << "An exception occurred: " << e.what() << std::endl;
28         return EXIT_FAILURE;
29     }
30 
31     return EXIT_SUCCESS;
32 }

Connection

Atlas

The following code shows how to connect to a MongoDB Atlas deployment:

mongocxx::uri uri("<Atlas connection string>");
mongocxx::client client(uri);

To learn more about connecting to an Atlas deployment, see Atlas in the Connection Targets guide.

Local Deployment

The following code shows how to connect to a local MongoDB deployment:

mongocxx::uri uri("mongodb://localhost:27017/");
mongocxx::client client(uri);

To learn more about connecting to a local deployment, see Local Deployments in the Connection Targets guide.

Replica Set

The following code shows how to connect to a replica set deployment:

mongocxx::uri uri("mongodb://<replica set member>:<port>/?replicaSet=<replica set name>");
mongocxx::client client(uri);

To learn more about connecting to a replica set, see Replica Sets in the Connection Targets guide.

Transport Layer Security (TLS)

Enable TLS

The following code shows how to enable TLS for the connection to your MongoDB instance:

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true");
mongocxx::client client(uri);

To learn more about enabling TLS, see Enable TLS in the TLS configuration guide.

Specify a Certificate Authority (CA) File

The following code shows how to specify the path to your CA file for the connection to your MongoDB instance:

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.pem_file("/path/to/file.pem");
client_options.tls_opts(tls_options);
mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true");
mongocxx::client client(uri, client_options);

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsCAFile=/path/to/file.pem");

To learn more about specifying a CA file, see Specify a CA File in the TLS configuration guide.

Disable OCSP Checks

The following code shows how to prevent the driver from contacting the OCSP endpoint:

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsDisableOCSPEndpointCheck=true");
mongocxx::client client(uri);

To learn more about disabling OCSP checks, see OCSP in the TLS configuration guide.

Specify a Certificate Revocation List (CRL)

The following code shows how to instruct the driver to verify the server's certificate against a CRL:

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.crl_file("<path to your CRL file>");
client_options.tls_opts(tls_options);
mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true");
mongocxx::client client(uri, client_options);

To learn more about specifying a CRL, see Certificate Revocation List in the TLS configuration guide.

Present a Client Certificate

The following code shows how to specify the client certificate that the driver presents to your MongoDB deployment:

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.pem_file("/path/to/file.pem");
client_options.tls_opts(tls_options);
mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true");
mongocxx::client client(uri, client_options);

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/file.pem");

To learn more about specifying a client certificate, see Present a Client Certificate in the TLS configuration guide.

Provide a Certificate Key File Password

The following code shows how to specify the password for your client certificate:

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.pem_file("/path/to/file.pem");
tls_options.pem_password("<password>");
client_options.tls_opts(tls_options);
mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true");
mongocxx::client client(uri, client_options);

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/file.pem&tlsCertificateKeyFilePassword=<password>");

To learn more about providing a key file password, see Provide a Key Password in the TLS configuration guide.

Allow Insecure TLS

The following code shows how to disable certificate verification:

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsInsecure=true");
mongocxx::client client(uri);

To learn more about allowing insecure TLS, see Allow Insecure TLS in the TLS configuration guide.

Disable Certificate Validation

The following code shows how to disable certificate validation:

mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
tls_options.allow_invalid_certificates(true);
client_options.tls_opts(tls_options);
mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true");
mongocxx::client client(uri, client_options);

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsAllowInvalidCertificates=true");

To learn more about disabling certificate validation, see Allow Insecure TLS in the TLS configuration guide.

Disable Hostname Verification

The following code shows how to disable hostname verification:

mongocxx::uri uri("mongodb://<hostname>:<port>/?tls=true&tlsAllowInvalidHostnames=true");
mongocxx::client client(uri);

To learn more about disabling hostname verification, see Allow Insecure TLS in the TLS configuration guide.

Network Compression

Compression Algorithms

The following code shows how to enable compression for the connection to your MongoDB instance by specifying each compression algorithm:

mongocxx::uri uri("mongodb://<hostname>:<port>/?compressors=snappy,zstd,zlib");
mongocxx::client client(uri);

To learn more about specifying compression algorithms, see Specify Compression Algorithms in the Network Compression guide.

zlib Compression Level

The following code shows how to specify the zlib compression algorithm and set its compression level:

mongocxx::uri uri("mongodb://<hostname>:<port>/?compressors=zlib&zlibCompressionLevel=1");
mongocxx::client client(uri);

To learn more about setting the zlib compression level, see Specify Compression Algorithms in the Network Compression guide.

Stable API

The following code shows how to enable the Stable API for the connection to your MongoDB instance:

mongocxx::uri uri("<connection string>");
mongocxx::options::client client_options;
mongocxx::options::server_api server_api_options(mongocxx::options::server_api::version::k_version_1);
client_options.server_api_opts(server_api_options);
mongocxx::client client(uri, client_options);

To learn more about the Stable API, see the Stable API guide.

Back

Next Steps

Create a Driver Instance

1	#include <bsoncxx/json.hpp>
2
3	#include <mongocxx/client.hpp>
4	#include <mongocxx/exception/exception.hpp>
5	#include <mongocxx/instance.hpp>
6	#include <mongocxx/uri.hpp>
7
8	#include <iostream>
9
10	int main()
11	{
12	mongocxx::instance instance;
13
14	try
15	{
16	// Start example code here
17
18	// End example code here
19
20	auto admin = client["admin"];
21	admin.run_command(bsoncxx::from_json(R"({ "ping": 1 })"));
22
23	std::cout << "Successfully pinged the MongoDB server." << std::endl;
24	}
25	catch (const mongocxx::exception &e)
26	{
27	std::cout << "An exception occurred: " << e.what() << std::endl;
28	return EXIT_FAILURE;
29	}
30
31	return EXIT_SUCCESS;
32	}