Criar um MongoClient

Neste guia, você aprenderá como se conectar a uma implantação MongoDB Atlas, a uma instância do MongoDB ou a um conjunto de réplicas usando o Java Driver.

Você pode ver um exemplo de código para se conectar a um cluster do Atlas ou continuar lendo para saber mais sobre a classe MongoClient e os URIs de conexão.

Cliente Mongo

Você pode se conectar e se comunicar com MongoDB usando a MongoClient classe . Para criar um objeto MongoClientSettings, use o MongoClientSettings.builder() método e os métodos de cadeia para especificar suas configurações. Após encadeá-los, use o build() método para criar o MongoClientSettings objeto.

Para saber mais sobre as diferentes configurações que você pode usar para controlar o comportamento do seu MongoClient, consulte o guia Especificar configurações do MongoClient.

Exemplo

Este exemplo demonstra a especificação de um ConnectionString:

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
    .applyConnectionString(new ConnectionString("<your connection string>"))
    .build());

Observação

Ordem de corrente

Algumas opções no mapa de configurações para uma opção de cadeia de conexão. Se você especificar as mesmas opções em suas configurações e na cadeia de conexão, a ordem em que você as encadear determinará qual opção o driver usará. O driver usa a última configuração lida.

Por exemplo, esse trecho contém configurações com os seguintes horários para o driver se conectar a um soquete disponível:

A cadeia de conexão especifica dentro 2 SECONDS
As configurações de soquete especificam dentro de 5 SECONDS

MongoClient mongoClient = MongoClients.create(
   MongoClientSettings.builder().applyConnectionString(new ConnectionString("mongodb+srv://<db_username>:<db_password>@<hostname>:<port>/<auth db>?connectTimeoutMS=2000"))
      .applyToSocketSettings(builder ->
      builder.connectTimeout(5L, SECONDS))
      .build());

Como o driver lê as opções de configurações de soquete por último, o driver espera se conectar a um soquete disponível dentro de 5 SECONDS antes de atingir o tempo limite.

Importante

Reutilize seu cliente

Como cada MongoClient representa um repositório seguro de conexões com o banco de dados, a maioria dos aplicativos requer apenas uma única instância de um MongoClient, mesmo em vários threads. Todos os limites de uso de recursos, como conexões máximas, se aplicam a instâncias individuais do MongoClient.

Dica

Sempre chame MongoClient.close() para limpar recursos quando uma instância não for mais necessária.

URI de conexão

O URI de conexão fornece um conjunto de instruções que o driver utiliza para se conectar a uma implantação MongoDB. Ele instrui o driver sobre como deve se conectar ao MongoDB e como deve se comportar enquanto conectado. A figura a seguir explica cada parte de um URI de conexão de amostra:

Um exemplo de uma connection string que demonstra o protocolo, as credenciais, o nome do host ou o IP, a porta e as opções de conexão

Neste exemplo, você se conecta a um sistema do Atlas MongoDB que tem um registro DNS SRV. Para obter mais informações, consulte a seção Descoberta de serviços DNS deste guia.

Observação

Se a sua implantação estiver no MongoDB Atlas, consulte o guia de conexão do driver do Atlas e selecione Java no menu suspenso de idioma para recuperar sua string de conexão.

Se você estiver se conectando a uma instância ou conjunto de réplicas que não tenha um endereço SRV DNS, deverá usar mongodb para o protocolo, que especifica o Formato Padrão de Connection String.

Após o protocolo, a connection string contém suas credenciais se você estiver usando um mecanismo de autenticação baseado em senha. Substitua o valor de user pelo seu nome de usuário e pass pela sua senha. Se o mecanismo de autenticação não exigir credenciais, omita esta parte do URI de conexão.

A próxima parte do URI de conexão especifica o nome do host ou endereço IP, seguido pela porta da sua instância do MongoDB. No exemplo, sample.host representa o nome do host e 27017 é o número da porta. Substitua estes valores para consultar a sua instância MongoDB.

A última parte do URI de conexão contém opções de conexão como parâmetros. No exemplo, você define duas opções de conexão: maxPoolSize=20 e w=majority. Para obter mais informações sobre as opções de conexão, vá para a seção Especificar opções de conexão deste guia.

Descoberta de serviço DNS

Para usar a descoberta de serviços DNS para procurar o registro DNS SRV do serviço ao qual você está se conectando, especifique o formato de conexão SRV em sua string de conexão. Se você especificar este formato, o driver Java reanalisa automaticamente em busca de novos hosts. Seu sistema pode adicionar hosts à topologia sem exigir alterações na configuração do cliente .

O código a seguir mostra uma string de conexão que usa o formato de conexão SRV:

String uri = "mongodb+srv://<hostname>/";

Para saber mais sobre o formato de conexão SRV, consulte a entrada Formato de conexão SRV no manual do MongoDB Server.

Exemplo de conexão do Atlas

Para se conectar a uma implementação do MongoDB no Atlas, crie um cliente. Você pode criar um cliente que use sua conexão e outras opções do cliente passando um objeto MongoClientSettings para o método MongoClients.create() .

Para instanciar um objeto MongoClientSettings, use o método builder para especificar sua string de conexão e quaisquer outras opções de cliente e, em seguida, chame o método build(). Encadeie o método applyConnectionString() ao construtor para especificar seu URI de conexão.

Você pode definir a opção de cliente da versão Stable API para evitar alterações significativas ao atualizar para uma nova versão do servidor MongoDB. Para saber mais sobre o recurso de API estável, consulte a página de API estável.

O código a seguir mostra como você pode especificar a cadeia de conexão e a opção de cliente Stable API ao se conectar a uma implementação do MongoDB no Atlas e verificar se a conexão foi bem-sucedida:

package fundamentals;
import com.mongodb.*;
import org.bson.BsonDocument;
import org.bson.BsonInt64;
import org.bson.Document;
import org.bson.conversions.Bson;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoDatabase;
public class MongoClientConnectionExample {
    public static void main(String[] args) {
        // Replace the placeholder with your Atlas connection string
        String uri = "<connection string>";
        // Construct a ServerApi instance using the ServerApi.builder() method
        ServerApi serverApi = ServerApi.builder()
                .version(ServerApiVersion.V1)
                .build();
        MongoClientSettings settings = MongoClientSettings.builder()
                .applyConnectionString(new ConnectionString(uri))
                .serverApi(serverApi)
                .build();
        // Create a new client and connect to the server
        try (MongoClient mongoClient = MongoClients.create(settings)) {
            MongoDatabase database = mongoClient.getDatabase("admin");
            try {
                // Send a ping to confirm a successful connection
                Bson command = new BsonDocument("ping", new BsonInt64(1));
                Document commandResult = database.runCommand(command);
                System.out.println("Pinged your deployment. You successfully connected to MongoDB!");
            } catch (MongoException me) {
                System.err.println(me);
            }
        }
    }
}

Outras maneiras de se conectar ao MongoDB

Se estiver se conectando a uma única implementação ou conjunto de réplicas do MongoDB que não esteja hospedado no Atlas, consulte as seções a seguir para saber como se conectar.

Conecte-se a uma implementação do MongoDB em sua máquina local

Se você precisar executar uma implementação do MongoDB em seu computador local para fins de desenvolvimento, em vez de usar um cluster do Atlas, será necessário realizar o seguinte:

Baixe a versão Comunidade ou Enterprise do MongoDB Server.
Instale e configure o servidor MongoDB.
Inicie a implementação.

Importante

Sempre proteja sua implantação do MongoDB contra ataques maliciosos. Consulte nossa Lista de verificação de segurança para obter uma lista de recomendações de segurança.

Depois de iniciar com êxito a implementação do MongoDB, especifique sua connection string no código de conexão do driver.

Se a implementação do MongoDB estiver sendo executada localmente, você poderá usar a connection string "mongodb://localhost:<port>", em que <port> é o número da porta que você configurou no servidor para escutar as conexões de entrada.

Se você precisar especificar um nome de host ou endereço IP diferente, consulte a entrada do Manual do servidor sobre strings de conexão.

Para testar se você pode se conectar à sua implantação, substitua a string de conexão no exemplo de código Connect to MongoDB Atlas e execute-a.

Conectar a um conjunto de réplicas

Um sistema do conjunto de réplicas MongoDB é um grupo de instâncias conectadas que armazenam o mesmo conjunto de dados. Esta configuração de instâncias fornece redundância de dados e alta disponibilidade de dados.

Para se conectar a um sistema de conjunto de réplicas, especifique o nome de host (ou endereço IP) e o número de porta dos membros do conjunto de réplicas.

Se não for possível fornecer uma lista completa de hosts no conjunto de réplicas, você poderá especificar um único ou um subconjunto de hosts na réplica e instruir o driver a executar a descoberta automática de uma das seguintes maneiras:

Especifique o nome do conjunto de réplica como o valor do parâmetro replicaSet
Especifique false como o valor do parâmetro directConnection
Especifique mais de um host no conjunto de réplicas

Dica

Embora você possa especificar um subconjunto dos hosts em um conjunto de réplicas, inclua todos os hosts no conjunto de réplicas para garantir que o driver possa estabelecer a conexão se um dos hosts estiver inacessível.

Os exemplos seguintes mostram como especificar múltiplos hosts para uma instância do MongoClient utilizando a classe ConnectionString ou MongoClientSettings. Selecione a aba que corresponde à sua turma preferida.

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

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

Observação

Conjunto de réplicas no Docker

Quando um conjunto de réplicas é executado no Docker, ele pode expor apenas um endpoint MongoDB . Nesse caso, o conjunto de réplicas não é detectável. Especificar directConnection=false em seu URI de conexão ou deixar essa opção sem definir pode impedir que seu aplicação se conecte a ele.

Em um ambiente de teste ou desenvolvimento, é possível conectar-se ao conjunto de réplicas especificando directConnection=true. Em um ambiente de produção, recomendamos configurar o cluster para que cada instância do MongoDB seja acessível fora da rede virtual do Docker.

Perguntas frequentes

Esta seção responde a perguntas que podem surgir ao se conectar ao MongoDB.

Por que existem dois tipos de `MongoClient` no driver Java?

Existem dois tipos de MongoClient porque queríamos uma API mais limpa para novos usuários que não tivesse a confusão de incluir vários CRUD Frequently AsAPIs. Queremos garantir que a nova API CRUD esteja disponível em uma estrutura de pacote Java que funcione bem com o suporte a módulos Java introduzido no Java 9.

Que tipo de `MongoClient` devo usar?

Novos aplicativos geralmente usam a interface com.mongodb.client.MongoClient, que suporta as seguintes funcionalidades:

Configuração com MongoClientSettings e ConnectionString. Você pode criar instâncias desta interface utilizando métodos de fábrica definidos na classe com.mongodb.client.MongoClients.
Acesse a API CRUD usando MongoDatabase e, a partir de lá, MongoCollection.

Use a classe com.mongodb.MongoClient se você precisar de suporte para a API legado , que suporta as seguintes funcionalidades:

Configuração usando MongoClientOptions e MongoClientURI.
Acesse a API CRUD usando DB e, a partir de lá, DBCollection. Você pode acessar essa API usando o método getDB().

Para aplicativos que exigem uma combinação de APIs novas e legado , o com.mongodb.MongoClient também suporta as seguintes funcionalidades:

Configuração usando MongoClientSettings e ConnectionString, a única diferença é que você cria instâncias por meio de construtores em vez de uma classe de fábrica.
Acesse a API CRUD usando MongoDatabase e, a partir de lá, MongoCollection. Você pode acessar essa API usando o método getDatabase().

