Guia de conexão

Nesta página

Visão geral

URI de conexão
Partes de um URI de conexão
Cliente MongoDB
Métodos de criação de cliente
Exemplo de conexão
Outras maneiras de se conectar ao MongoDB
Conecte-se a um servidor MongoDB em sua máquina local
Conectar a um conjunto de réplicas

Visão geral

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

Este guia inclui as seguintes seções:

O URI de conexão descreve os URIs de conexão e suas partes constituintes
Cliente MongoDB descreve o tipo Client e maneiras de criar um cliente a partir de uma string de conexão
Exemplo de conexão fornece exemplos que mostram como se conectar ao MongoDB usando uma cadeia de conexão do Atlas
Outras Maneiras de Conectar ao MongoDB descreve maneiras de se conectar a implementações do MongoDB que não estão hospedadas no Atlas

URI de conexão

Um URI de conexão, também conhecido como cadeia de conexão, informa ao driver como se conectar ao MongoDB e como se comportar enquanto estiver conectado.

Partes de um URI de conexão

O exemplo a seguir explica cada parte de um exemplo de URI de conexão:

Neste exemplo, usamos mongodb para o protocolo, que especifica o formato de cadeia de conexão padrão. Você também pode usar o formato de conexão da seed list de DNS caso deseje mais flexibilidade em sua implantação e a capacidade de alterar os servidores em rotação sem reconfigurar os clientes.

Se você estiver usando autenticação com senha, a parte da cadeia de conexão logo após o protocolo conterá seu nome de usuário e senha. Substitua o espaço reservado para user pelo seu nome de usuário e pass pela sua senha. Se você estiver usando um mecanismo de autenticação que não requer um nome de usuário e senha, omita esta parte do URI de conexão.

A parte da cadeia de conexão após as credenciais especifica o nome do host ou o endereço IP e a porta da sua instância do MongoDB. No exemplo anterior, usamos sample.host como nome de host e 27017 como porta. Substitua esses valores para apontar para a sua instância MongoDB.

A última parte da cadeia de conexão especifica as opções de conexão e autenticação. No exemplo, definimos duas opções de conexão: maxPoolSize=20 e w=majority.

Dica

Opções de conexão

Para saber mais sobre como configurar as opções de conexão, consulte o guia sobre Opções de conexão.

Cliente MongoDB

Para se conectar ao MongoDB, você deve criar uma instância Client. Um cliente gerencia conexões e executa comandos de banco de dados.

Dica

Reutilize seu cliente

Você pode melhorar o desempenho reutilizando seu cliente entre sessões e operações. Você pode utilizar a mesma instância do Client para executar múltiplas tarefas, em vez de criar outra a cada vez. O tipo de Client é seguro para uso concorrente por vários threads ou tarefas assíncronas.

Métodos de criação de cliente

Você pode criar um cliente que use sua cadeia de conexão e outras opções do cliente passando um objeto ClientOptions para o método with_options().

Para especificar o URI da conexão, passe-o para o método parse() do ClientOptions. Para definir quaisquer outras opções, defina o campo relevante da estrutura ClientOptions.

Se você não especificar nenhuma opção de cliente, crie um cliente passando sua cadeia de conexão para o método Client::with_uri_str().

Para saber mais sobre como criar um cliente, consulte a documentação da API para Cliente e with_options().

Dica

Stable API

Você pode definir a versão da Stable API como uma opção para evitar alterações significativas ao atualizar para uma nova versão do servidor.

Para saber mais sobre o recurso de Stable API, consulte o guia da Stable API.

Exemplo de conexão

O código a seguir mostra como criar um cliente que usa uma connection string do Atlas e a versão da API estável, conecta-se ao MongoDB e verifica se a conexão foi bem-sucedida. Selecione nas guias Asynchronous API ou Synchronous API abaixo para obter amostras de código de conexão correspondentes.

Dica

Para saber mais sobre tempos de execução assíncronos e síncronos, consulte o guia APIs assíncronas e síncronas.

use mongodb::{ bson::doc, options::{ ClientOptions, ServerApi, ServerApiVersion }, Client };
#[tokio::main]
async fn main() -> mongodb::error::Result<()> {
    // Replace the placeholder with your Atlas connection string
    let uri = "<connection string>";
    let mut client_options = ClientOptions::parse(uri).await?;
    // Set the server_api field of the client_options object to Stable API version 1
    let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
    client_options.server_api = Some(server_api);
    // Create a new client and connect to the server
    let client = Client::with_options(client_options)?;
    // Send a ping to confirm a successful connection
    client.database("admin").run_command(doc! { "ping": 1 }).await?;
    println!("Pinged your deployment. You successfully connected to MongoDB!");
    Ok(())
}

