Choose a Connection Target
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.
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:
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 thedirectConnection
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
:
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:
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: