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