Choose a Connection Target

Overview

In this guide, you can learn how to use a connection string and a Mongo::Client 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 Mongo::Client constructor.

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 feature, see the Stable API guide.

The following code shows how to use the Ruby driver to connect to an Atlas cluster. The code also uses the server_api field to specify a Stable API version.

require 'mongo'
# Replace the placeholders with your credentials
uri = "<connection string>"
# Sets the server_api field of the options object to Stable API version 1
options = { server_api: { version: '1' } }
# Creates a new client and connect to the server
client = Mongo::Client.new(uri, options)
# Sends a ping to confirm a successful connection
begin
  admin_client = client.use('admin')
  result = admin_client.database.command(ping: 1).documents.first
  puts "Pinged your deployment. You successfully connected to MongoDB!"
rescue Mongo::Error::OperationFailure => ex
  puts ex
ensure
  client.close
end

Local Deployments

To connect to a local standalone MongoDB deployment, specify the host of the server. Optionally, specify the port of the server and the database to connect to. If no port is specified, the default port is 27017. If no database name is specified, the client will use the admin database:

Mongo::Client.new([ 'host1:27017' ], database: 'mydb')

You can also specify the host, port, and database to connect to using a connection string:

Mongo::Client.new("mongodb://host1:27017/mydb")

You can also specify your host as localhost. The following code example connects to localhost on the default port, 27017:

client = Mongo::Client.new(["localhost"])

Replica Sets

To connect to a replica set, it is recommended to specify all nodes that are part of the replica set. In the event that one or more nodes becomes unavailable, specifying all nodes allows the driver to still connect to the replica set, as long as one node is available.

However, it is sufficient to pass the address of any one node in the replica set to the driver. The node does not have to be the primary, and it may be a hidden node. The driver will then automatically discover the remaining nodes.

The following example shows how to specify three members of the replica set:

Mongo::Client.new([ 'host1:27017', 'host2:27018', `host3:21019` ], database: 'mydb')

The following example shows how to connect to the replica set using a connection string:

Mongo::Client.new("mongodb://host1:27017,host2:27018,host3:27019/mydb")

The following example shows how to verify the replica set name upon connection by using the replica_set option or the replicaSet connection string option:

Mongo::Client.new([ 'host1:27017', 'host2:27018', 'host3:27019' ],
  database: 'mydb', replica_set: 'myapp')
# Or by using a connection string:
Mongo::Client.new("mongodb://host1:27017,host2:27018,host3:27019/mydb?replicaSet=myapp")

API Documentation

To learn more about creating a Mongo::Client object with the Ruby driver, see the API documentation for Mongo::Client .