Guia de conexão

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 cadeias de conexão padrão. Você também pode usar o formato de conexão de seed list de DNS caso deseje mais flexibilidade de implantação e a capacidade de alterar os servidores em rotação sem reconfigurar os clientes.

A próxima parte da cadeia de conexão contém seu nome de usuário e, se você estiver usando autenticação por senha, a própria senha. Substitua o valor de 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 próxima parte da cadeia de conexão especifica o nome do host ou o endereço IP e a porta da 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. Para saber mais sobre as opções de conexão, leia a seção Opções de conexão deste guia.

Exemplo de conexão

Para se conectar ao MongoDB, você deve criar um cliente. Um cliente gerencia conexões e executa comandos de banco de dados.

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 Connect().

Para especificar seu URI de conexão, passe-o para o método ApplyURI(), que retorna uma nova instância do ClientOptions. Para definir quaisquer outras opções, chame o método assistente relevante a partir do pacote options.

Para saber mais sobre as opções de conexão, consulte a seção Opções de conexão. Para saber mais sobre como criar um cliente, consulte a documentação da API para Cliente e Conectar().

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

O código a seguir mostra como você pode criar um cliente que utiliza uma cadeia de conexão do Atlas e a versão da Stable API, conectar-se ao MongoDB e verificar se a conexão foi bem-sucedida:

// Connects to MongoDB and sets a Stable API version
package main
import (
	"context"
	"fmt"
	"go.mongodb.org/mongo-driver/bson"
	"go.mongodb.org/mongo-driver/mongo"
	"go.mongodb.org/mongo-driver/mongo/options"
)
// Replace the placeholder with your Atlas connection string
const uri = "<connection string>"
func main() {
	// Use the SetServerAPIOptions() method to set the Stable API version to 1
	serverAPI := options.ServerAPI(options.ServerAPIVersion1)
	opts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPI)
	// Create a new client and connect to the server
	client, err := mongo.Connect(context.TODO(), opts)
	if err != nil {
		panic(err)
	}
	defer func() {
		if err = client.Disconnect(context.TODO()); err != nil {
			panic(err)
		}
	}()
	// Send 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!")
}

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

Se você precisa executar um servidor MongoDB em sua máquina local para fins de desenvolvimento, complete as seguintes etapas:

1. Baixe a versão Comunidade ou Enterprise do MongoDB Server.

2. Instale e configure o servidor MongoDB.

3. Inicie o servidor.

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

Se o servidor MongoDB estiver sendo executado 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ê quiser 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 ao servidor, substitua a cadeia de conexão pela do localhost no exemplo de código anterior.

Conectar a um conjunto de réplicas

Uma implantação do conjunto de réplicas MongoDB é um grupo de instâncias conectadas que armazenam o mesmo conjunto de dados. Esta configuração 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 seguinte, 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.

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.

• Despacha operações para o membro apropriado, como instruções para gravar no primário.

Definição de tempo limite único

Você pode definir uma única opção Timeout em seu Client para controlar o tempo que uma única operação pode levar para ser executada usando o método SetTimeout() ou especificando a opção timeoutMS em sua string URI de conexão. As instâncias Database, Collection, Session, ChangeStream e Bucket em outras partes do seu código herdarão a opção Timeout de Client se você não definir um contexto para operações na mesma entidade.

Se você fornecer um contexto para uma operação com um prazo específico, o driver usará esse prazo de contexto para a operação. Se não houver um prazo específico, o driver criará um novo contexto a partir do contexto fornecido, usando a opção Timeout definida em Client.

O código a seguir mostra como definir a opção Timeout em um Client com a opção SetTimeout:

opts := options.Client().SetTimeout(5 * time.Second)

O exemplo a seguir mostra como definir um tempo limite único com a opção URI e executar uma operação que herda esta configuração:

uri := "mongodb://user:pass@sample.host:27017/?timeoutMS=5000"
client := mongo.Connect(uri)
coll := client.Database("<db>").Collection("<collection>")
...
coll.InsertOne(context.Background(), doc)