Create a MongoClient

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

Create a MongoClient

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](https://www.mongodb.com/docs/languages/c/c-driver/current/security/authentication.md#std-label-c-auth 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](https://www.mongodb.com/docs/languages/c/c-driver/current/connect/connection-options/stable-api.md#std-label-c-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.