Connect to MongoDB

You are currently viewing an older version of the Java driver documentation.
For the most recent version of the reference documentation, see our MongoDB Java Driver documentation site.

Java Driver
Tutorials
Connect to MongoDB

Connect to MongoDB

Use MongoClients.create() (as of the 3.7 release), or MongoClient() for the legacy MongoClient API, to make a connection to a running MongoDB instance.

important

The following examples are not meant to provide an exhaustive list of ways to instantiate MongoClient. For a complete list of MongoClients factory methods, see the MongoClients API documentation, or for the legacy MongoClient API see the MongoClient() API documentation.

Note

The 3.5 release deprecated socket keep-alive settings, also socket keep-alive checks are now on by default. It is strongly recommended that system keep-alive settings should be configured with shorter timeouts.

See the ‘does TCP keep-alive time affect MongoDB deployments?’ documentation for more information.

Prerequisites

Running MongoDB deployments to which to connect. For example, to connect to a standalone, you must have a running standalone.
The MongoDB Driver. See Installation for instructions on how to install the MongoDB driver.
The following import statements:

import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoClient;
import com.mongodb.MongoClientSettings;
import com.mongodb.ConnectionString;
import com.mongodb.ServerAddress;
import com.mongodb.MongoCredential;
import com.mongodb.MongoClientSettings;

import java.util.Arrays;

or for the legacy MongoClient API:

import com.mongodb.MongoClient;
import com.mongodb.ServerAddress;
import com.mongodb.MongoCredential;
import com.mongodb.MongoClientSettings;

import java.util.Arrays;

`MongoClient` (since 3.7 release)

A MongoClient instance represents a pool of connections to the database; you will only need one instance of class MongoClient even with multiple threads.

important

Typically you only create one MongoClient instance for a given MongoDB deployment (e.g. standalone, replica set, or a sharded cluster) and use it across your application. However, if you do create multiple instances:

All resource usage limits (e.g. max connections, etc.) apply per MongoClient instance.
To dispose of an instance, call MongoClient.close() to clean up resources.

Connect to a Standalone MongoDB Instance

To connect to a standalone MongoDB instance:

You can create a MongoClient object without any parameters to connect to a MongoDB instance running on localhost on port 27017:

    MongoClient mongoClient = MongoClients.create()

You can explicitly specify the hostname to connect to a MongoDB instance running on the specified host on port 27017:

    MongoClient mongoClient = MongoClients.create("mongodb://host1");

You can explicitly specify the hostname and the port:

MongoClient mongoClient = MongoClients.create("mongodb://host1:27017");

Connect to a Replica Set

To connect to a replica set, you must specify one or more members to the MongoClients create method.

Note

MongoDB will auto-discover the primary and the secondaries.

You can specify the members using a ConnectionString:
- To specify at least two members of the replica set:

    MongoClient mongoClient = MongoClients.create("mongodb://host1:27017,host2:27017,host3:27017");

With at least one member of the replica set and the replicaSet option specifying the replica set name:

    MongoClient mongoClient = MongoClients.create("mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myReplicaSet");

You can specify a list of the all the replica set members’ ServerAddress:

    MongoClient mongoClient = MongoClients.create(
            MongoClientSettings.builder()
                    .applyToClusterSettings(builder ->
                            builder.hosts(Arrays.asList(
                                    new ServerAddress("host1", 27017),
                                    new ServerAddress("host2", 27017),
                                    new ServerAddress("host3", 27017))))
                    .build());

Connect to a Sharded Cluster

To connect to a sharded cluster, specify the mongos instance or instances to a MongoClients create method.

To connect to a single mongos instance:

You can specify the hostname and the port in a ConnectionString

    MongoClient mongoClient = MongoClients.create( "mongodb://localhost:27017" );

or leave the connection string out if the mongos is running on localhost:27017:

    MongoClient mongoClient = MongoClients.create();

To connect to multiple mongos instances:

You can specify the ConnectionString with their hostnames and ports:

MongoClient mongoClient = MongoClients.create("mongodb://host1:27017,host2:27017");

You can specify a list of the mongos instances’ ServerAddress:

    MongoClient mongoClient = MongoClients.create(
            MongoClientSettings.builder()
                    .applyToClusterSettings(builder ->
                            builder.hosts(Arrays.asList(
                                    new ServerAddress("host1", 27017),
                                    new ServerAddress("host2", 27017))))
                    .build());

