Create a MongoClient

On this page

Overview

Connection URI
Atlas Connection Example
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 mongoc_client_t structure, which creates the connection to and performs operations on the MongoDB deployment.

This guide shows you how to create a connection string and use a mongoc_client_t structure to connect to MongoDB.

Connection URI

A standard connection string includes the following components:

Component	Description
`mongodb+srv://`	Required. A prefix that identifies this as a string in the SRV connection format.
`username: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 the Authentication Mechanisms guide.
`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 `username: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.

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

Atlas Connection Example

To connect to a MongoDB deployment on Atlas, you must first create a client.

You can pass a connection URI as a string to the mongoc_client_new() function to connect to a MongoDB instance:

// Initialize the C Driver
mongoc_init ();
// Create a new client and connect to the server
mongoc_client_t *client = mongoc_client_new ("mongodb+srv://<db_username>:<db_password>@<hostname:port>/?<options>");
mongoc_database_t *database = mongoc_client_get_database (client, "admin");
bson_t *ping = BCON_NEW ("ping", BCON_INT32 (1));
bson_t reply = BSON_INITIALIZER;
bson_error_t error;
// Send a ping to confirm a successful connection
if (!mongoc_client_command_simple (client, "admin", ping, NULL, &reply, &error)) {
  fprintf(stderr, "error: %s\n", error.message);
  goto cleanup;
}
printf ("Pinged your deployment. You successfully connected to MongoDB!\n");
cleanup:
  bson_destroy (&reply);
  bson_destroy (ping);
  mongoc_database_destroy (database);
  mongoc_client_destroy (client);
  // Cleanup the C Driver
  mongoc_cleanup ();

You can set the Stable API version client option to avoid breaking changes when you upgrade to a new server version.

Tip

To learn more about the Stable API feature, see the Stable API guide.

The following code shows how you can specify the connection string and the Stable API client option when connecting to a MongoDB deployment on Atlas and verify that the connection is successful:

// Intialize the MongoDB C Driver
mongoc_init();
// Create a new client and connect to the server
mongoc_client_t *client = mongoc_client_new ("mongodb+srv://<db_username>:<db_password>@<hostname:port>/?<options>");
// Set the version of the Stable API on the client
mongoc_server_api_t *api = mongoc_server_api_new(MONGOC_SERVER_API_V1);
bson_t *ping = BCON_NEW ("ping", BCON_INT32 (1));
bson_t reply = BSON_INITIALIZER;
bson_error_t error;
if (!mongoc_client_set_server_api (client, api, &error)) {
  fprintf(stderr, "error: %s\n", error.message);
  goto cleanup;
}
// Send a ping to confirm a successful connection
if (!mongoc_client_command_simple (client, "admin", ping, NULL, &reply, &error)) {
  fprintf(stderr, "error: %s\n", error.message);
  goto cleanup;
}
printf ("Pinged your deployment. You successfully connected to MongoDB!\n");
cleanup:
  bson_destroy (&reply);
  bson_destroy (ping);
  mongoc_server_api_destroy (api);
  mongoc_client_destroy (client);
  // Cleanup the C Driver
  mongoc_cleanup ();

API Documentation

For more information about the mongoc_client_t structure, see the API documentation.

Back

Connect to MongoDB

Stable API