Docs Menu
Docs Home
/
Languages
/
C
/
C Driver
/
Connect to MongoDB

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

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