use mongodb::{ bson::doc, options::{ ClientOptions, ServerApi, ServerApiVersion }, sync::Client };
fn main() -> mongodb::error::Result<()> {
    // Replace the placeholder with your Atlas connection string
    let uri = "<connection string>";
    let mut client_options = ClientOptions::parse(uri)?;
    // Set the server_api field of the client_options object to Stable API version 1
    let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
    client_options.server_api = Some(server_api);
    // Create a new client and connect to the server
    let client = Client::with_options(client_options)?;
    // Send a ping to confirm a successful connection
    client.database("admin").run_command(doc! { "ping": 1 }).run()?;
    println!("Pinged your deployment. You successfully connected to MongoDB!");
    Ok(())
}

Dica

Siga o Guia de início rápido para recuperar sua cadeia de conexão do Atlas.

Observação

Para saber mais sobre como se conectar ao Atlas sem servidor, consulte a página Limitações da instância sem servidor para identificar a versão mínima de driver necessária.

Outras maneiras de se conectar ao MongoDB

Se precisa se conectar a uma única instância ou a um conjunto de réplicas do Servidor MongoDB que não esteja hospedado no Atlas, consulte as seções a seguir para saber como.

Conecte-se a um servidor MongoDB em sua máquina local

Se você precisa executar o servidor MongoDB em sua máquina local para fins de desenvolvimento, você deve fazer o seguinte:

Siga o tutorial Instale o MongoDB para instalar o MongoDB Server em sua máquina. Selecione o tutorial de instalação apropriado de acordo com sua máquina e seu sistema operacional.
Depois de concluir a instalação, inicie o servidor.

Importante

Sempre proteja seu servidor contra ataques maliciosos. Consulte o Checklist de segurança para obter uma lista de recomendações de segurança.

Depois de iniciar com sucesso o MongoDB Server, conecte-se à sua instância local seguindo estas etapas:

Substitua a cadeia de conexão armazenada na variável uri no exemplo anterior pela cadeia de conexão da sua instância local do MongoDB.
Se você estiver executando o MongoDB Server localmente, use esta cadeia de conexão para acessá-lo:
```
mongodb://localhost:<port>
```
Nessa cadeia de conexão, <port> é o número da porta na qual você configurou o servidor para escutar conexões recebidas.
Execute o código de conexão. Se o código for executado com sucesso, você verá a seguinte saída em seu console:
```
Pinged your deployment. You successfully connected to MongoDB!
```

Dica

Veja também:

Para saber mais sobre cadeias de conexão e formatos personalizados, consulte cadeias de conexão no manual do servidor.

Conectar a um conjunto de réplicas

Uma implantação do conjunto de réplicas MongoDB é um grupo de instâncias conectadas, ou nós, onde os nós armazenam o mesmo conjunto de dados. Esta configuração de instâncias fornece redundância de dados e alta disponibilidade de dados.

Para conectar a uma implantação do conjunto de réplicas, especifique o nome do host e os números de porta de cada instância, separados por vírgulas, e o nome do conjunto de réplicas como o valor do parâmetro replicaSet na cadeia de conexão.

No exemplo a seguir, os nomes de host são host1, host2 e host3, e os números de porta são todos 27017. O nome do conjunto de réplicas é myRS. O código a seguir mostra o URI de conexão para o conjunto de réplicas com essas especificações:

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

Ao se conectar a um conjunto de réplicas, o driver realiza as seguintes ações por padrão:

Descobre todos os membros do conjunto de réplicas quando recebe o endereço de qualquer membro.
Envia operações para o membro apropriado, como instruções para escrever no nó primário . Para saber mais sobre o conjunto de réplicas primário, consulte Conjunto de réplicas primário no manual do servidor MongoDB.

Dica

Você só precisa especificar um host para se conectar a um conjunto de réplicas. No entanto, para garantir a conectividade quando o host especificado não estiver disponível, forneça a lista completa de hosts.

Conexão direta

Para forçar operações no host designado no URI de conexão, especifique a opção directConnection. As conexões diretas exibem o seguinte comportamento:

Não oferecem suporte a strings SRV.
Falham nas gravações quando o host especificado não é o primário.
Eles exigem que você especifique uma preferência de leitura secundária quando o host especificado não é o nó principal. Para saber mais sobre esses nós do conjunto de réplicas, consulte Nós secundários do conjunto de réplicas no manual do servidor.

Voltar

Conexões

Opções de conexão