Connect to MongoDB

To make a connection to a running MongoDB instance, use MongoClients.create to create a new MongoClient instance.

A MongoClient instance actually represents a pool of connections to the database; you will only need one instance of class MongoClient even with multiple concurrently executing asynchronous operations.

Prerequisites

• Running MongoDB deployments to which to connect. For example, to connect to a standalone, you must have a running standalone.

• The MongoDB Asynchronous Driver. See Installation for instructions on how to install the MongoDB async driver.

• The following import statements:

  import com.mongodb.ConnectionString;
  import com.mongodb.ServerAddress;
  import com.mongodb.async.client.*;
  import com.mongodb.connection.ClusterSettings;
  import java.util.Arrays;
  import static java.util.Arrays.asList;
  

Connect to a Standalone MongoDB Instance

To connect to a standalone MongoDB instance:

• You can call MongoClients.create() without any parameters to connect to a MongoDB instance running on localhost on port 27017:

  MongoClient mongoClient = MongoClients.create();
  

• You can call MongoClients.create() with a string that specifies the connection string:

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

  The connection string mostly follows RFC 3986, with the exception of the domain name. For MongoDB, it is possible to list multiple domain names separated by a comma. For more information on the connection string, see connection string.

• You can call MongoClients.create() with a ConnectionString object:

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

• You can call MongoClients.create() with a MongoClientSettings object. To specify the host information, use the ClusterSettings.

  ClusterSettings clusterSettings = ClusterSettings.builder()
                                    .hosts(asList(new ServerAddress("localhost")))
                                    .build();
  MongoClientSettings settings = MongoClientSettings.builder()
                                    .clusterSettings(clusterSettings).build();
  MongoClient mongoClient = MongoClients.create(settings);
  

Connect to a Replica Set

To connect to a replica set, specify at least one or more members of the replica set in the connection string or MongoClientSettings object and pass to MongoClients.create().

• You can call MongoClients.create() with a connection string that specifies the members of the replica set:

  • Specify at least two members of the replica set if you are not specifying the replica set name

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

  • Specify at least one member of the replica set and the replica set name

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

• You can call MongoClients.create() with a ConnectionString object that specifies the members of the replica set:

  • Specify at least two members of the replica set if you are not specifying the replica set name

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

  • Specify at least one member of the replica set and the replica set name:

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

• You can call MongoClients.create() with a MongoClientSettings object. To specify the host information of the replica set members, use ClusterSettings.

    ClusterSettings clusterSettings = ClusterSettings.builder()
                                        .hosts(asList(
                                            new ServerAddress("host1", 27017),
                                            new ServerAddress("host2", 27017),
                                            new ServerAddress("host3", 27017)))
                                        .build();
  
    MongoClientSettings settings = MongoClientSettings.builder()
                                        .clusterSettings(clusterSettings).build();
  
    MongoClient mongoClient = MongoClients.create(settings);
  

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 call MongoClients.create() without any parameters to connect to a :program:mongos running on localhost on port 27017:

  MongoClient mongoClient = MongoClients.create();
  

• You can call MongoClients.create() with a string that specifies the host information of the mongos instance in the connection URI:

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

• You can call MongoClients.create() with a ConnectionString object that specifies the host information of the mongos instance:

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

• You can call MongoClients.create() with a MongoClientSettings object. To specify the host information of the mongos instance, use ClusterSettings:

  ClusterSettings clusterSettings = ClusterSettings.builder()
                                      .hosts(asList(new ServerAddress("localhost")))
                                      .build();
  MongoClientSettings settings = MongoClientSettings.builder()
                                      .clusterSettings(clusterSettings)
                                      .build();
  MongoClient mongoClient = MongoClients.create(settings);
  

To connect to multiple mongos instances, specify the host and port of the mongos instances:

• You can call MongoClients.create() with a string that specifies the host and port information of the mongos instances in the connection URI:

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

• You can call MongoClients.create() with a ConnectionString object that specifies the host and port information of the mongos instances:

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

• You can call MongoClients.create() with a MongoClientSettings object. To specify the host information of the mongos instances, use ClusterSettings:

  ClusterSettings clusterSettings = ClusterSettings.builder()
                                        .hosts(asList(
                                            new ServerAddress("host1", 27017),
                                            new ServerAddress("host2", 27017)))
                                        .build();
  
  
  MongoClientSettings settings = MongoClientSettings.builder()
                                        .clusterSettings(clusterSettings).build();
  MongoClient mongoClient = MongoClients.create(settings);
  

Connection Options

You can specify the connection settings using either the connection string (or ConnectionString object) or the MongoClientSettings or both.

Netty Configuration

In its default configuration, the async driver is supported on Java 7+ when TLS/SSL is disabled, and on Java 8+ when TLS/SSL is enabled.
Otherwise, applications must use Netty.

To configure the driver to use Netty,

• Include the streamType option set to netty in the connection string

  MongoClient client = MongoClients.create("mongodb://localhost/?streamType=netty");
  

• Configure MongoClientSettings with the StreamFactory set to use Netty:

  MongoClient client = MongoClients.create(MongoClientSettings.builder()
          .applyConnectionString(new ConnectionString("mongodb://localhost"))
          .streamFactoryFactory(NettyStreamFactoryFactory.builder().build())
          .build());