Choose a Connection Target

On this page

Overview

Atlas
Local Deployments
Replica Sets
Initialization
API Documentation

Overview

In this guide, you can learn how to use a connection string and mongocxx::client object to connect to different types of MongoDB deployments.

Atlas

To connect to a MongoDB deployment on Atlas, include the following elements in your connection string:

URI of your Atlas cluster
MongoDB username
MongoDB password

Then, pass your connection string to the mongocxx::uri constructor, and use the mongocxx::uri object to construct a mongocxx::client object.

When you connect to Atlas, we recommend using the Stable API client option to avoid breaking changes when Atlas upgrades to a new version of MongoDB Server. To learn more about the Stable API feature, see the Stable API page.

The following code shows how to use the C++ driver to connect to an Atlas cluster. The code also uses the server_api_opts option to specify a Stable API version.

#include <mongocxx/instance.hpp>
#include <mongocxx/client.hpp>
#include <mongocxx/uri.hpp>
#include <bsoncxx/json.hpp>
#include <mongocxx/exception/exception.hpp>
using bsoncxx::builder::basic::kvp;
using bsoncxx::builder::basic::make_document;
int main()
{
    mongocxx::instance instance;
    // Replace the placeholder with your Atlas connection string
    mongocxx::uri uri("<connection string>");
    // Create a mongocxx::client with a mongocxx::options::client object to set the Stable API version
    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);
    try
    {
        // Ping the server to verify that the connection works
        auto admin = client["admin"];
        auto command = make_document(kvp("ping", 1));
        auto result = admin.run_command(command.view());
        std::cout << bsoncxx::to_json(result) << "\n";
        std::cout << "Pinged your deployment. You successfully connected to MongoDB!\n";
    }
    catch (const mongocxx::exception &e)
    {
        std::cerr << "An exception occurred: " << e.what() << "\n";
        return EXIT_FAILURE;
    }
}

Tip

Follow the Atlas driver connection guide to retrieve your connection string.

Local Deployments

To connect to a local MongoDB deployment, use localhost as the hostname. By default, the mongod process runs on port 27017, though you can customize this for your deployment.

The following code shows how to use the C++ driver to connect to a local MongoDB deployment:

#include <mongocxx/instance.hpp>
#include <mongocxx/uri.hpp>
#include <mongocxx/client.hpp>
int main()
{
    mongocxx::instance instance;
    mongocxx::uri uri("mongodb://localhost:27017");
    mongocxx::client client(uri);
}

Replica Sets

To connect to a replica set, specify the hostnames (or IP addresses) and port numbers of the replica set members in your connection string.

If you aren't able to provide a full list of hosts in the replica set, you can specify one or more of the hosts in the replica set and instruct the C++ driver to perform automatic discovery to find the others. To instruct the driver to perform automatic discovery, perform one of the following actions:

Specify the name of the replica set as the value of the replicaSet parameter.
Specify false as the value of the directConnection parameter.
Specify more than one host in the replica set.

In the following example, the driver uses a sample connection URI to connect to the MongoDB replica set sampleRS, which is running on port 27017 of three different hosts, including host1:

#include <mongocxx/instance.hpp>
#include <mongocxx/client.hpp>
#include <mongocxx/uri.hpp>
int main()
{
    mongocxx::instance instance;
    mongocxx::uri uri("mongodb://host1:27017/?replicaSet=sampleRS");
    mongocxx::client client(uri);
}

Initialization

To initialize a replica set, you must connect directly to a single member. To do so, set the directConnection connection option to true in the connection string. The following code example shows how to set this connection option:

#include <mongocxx/instance.hpp>
#include <mongocxx/client.hpp>
#include <mongocxx/uri.hpp>
int main()
{
    mongocxx::instance instance;
    mongocxx::uri uri("mongodb://<hostname>:<port>/?directConnection=true");
    mongocxx::client client(uri);
}

API Documentation

To learn more about the types used on this page, see the following API documentation:

Back

Create a MongoDB Client

Specify Connection Options