Connection Options

You can specify the connection settings using either the ConnectionString or MongoClientSettings or both.

For example, you can specify TLS/SSL and authentication setting in the connection string:

    MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1&ssl=true");

You can also use MongoClientSettings to specify TLS/SSL and the MongoCredential for the authentication information:

    String user; // the user name
    String database; // the name of the database in which the user is defined
    char[] password; // the password as a character array
    // ...

    MongoCredential credential = MongoCredential.createCredential(user, database, password);

    MongoClientSettings settings = MongoClientSettings.builder()
            .credential(credential)
            .applyToSslSettings(builder -> builder.enabled(true))
            .applyToClusterSettings(builder -> 
                builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
            .build();

    MongoClient mongoClient = MongoClients.create(settings);

Finally, in some cases you may need to combine a connection string with programmatic configuration:

    ConnectionString connectionString = new ConnectionString("mongodb://host1:27107,host2:27017/?ssl=true");
    CommandListener myCommandListener = ...;
    MongoClientSettings settings = MongoClientSettings.builder()
            .addCommandListener(myCommandListener)
            .applyConnectionString(connectionString)
            .build();

    MongoClient mongoClient = MongoClients.create(settings);

`MongoClient` (legacy API)

A MongoClient instance represents a pool of connections to the database; you will only need one instance of class MongoClient even with multiple threads.

important

All resource usage limits (e.g. max connections, etc.) apply per MongoClient instance.
To dispose of an instance, call MongoClient.close() to clean up resources.

Connect to a Standalone MongoDB Instance

To connect to a standalone MongoDB instance:

You can instantiate a MongoClient object without any parameters to connect to a MongoDB instance running on localhost on port 27017:
```
MongoClient mongoClient = new MongoClient();
```
You can explicitly specify the hostname to connect to a MongoDB instance running on the specified host on port 27017:
```
MongoClient mongoClient = new MongoClient("mongodb://host1");
```

You can connect to the Unix domain socket (requires the jnr.unixsocket library):

MongoClient mongoClient = new MongoClient("mongodb://%2Ftmp%2Fmongodb-27107.sock");

You can explicitly specify the hostname and the port:

MongoClient mongoClient = new MongoClient("mongodb://host1:27017");

Connect to a Replica Set

To connect to a replica set, you must specify one or more members to the MongoClient constructor.

Note

MongoDB will auto-discover the primary and the secondaries.

You can specify the members using a connection string:

To specify at least two members of the replica set:

MongoClient mongoClient = new MongoClient("mongodb://host1:27017,host2:27017,host3:27017");

With at least one member of the replica set and the replicaSet option:

MongoClient mongoClient = new MongoClient("mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myReplicaSet");

You can specify a list of the all the replica set members’ ServerAddress:

MongoClient mongoClient = new MongoClient(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder -> 
                        builder.hosts(Arrays.asList(
                                new ServerAddress("host1", 27017),
                                new ServerAddress("host2", 27017),
                                new ServerAddress("host3", 27017))))
                .build());

Connect to a Sharded Cluster

To connect to a sharded cluster, specify the mongos instance or instances to the MongoClient constructor.

To connect to a single mongos instance:

You can specify the hostname and the port in a connection string (or you can omit the parameters if mongos is running on localhost and port 27017)
```
MongoClient mongoClient = new MongoClient("mongodb://localhost:27017");
```

To connect to multiple mongos instances:

You can specify the connection string with their hostnames and ports:

MongoClient mongoClient = new MongoClient("mongodb://host1:27017,host2:27017");

Connection Options

You can specify the connection settings using either the ConnectionString or MongoClientSettings or both.

For example, you can specify TLS/SSL and authentication setting in the ConnectionString:

MongoClient mongoClient = new MongoClient("mongodb://user1:pwd1@host1/?authSource=db1&ssl=true");

You can also use MongoClientSettings to specify TLS/SSL and the MongoCredential for the authentication information:

 String user; // the user name
 String database; // the name of the database in which the user is defined
 char[] password; // the password as a character array

 MongoCredential credential = MongoCredential.createCredential(user, database, password);

 MongoClientSettings settings = MongoClientSettings.builder()
                .applyToClusterSettings(builder -> builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .applyToSslSettings(builder -> builder.enabled(true))
                .credential(credential)
                .build(); 

 MongoClient mongoClient = new MongoClient(settings);

On this page