Como evito o erro "java.lang.NoClassDefFoundError: com/mongodb/MongoClient"?

Você pode encontrar uma exceção java.lang.NoClassDefFoundError quando seu ambiente de execução Java não consegue localizar um arquivo de classe no tempo de execução. Ao tentar executar o código do aplicativo que usa o MongoDB Java Driver, você deve incluir os arquivos JAR do driver apropriados no classpath.

Se você receber esse erro depois de adicionar os arquivos JAR do driver Java ao seu classpath, verifique os seguintes itens no seu ambiente:

Os arquivos JAR existem nos locais especificados pelo classpath.
A sintaxe do classpath está correta.
Se você definir o classpath em uma variável de ambiente, o ambiente de tempo de execução Java utilizará esta variável.
Se você usar um gerenciador de dependências, ele não relatará nenhum conflito não resolvido.

Dica

Esse erro contém o pacote e o nome da classe, o que pode ajudá-lo a identificar qual driver JAR pode estar faltando no seu classpath. Para localizar o JAR do driver a que o erro se refere, verifique cada uma das entradas na documentação da API.

Como evito o erro "com.mongodb.MongoSecurityException"?

Seu aplicativo poderá lançar essa exceção se você especificar credenciais inválidas ou formatadas incorretamente ao se conectar a um sistema do MongoDB.

Se você receber esse erro ao tentar se conectar a um sistema do MongoDB, verifique os seguintes itens no seu código:

O URI de conexão corresponde à implantação correta do MongoDB . Para saber mais sobre como configurar seu URI de conexão, consulte URI de conexão.
As credenciais do mecanismo de autenticação que você especificou estão corretas. Para saber como especificar suas credenciais, consulte o guia Mecanismos de autenticação.
O nome do banco de dados de autenticação que você especificou está correto. Para saber como configurar os usuários e as funções de seu MongoDB deployment, consulte Gerenciar usuários e funções na documentação do Servidor MongoDB.

Como evito o erro "IllegalStateException: o estado deve ser: aberto"?

Você poderá encontrar essa exceção se chamar uma operação em uma instância MongoClient que fechou suas conexões com o MongoDB. Depois que o método close() for chamado em MongoClient, qualquer operação adicional chamada nessa instância gerará essa exceção.

Para evitar essa exceção, não chame operações na instância MongoClient após qualquer código que chame close() nela.

Dica

O código que fecha a instância do MongoClient pode ser difícil de localizar em determinados casos. Para localizar possíveis fontes dessa exceção, pesquisar os seguintes casos:

Chamadas para close() em uma instância do MongoClient
A operação chama uma instância MongoClient que está fora do escopo da declaração de tentativa com recursos na qual o MongoClient é declarado

Se sua aplicação usar uma estrutura para managed o MongoClient , como oSpring Boot, verifique a documentação da estrutura para localizar as melhores práticas para managed o comportamento da conexão.

Para saber mais sobre como acessar o MongoDB a partir do Spring Boot, consulte Spring Boot e MongoDB.

Voltar

Conecte

Especificar opções de conexão

Cliente Mongo

Exemplo

Observação

Ordem de corrente

Importante

Reutilize seu cliente

Dica

URI de conexão

Observação

Descoberta de serviço DNS

Exemplo de conexão do Atlas

Outras maneiras de se conectar ao MongoDB

Conecte-se a uma implementação do MongoDB em sua máquina local

Importante

Conectar a um conjunto de réplicas

Dica

Observação

Conjunto de réplicas no Docker

Perguntas frequentes

Por que existem dois tipos de MongoClient no driver Java?

Que tipo de MongoClient devo usar?

Como evito o erro "java.lang.NoClassDefFoundError: com/mongodb/MongoClient"?

Dica

Como evito o erro "com.mongodb.MongoSecurityException"?

Como evito o erro "IllegalStateException: o estado deve ser: aberto"?

Dica

Por que existem dois tipos de `MongoClient` no driver Java?

Que tipo de `MongoClient` devo usar?