Create a MongoClient

Overview

In this guide, you can learn how to connect to a MongoDB Atlas deployment, a MongoDB instance, or a replica set using the Go driver.

To connect to a MongoDB deployment, you need the following two things:

Connection URI, also known as a connection string, which tells the Go driver which MongoDB deployment to connect to.
MongoClient object, which creates the connection to and performs operations on the MongoDB deployment.

You can use options.Client() to customize the way the Go driver behaves while connected to MongoDB.

Connection URI

A standard connection string includes the following components:

Component	Description
`mongodb://`	Required. A prefix that identifies this as a string in the standard 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 Connection Troubleshooting in the Connection Troubleshooting 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. When you call `client.db()` with no argument, this is the database that is used. 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. See Specify Connection Options for a full description of these options.

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

Create a Client to Connect to MongoDB Atlas

To connect to MongoDB, you must create a client. A client manages your connections and runs database commands.

You can create a client that uses your connection string and other client options by passing a ClientOptions object to the Connect() method.

To specify your connection URI, pass it to the ApplyURI() method, which returns a new ClientOptions instance. To set any other options, call the relevant helper method from the options package.

Tip

Reuse Your Client

We recommend that you reuse your client across sessions and operations. You can use the same Client instance to perform multiple tasks, instead of creating a new one each time. The Client type is safe for concurrent use by multiple goroutines. To learn more about how connection pools work in the driver, see the Connection Pools guide.

To learn more about connection options, see the Connection Options section. To learn more about creating a client, see the API documentation for Client and Connect().

You can set the Stable API version as an option to avoid breaking changes when you upgrade to a new server version. To learn more about the Stable API feature, see the Stable API page.

Example

The following code shows how you can create a client that uses an Atlas connection string and the Stable API version, connects to MongoDB, and verifies that the connection is successful:

// Connects to MongoDB and sets a Stable API version
package main
import (
	"context"
	"fmt"
	"log"
	"os"
	"go.mongodb.org/mongo-driver/v2/bson"
	"go.mongodb.org/mongo-driver/v2/mongo"
	"go.mongodb.org/mongo-driver/v2/mongo/options"
)
func main() {
	var uri string
	if uri = os.Getenv("MONGODB_URI"); uri == "" {
		log.Fatal("You must set your 'MONGODB_URI' environment variable. See\n\t https://docs.mongodb.com/drivers/go/current/usage-examples/")
	}
	// Uses the SetServerAPIOptions() method to set the Stable API version to 1
	serverAPI := options.ServerAPI(options.ServerAPIVersion1)
	// Defines the options for the MongoDB client
	opts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPI)
	// Creates a new client and connects to the server
	client, err := mongo.Connect(opts)
	if err != nil {
		panic(err)
	}
	defer func() {
		if err = client.Disconnect(context.TODO()); err != nil {
			panic(err)
		}
	}()
	// Sends a ping to confirm a successful connection
	var result bson.M
	if err := client.Database("admin").RunCommand(context.TODO(), bson.D{{"ping", 1}}).Decode(&result); err != nil {
		panic(err)
	}
	fmt.Println("Pinged your deployment. You successfully connected to MongoDB!")
}

Tip

Follow the Quick Start guide to learn how to retrieve your Atlas connection string.

Note

To learn about connecting to Atlas Serverless, see the Serverless Instance Limitations page to identify the minimum driver version required.

Other Ways to Connect to MongoDB

If you are connecting to a single MongoDB server instance or replica set that is not hosted on Atlas, see the following sections to learn how to connect.

Connect to a MongoDB Server on Your Local Machine

If you must run a MongoDB server on your local machine for development purposes, complete the following steps:

Download the Community or Enterprise version of MongoDB Server.
Install and configure MongoDB Server.
Start the server.

Important

Always secure your MongoDB server from malicious attacks. See the Security Checklist in the Server manual for a list of security recommendations.

After you successfully start your MongoDB server, specify your connection string in your driver connection code.

If your MongoDB Server is running locally, you can use the connection string "mongodb://localhost:<port>" where <port> is the port number you configured your server to listen for incoming connections.

For more information on how to specify a different hostname or IP address, see Connection Strings in the Server manual.

To test whether you can connect to your server, replace the connection string with your localhost connection string in the preceding code example <go-connection-example-code>.

Connect to a Replica Set

A MongoDB replica set deployment is a group of connected instances that store the same set of data. This configuration provides data redundancy and high data availability.

To connect to a replica set deployment, specify the hostname and port numbers of each instance, separated by commas, and the replica set name as the value of the replicaSet parameter in the connection string. In the following example, the hostnames are host1, host2, and host3, and the port numbers are all 27017. The replica set name is myRS.

mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRS

When connecting to a replica set, the driver takes the following actions by default:

Discovers all replica set members when given the address of any one member.
Dispatches operations to the appropriate member, such as instructions to write against the primary.

Tip

You can specify just one host to connect to a replica set. However, to ensure connectivity when the specified host is unavailable, you must provide the full list of hosts.

To learn more about replication in MongoDB, see the Replication section of Server manual.

Direct Connection

To force operations on the host designated in the connection URI, specify the directConnection option. Direct connections exhibit the following behavior:

They don't support SRV strings.
They fail on writes when the specified host is not the primary.
They require you to specify a secondary read preference when the specified host isn't the primary node.

Note

Replica Set in Docker

When a replica set runs in Docker, it might expose only one MongoDB endpoint. In this case, the replica set is not discoverable. Specifying directConnection=false in your connection URI, or leaving this option unset, can prevent your application from connecting to it.

In a test or development environment, you can connect to the replica set by specifying directConnection=true. In a production environment, we recommend configuring the cluster to make each MongoDB instance accessible outside of the Docker virtual network.

Back

Connect

Choose a Connection Target