Choose a Connection Target

On this page

Overview

Atlas
Local Deployments
Replica Sets
API Documentation

Overview

In this guide, you can learn how to use a connection string and a mongoc_client_t object to connect to different types of MongoDB deployments.

Atlas

To connect to a MongoDB deployment on Atlas, include the following elements in your connection string:

The URL of your Atlas cluster
Your MongoDB username
Your MongoDB password

Then, pass your connection string to the mongoc_client_new() function.

Tip

Follow the Atlas driver connection guide to retrieve your connection string.

The following code shows how to use the C driver to connect to an Atlas cluster. The code also uses the mongoc_server_api_new() function to specify a Stable API version.

bson_t *ping = BCON_NEW ("ping", BCON_INT32 (1));
bson_t reply = BSON_INITIALIZER;
bson_error_t error;
mongoc_client_t *client = NULL;
// Create a new client 
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);
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);

Tip

When you connect to Atlas, we recommend using the Stable API client option to avoid breaking changes when Atlas upgrades to a new version of MongoDB Server. To learn more about the Stable API, see the Stable API guide.

Local Deployments

To connect to a local MongoDB deployment, use localhost as the hostname. By default, the mongod process runs on port 27017, though you can customize this for your deployment.

The following code shows how to use the C driver to connect to a local MongoDB deployment:

bson_t *ping = BCON_NEW ("ping", BCON_INT32 (1));
bson_t reply = BSON_INITIALIZER;
bson_error_t error;
mongoc_client_t *client = NULL;
// Create a new client 
mongoc_uri_t *uri = mongoc_uri_new_with_error ("mongodb://localhost:27017", &error);  
if (!uri) {
  fprintf (stderr, "failed to parse URI, error: %s\n", error.message);
  goto cleanup;
}
client = mongoc_client_new_from_uri (uri);
if (!client) {
  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_client_destroy (client);
  mongoc_uri_destroy (uri);

Replica Sets

To connect to a replica set, specify the hostnames (or IP addresses) and port numbers of the replica-set members.

Instead of providing a full list of hosts in the replica set, you can specify one or more of the hosts in the replica set and instruct the C driver to perform automatic discovery to find the others. To instruct the driver to perform automatic discovery, perform one of the following actions:

Specify the name of the replica set as the value of the replicaSet parameter.
Specify false as the value of the directConnection parameter.
Specify more than one host in the replica set.

The following example uses a sample connection URI to connect to the MongoDB replica set myreplset, which is running on port 27017 of three different hosts:

bson_t *ping = BCON_NEW ("ping", BCON_INT32 (1));
bson_t reply = BSON_INITIALIZER;
bson_error_t error;
mongoc_client_t *client = NULL;
// Create a new client 
client = mongoc_client_new ("mongodb://host01:27017,host02:27017,host03:27017/?replicaSet=myreplset");
if (!client) {
  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_client_destroy (client);

Note

The mongoc_client_new() function is non-blocking. When you connect to a replica set, the constructor returns immediately while the client uses background threads to connect to the replica set.

If you construct a mongoc_client_t object and immediately print the string representation of its nodes attribute, the list might be empty while the client connects to the replica-set members.

API Documentation

For more information about the objects and functions mentioned in this guide, see the following API documentation:

Back

Stable API

Configure TLS