Create a MongoDB Client

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

Create a MongoDB Client

Overview

To connect to a MongoDB deployment, you need two things:

  • A connection URI, also known as a connection string, which tells the C++ driver which MongoDB deployment to connect to.

  • A mongocxx::client object, which creates the connection to the MongoDB deployment and lets you perform operations on it.

You can also use either of these components to customize the way the C++ driver behaves while connected to MongoDB.

This guide shows you how to create a connection string and use a mongocxx::client object to connect to MongoDB.

Note: mongocxx::instance

The code examples on this page assume that you've already created a mongocxx::instance object elsewhere in your application.

To learn more about creating an instance, see [Create a Driver Instance.](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/connect/instance.md#std-label-cpp-instance

Connection URI

A standard connection string includes the following components:

Component Description
mongodb:// Required. A prefix that identifies this as a string in the standard connection format.
db_username:db_password Optional. Authentication credentials. If you include these, the client authenticates the user against the database specified in authSource. For more information about the authSource connection option, see [Authentication Options.](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/connect/connection-options.md#std-label-cpp-auth
host[:port] Required. The host and optional port number where MongoDB is running. If you don't include the port number, the driver uses the default port, 27017.
/defaultauthdb Optional. The authentication database to use if the connection string includes db_username:db_password@ authentication credentials but not the authSource option. If you don't include this component, the client authenticates the user against the admin database.
?<options> Optional. A query string that specifies connection-specific options as <name>=<value> pairs. See [Specify Connection Options](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/connect/connection-options.md#std-label-cpp-connection-options for a full description of these options.

For more information about creating a connection string, see Connection Strings in the MongoDB Server documentation.

Create a mongocxx::client

To create a connection to MongoDB, construct an instance of the mongocxx::uri class, passing the connection URI as a string to the constructor. Then, pass the instance of the mongocxx::uri class to the mongocxx::client constructor.

In the following example, the driver uses a sample connection URI to connect to a MongoDB deployment on port 27017 of localhost:

#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);
}

Tip: Reuse Your Client

Because each mongocxx::client object represents a pool of connections to the database, most applications require only a single instance of mongocxx::client, even across multiple requests.

API Documentation

To learn more about creating a mongocxx::client object in C++ driver, see the following API documentation: