Create a MongoDB Client

On this page

Overview

Connection URI
Create a mongocxx::client
API Documentation

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.

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 Mechanisms.
`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 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:

mongocxx::client

Back

Create a Driver Instance

Choose a Connection Target