Menu Docs

Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

Cadeias de conexão

Nesta página

  • Compatibilidade
  • Encontre sua cadeia de conexão
  • Encontre sua connection string do MongoDB Atlas
  • Encontre a connection string do seu sistema auto-hospedado
  • Formatos de cadeia de conexão
  • Formato de conexão SRV
  • Formato de connection string padrão
  • Opções de connection string
  • Opção de conjunto de réplica
  • Opções de conexão
  • Opções do pool de conexões
  • Opções de write concern
  • readConcern Opções
  • Opções de read preference
  • Opções de autenticação
  • Seleção de servidor e opções de descoberta
  • Configurações diversas
  • Exemplos de connection string
  • Exemplos de connection string de sistema do MongoDB Atlas
  • Exemplos de strings de conexão de implantação auto-hospedada

➤ Use o menu suspenso Selecione a linguagem no canto superior direito para definir a linguagem dos exemplos a seguir.

Você pode usar strings de conexão para definir conexões entre instâncias do MongoDB e os seguintes destinos:

  • Seus aplicativos quando você se conecta usando o drivers.

  • Ferramentas como MongoDB Compass e o MongoDB Shell (mongosh).

Compatibilidade

Você pode usar cadeias de conexão para se conectar a implantações hospedadas nos seguintes ambientes:

  • MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

  • MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB

  • MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Encontre sua cadeia de conexão

Conclua estas etapas para encontrar sua connection string.

Encontre sua connection string do MongoDB Atlas

Sua string de conexão do MongoDB Atlas é semelhante ao exemplo a seguir:

Encontre a connection string do seu sistema auto-hospedado

Se você estiver conectado à sua implantação de MongoDB Enterprise auto-hospedada ou MongoDB Community, execute o método db.getMongo() para retornar a string de conexão.

Se não estiver conectado à sua implantação, você poderá determinar sua string de conexão com base no tipo de conexão que deseja usar. Consulte Formato de conexão SRV para conhecer a sintaxe da string de conexão SRV ou Formato de string de conexão padrão para conhecer a sintaxe da string de conexão padrão.

Sua cadeia de conexão auto-hospedada é semelhante aos exemplos a seguir:

Para obter uma lista completa das opções de cadeia de conexão, consulte Formato de conexão SRV ou Formato padrão de cadeia de conexão. Para obter mais exemplos, consulte Exemplos de cadeia de conexão.

Formatos de cadeia de conexão

Você pode especificar a cadeia de conexão do MongoDB usando um dos seguintes formatos:

As implantações de banco de dados do MongoDB Atlas utilizam o formato de conexão SRV, a menos que você se conecte a um arquivo on-line.

Formato de conexão SRV

O MongoDB oferece suporte a uma lista de sementes construídaDNS . Usar o DNS para construir a lista de servidores disponíveis permite maior flexibilidade de implantação e a capacidade de alterar os servidores em rotação sem reconfigurar os clientes.

O esquema de conexão do URI do SRV tem o seguinte formulário:

mongodb+srv://[username:password@]host[/[defaultauthdb][?options]]

Para obter mais exemplos, consulte Exemplos de cadeia de conexão.

Componentes da connection string

Uma connection string inclui os seguintes componentes:

Componente
Descrição
mongodb:// ou mongodb+srv://
Um prefixo necessário para identificar que esta é uma string no formato de conexão padrão (mongodb://) ou no formato de conexão SRV (mongodb+srv://). Para saber mais sobre cada formato, consulte Formato de string de conexão padrão e conexão SRV.
username:password@

Opcional. Credenciais de autenticação.

Se especificado, o cliente tentará autenticar o usuário no authSource. Se o authSource não for especificado, o cliente tentará autenticar o usuário no defaultauthdb. E se o defaultauthdb não for especificado, para o banco de dados do admin .

Observação

Se o nome de usuário ou senha incluir os seguintes caracteres:

$ : / ? # [ ] @

esses caracteres devem ser convertidos usando codificação percentual.

Consulte também authSource.

host[:port]

O host (e o número da porta opcional) em que a instância mongod (ou mongos para um cluster fragmentado) está sendo executada. Você pode especificar um nome de host, endereço IP ou soquete de domínio UNIX. Especifique quantos hosts forem apropriados para sua topologia de implantação:

  • Para um standalone, especifique o nome do host da instância de mongod standalone.

  • Para um conjunto de réplica, especifique o(s) nome(s) de host da(s) instância(s) do mongod como listado na configuração do conjunto de réplicas.

  • Para um cluster fragmentado, especifique o(s) nome(s) de host da(s) instância(s) mongos.

Se o número da porta não for especificado, a porta padrão 27017 será usada.

Observação

Se você usar o formato de conexão URI do SRV, poderá especificar somente um host e nenhuma porta. Caso contrário, o driver ou o mongosh levanta um erro de análise e não executa a resolução de DNS.

/defaultauthdb

Opcional. O banco de dados de autenticação para utilizar se a string de conexão incluir credenciais de autenticação do username:password@ mas a opção authSource não for especificada.

Se tanto authSource quanto defaultauthdb não forem especificados, o cliente tentará autenticar o usuário especificado no banco de dados do admin .

?<options>

Opcional. Uma string de consulta que especifica opções específicas de conexão como <name>=<value> pares. Consulte Opções de string de conexão para obter uma descrição completa dessas opções.

Se a string de conexão não especificar um banco de dados/você deve especificar uma barra (/) entre os últimos host e o ponto de interrogação (?) que inicia a string de opções.

Para aproveitar a lista de sementes do DNS, use a mesma sintaxe de uma connection string padrão com um prefixo mongodb+srv em vez do padrão mongodb. O +srv indica ao cliente que o nome do host a seguir corresponde a um registro DNS SRV. O driver ou mongosh consultará o DNS em busca do registro para determinar quais hosts estão executando as instâncias mongod ou mongos .

Observação

O uso do modificador de string true conexão do define automaticamente a opção +srv ou equivalente tls ssl a conexão. Você pode substituir este comportamento configurando explicitamente a opção tls (ou ssl equivalente) para false com tls=false (ou ssl=false) na string de consulta.

Ao usar o formato +srv, você deve especificar hostname, domain e top-level domain (TLD) no seguinte formato: <hostname>.<domain>.<TLD>. Essa tabela mostra como os espaços reservados correspondem aos valores de exemplo:

Espaço reservado
Exemplo
<hostname>
server
<domain>
example
<TLD>
com
<hostname>.<domain>.<TLD>
server.example.com

Este exemplo mostra uma connection string da lista de sementes de DNS que usa corretamente o formato <hostname>.<domain>.<TLD>. Ele autentica como usuário myDatabaseUser com a senha D1fficultP%40ssw0rd:

mongodb+srv://myDatabaseUser:D1fficultP%40ssw0rd@server.example.com/

A configuração de DNS correspondente é semelhante a:

Record                            TTL   Class    Priority Weight Port  Target
_mongodb._tcp.server.example.com. 86400 IN SRV   0        5      27317 mongodb1.example.com.
_mongodb._tcp.server.example.com. 86400 IN SRV   0        5      27017 mongodb2.example.com.

Os registros SRV individuais devem estar no formato _mongodb._tcp.<hostname>.<domain>.<TLD>.

Quando um cliente se conecta a um membro da lista de sementes, ele recupera uma lista de membros do conjunto de réplicas aos quais ele pode se conectar. Os clientes geralmente usam aliases DNS em suas listas de sementes, o que significa que o host pode retornar uma lista de servidores diferente da lista de sementes original. Se isso acontecer, os clientes usarão os nomes de host fornecidos pelo conjunto de réplicas em vez dos nomes de host listados na lista de sementes para garantir que os membros do conjunto de réplicas possam ser alcançados por meio dos nomes de host na configuração do conjunto de réplicas resultante.

Importante

Os nomes de host retornados nos registros SRV devem compartilhar o mesmo domínio pai (neste exemplo, example.com) do nome de host fornecido. Se os domínios pai e o nome de host não corresponderem, você não poderá se conectar.

Este exemplo mostra uma connection string de lista de sementes de DNS sem <hostname>. Isso está incorreto e gera um erro.

# This connection string is missing the <hostname> and raises a connection error
mongodb+srv://myDatabaseUser:D1fficultP%40ssw0rd@example.com/

Assim como a connection string padrão, a connection string da lista de sementes de DNS oferece suporte à especificação de opções como uma string de query. Com uma connection string de lista de sementes de DNS, você também pode especificar as seguintes opções por meio de um registro TXT:

  • replicaSet

  • authSource

Você só pode especificar um registro TXT por instância do mongod. Se vários registros TXT forem exibidos no DNS e/ou se o registro TXT contiver uma opção diferente de replicaSet ou authSource, o cliente retornará um erro.

O registro TXT para a entrada de DNS do server.example.com se assemelharia a:

Record              TTL   Class    Text
server.example.com. 86400 IN TXT   "replicaSet=mySet&authSource=authDB"

Juntos, os registros DNS SRV e as opções especificadas no registro TXT resultam na seguinte cadeia de conexão de formato padrão:

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongodb1.example.com:27317,mongodb2.example.com:27017/?replicaSet=mySet&authSource=authDB

Você pode substituir as opções especificadas em um registro TXT passando a opção na string de query. No exemplo a seguir, a string de query forneceu uma substituição para a opção authSource configurada no registro TXT da entrada DNS acima.

mongodb+srv://myDatabaseUser:D1fficultP%40ssw0rd@server.example.com/?connectTimeoutMS=300000&authSource=aDifferentAuthDB

Dada a substituição de authSource, a connection string equivalente no formato padrão seria:

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongodb1.example.com:27317,mongodb2.example.com:27017/?connectTimeoutMS=300000&replicaSet=mySet&authSource=aDifferentAuthDB

Observação

A opção mongodb+srv falhará se não houver DNS disponível com registros que correspondam ao nome do host identificado na connection string. Se você usar o modificador de string de conexão +srv , a opção tls (ou ssl equivalente) é definida como true para a conexão. Você pode substituir este comportamento configurando explicitamente a opção tls (ou ssl equivalente) para false com tls=false (ou ssl=false) na string de consulta.

Para obter um exemplo que a um usando o formato de conexão da lista de sementes do DNS,mongosh consulte

Formato de connection string padrão

Esta seção descreve o formato padrão do URI de conexão do MongoDB usado para conectar-se a uma implantação autônoma, conjunto de réplicas ou cluster fragmentado do MongoDB auto-hospedado.

O esquema de conexão URI padrão tem o formulário:

mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]

Para obter mais exemplos, consulte Exemplos de cadeia de conexão.

Componentes da connection string

Uma connection string inclui os seguintes componentes:

Componente
Descrição
mongodb:// ou mongodb+srv://
Um prefixo necessário para identificar que esta é uma string no formato de conexão padrão (mongodb://) ou no formato de conexão SRV (mongodb+srv://). Para saber mais sobre cada formato, consulte Formato de string de conexão padrão e conexão SRV.
username:password@

Opcional. Credenciais de autenticação.

Se especificado, o cliente tentará autenticar o usuário no authSource. Se o authSource não for especificado, o cliente tentará autenticar o usuário no defaultauthdb. E se o defaultauthdb não for especificado, para o banco de dados do admin .

Observação

Se o nome de usuário ou senha incluir os seguintes caracteres:

$ : / ? # [ ] @

esses caracteres devem ser convertidos usando codificação percentual.

Consulte também authSource.

host[:port]

O host (e o número da porta opcional) em que a instância mongod (ou mongos para um cluster fragmentado) está sendo executada. Você pode especificar um nome de host, endereço IP ou soquete de domínio UNIX. Especifique quantos hosts forem apropriados para sua topologia de implantação:

  • Para um standalone, especifique o nome do host da instância de mongod standalone.

  • Para um conjunto de réplica, especifique o(s) nome(s) de host da(s) instância(s) do mongod como listado na configuração do conjunto de réplicas.

  • Para um cluster fragmentado, especifique o(s) nome(s) de host da(s) instância(s) mongos.

Se o número da porta não for especificado, a porta padrão 27017 será usada.

Observação

Se você usar o formato de conexão URI do SRV, poderá especificar somente um host e nenhuma porta. Caso contrário, o driver ou o mongosh levanta um erro de análise e não executa a resolução de DNS.

/defaultauthdb

Opcional. O banco de dados de autenticação para utilizar se a string de conexão incluir credenciais de autenticação do username:password@ mas a opção authSource não for especificada.

Se tanto authSource quanto defaultauthdb não forem especificados, o cliente tentará autenticar o usuário especificado no banco de dados do admin .

?<options>

Opcional. Uma string de consulta que especifica opções específicas de conexão como <name>=<value> pares. Consulte Opções de string de conexão para obter uma descrição completa dessas opções.

Se a string de conexão não especificar um banco de dados/você deve especificar uma barra (/) entre os últimos host e o ponto de interrogação (?) que inicia a string de opções.

Opções de connection string

Esta seção lista todas as opções de conexão para cadeias de conexão SRV e cadeias de conexão padrão.

As opções de conexão são pares no seguinte formulário: name=value.

  • A opção name diferencia maiúsculas de minúsculas ao utilizar um condutor.

  • A opção name diferencia maiúsculas de minúsculas ao utilizar mongosh.

  • O(A) value sempre diferencia maiúsculas de minúsculas.

Separe as opções com o caractere ampersand (&) name1=value1&name2=value2. No exemplo a seguir, uma conexão inclui as opções replicaSet e connectTimeoutMS :

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db1.example.net:27017,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000

Observação

Separador de ponto e vírgula para argumentos de connection string

Para oferecer compatibilidade com versões anteriores, atualmente, os drivers aceitam ponto e vírgula (;) como separadores de opções.

Opção de conjunto de réplica

A seguinte cadeia de caracteres de conexão conecta a um conjunto de réplica denominado myRepl com membros executando nos hosts especificados. Ele autentica como usuário myDatabaseUser com a senha D1fficultP%40ssw0rd:

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com:27017,db1.example.com:27017,db2.example.com:27017/?replicaSet=myRepl
Opção de conexão
Descrição
replicaSet

Especifica o nome do conjunto de réplicas, se o mongod for um membro de um conjunto de réplica. Defina a opção de conexão replicaSet para garantir um comportamento consistente entre drivers.

Ao conectar a um conjunto de réplicas, forneça uma lista de seeds dos membros do conjunto de réplicas para o componente host[:port] do uri. Para obter detalhes específicos, consulte a documentação do driver.

Opções de conexão

Opções de TLS

A connection string a seguir para um conjunto de réplicas inclui a opção tls=true . Ele autentica como usuário myDatabaseUser com a senha D1fficultP%40ssw0rd.

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&tls=true

Além disso, você também pode utilizar a opção ssl=true equivalente:

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&ssl=true
Opção de conexão
Descrição
tls

Habilita ou desabilita TLS/SSL para a conexão:

Observação

A opção tls é equivalente à opção ssl .

Se a shell do mongosh especificar opções adicionais de tls/ssl da linha de comando, utilize a opção de linha de comando do --tls .

ssl

Um booleano para ativar ou desativar TLS/SSL para a conexão:

Observação

A opção ssl é equivalente à opção tls .

Se a shell do mongosh especificar opções adicionais de tls/ssl da linha de comando, utilize a opção de linha de comando do --ssl .

tlsCertificateKeyFile

Especifica o local de um arquivo .pem local que contém o certificado TLS/SSL X.509 do cliente ou o certificado e chave TLS/SSL do cliente.

O cliente apresenta este arquivo para a instância mongod/mongos.

mongod / mongos registra um aviso na conexão se o certificado x.509 apresentado expirar dentro 30 dias a partir da hora do sistema do host mongod/mongos . Consulte Avisos de trigger de certificados x.509 próximos da expiração para obter mais informações.

Esta opção não é compatível com todos os drivers. Consulte a documentação sobre os drivers.

Esta opção de connection string não está disponível para o shell mongo. Use a opção de linha de comando.

tlsCertificateKeyFilePassword

Especifica a senha para descriptografar o tlsCertificateKeyFile.

Esta opção não é compatível com todos os drivers. Consulte a documentação sobre os drivers.

Esta opção de connection string não está disponível para o shell mongo. Use a opção de linha de comando.

tlsCAFile

Especifica o local de um arquivo de .pem local que contém a cadeia de certificados raiz da Autoridade de Certificação. Esse arquivo é usado para validar o certificado apresentado pela instânciamongod / mongos.

Esta opção não é compatível com todos os drivers. Consulte a documentação sobre os drivers.

Esta opção de connection string não está disponível para o shell mongo. Use a opção de linha de comando.

tlsAllowInvalidCertificates

Ignora a validação dos certificados apresentados pela instância mongod / mongos

Defina como true para se conectar às instâncias do MongoDB mesmo que o servidor apresente certificados inválidos.

Esta opção não é compatível com todos os drivers. Consulte a documentação sobre os drivers.

Esta opção de connection string não está disponível para o shell mongo. Use a opção de linha de comando.

Aviso

A desativação da validação do certificado cria uma vulnerabilidade.

tlsAllowInvalidHostnames

Desativa a validação do nome de host do certificado apresentado pela instância mongod / mongos.

Configure para true para conectar às instâncias MongoDB mesmo que o nome de host nos certificados do servidor não correspondam ao host do servidor.

Esta opção não é compatível com todos os drivers. Consulte a documentação sobre os drivers.

Esta opção de connection string não está disponível para o shell mongo. Use a opção de linha de comando.

Aviso

A desativação da validação do certificado cria uma vulnerabilidade.

tlsInsecure

Desabilita várias validações de certificado.

Defina como true para desabilitar as validações do certificado. As validações exatas desativadas variam de acordo com os drivers. Consulte a documentação sobre os drivers .

Esta opção de connection string não está disponível para o shell mongo. Use a opção de linha de comando.

Aviso

A desativação da validação do certificado cria uma vulnerabilidade.

Opções de tempo limite

Opção de conexão
Descrição
connectTimeoutMS
O tempo em milissegundos para tentar uma conexão antes de atingir o tempo limite. O padrão é 10,000 milissegundos, mas drivers específicos podem ter um padrão diferente. Para obter detalhes, consulte a documentação do driver .
socketTimeoutMS
O tempo em milissegundos para tentar enviar ou receber em um soquete antes que a tentativa expire. O padrão é nunca atingir o tempo limite, embora drivers diferentes possam variar. Consulte a documentação do driver.

Opções de compressão

Opção de conexão
Descrição
compressors

String delimitada por vírgula de compressores para habilitar a compressão de rede para comunicação entre este cliente e uma instância mongod / mongos.

Você pode especificar os seguintes compressores:

Se você especificar vários compressores, a ordem na qual você lista os compressores importam, bem como o iniciador de comunicação. Por exemplo, se o cliente especificar os seguintes compressores de rede "zlib,snappy" e o mongod especificar "snappy,zlib", as mensagens entre o cliente e o mongod utilizarão zlib.

Importante

As mensagens são compactadas quando ambas as partes habilitam a compactação de rede. Caso contrário, as mensagens entre as partes serão descompactadas.

Se as partes não compartilharem pelo menos um compressor comum, as mensagens entre as partes serão descompactadas.

mongosh suporta a opção de connection string uri compressors.

zlibCompressionLevel

Um número inteiro que especifica o nível de compressão se utilizar zlib para network compression.

Você pode especificar um valor inteiro na faixa entre -1 e 9:

Valor
Notas
-1
Nível de compressão padrão, geralmente compressão nível 6.
0
Sem compressão
1 - 9

Aumento do nível de compressão, mas ao custo da velocidade, com:

  • 1 fornecendo a melhor velocidade, mas menor compactação, e

  • 9 fornecendo a melhor compressão, mas na velocidade mais lenta.

Suportado por mongosh.

Opções do pool de conexões

A maioria dos drivers implementa algum tipo de tratamento de pool de conexões. Alguns drivers não oferecem suporte a pool de conexões. Consulte a documentação do driver para obter mais informações sobre a implantação do pool de conexões. Essas opções permitem que os aplicativos configurem o pool de conexão ao se conectar à implantação do MongoDB.

Opção de conexão
Descrição
maxPoolSize
O número máximo de conexões no pool de conexões. O valor padrão é 100.
minPoolSize

O número mínimo de conexões no pool de conexões. O valor padrão é 0.

Observação

A opção minPoolSize não é suportada por todos os drivers. Para obter informações sobre o motorista, consulte a documentação Drivers .

maxConnecting

Número máximo de conexões que um pool pode estabelecer simultaneamente. O valor padrão é 2.

maxConnecting é compatível com todos os drivers , exceto o Rust Driver.

Aumentar o valor de maxConnecting permite que o cliente estabeleça conexão com o servidor mais rápido, mas aumenta a chance de tempestades de conexão. Se o valor de maxConnecting for muito baixo, o pool de conexões poderá sofrer fortes limitações e aumentar a latência da parte final para os clientes que estiverem checando as conexões.

maxIdleTimeMS

O número máximo de milissegundos que uma conexão pode permanecer inativa no pool antes de ser removida e fechada.

Esta opção não é suportada por todos os drivers.

waitQueueMultiple

Um número ao qual o driver multiplica o valor de maxPoolSize , para fornecer o número máximo de threads permitidos para aguardar uma conexão se tornar disponível a partir do grupo. Para valores padrão, consulte a documentação do driver .

Esta opção não é suportada por todos os drivers.

waitQueueTimeoutMS

O tempo máximo em milissegundos que um thread pode esperar que uma conexão fique disponível. Para valores padrão, consulte a documentação do driver .

Esta opção não é suportada por todos os drivers.

Opções de write concern

A write concern descreve o nível de confirmação solicitado ao MongoDB. A opção write concern é suportada por:

Você pode especificar o write concern na connection string e como um parâmetro para métodos como insert ou update. Se o write concern for especificado em ambos os locais, o método parâmetro substituirá a connection string de configuração.

As connection strings de implantação do MongoDB Atlas usam "majority" por padrão. Se você não especificar o write concern para uma implantação do MongoDB Atlas, o MongoDB Atlas imporá"majority".

A connection string a seguir para um conjunto de réplicas especifica o write concern "majority" e um segundo tempo limite 5 usando o parâmetro de write concern wtimeoutMS :

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&w=majority&wtimeoutMS=5000
Opção de conexão
Descrição
w

Corresponde à opção de w da preocupação de gravação. A opção w solicita a confirmação de que a operação de gravação se propagou para um número especificado de instâncias mongod ou para instâncias mongod com tags especificadas.

Você pode especificar um number, a string majority ou um tag set.

Para obter detalhes, consulte Opção w.

wtimeoutMS

Corresponde à write concern de escrita wtimeout. wtimeoutMS especifica um limite de tempo, em milissegundos, para a write concern.

Quando wtimeoutMS é 0, as operações de gravação nunca atingem o tempo limite. Para mais informações, consulte wtimeout.

journal

Corresponde à opção de Opçãoj write concern. A opção journal solicita confirmação do MongoDB de que a operação de gravação foi gravada no diário. Para obter detalhes, consulte Opçãoj .

Se você definir journal como true e especificar um valor de w menor que 1, journal prevalecerá.

Para obter mais informações, consulte Preocupação de gravação.

readConcern Opções

Para o mecanismo de armazenamento WiredTiger, o MongoDB 3.2 introduz a opção readConcern para conjuntos de réplicas e fragmentos de conjuntos de réplicas.

Ler Preocupação permite que os clientes escolham um nível de isolamento para suas leituras a partir de conjuntos de réplica.

A seguinte cadeia de caracteres de conexão para um conjunto de réplica especifica readConcernLevel=majority:

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&readConcernLevel=majority
Opção de conexão
Descrição
readConcernLevel

O nível de isolamento. Pode aceitar um dos seguintes valores:

Esta opção de string de conexão não está disponível para mongosh. Especifique a read concern como uma opção para a operação específica.

Para obter mais informações, consulte Preocupação de leitura.

Opções de read preference

Read preferences descrevem o comportamento das operações de leitura em relação aos conjuntos de réplicas. Esses parâmetros permitem que você especifique preferências de leitura por conexão na connection string.

Observação

Para especificar a opção de leituras distribuídas usando os drivers, consulte a preferência de leitura dos drivers.

Por exemplo:

  • A seguinte connection string para um conjunto de réplica especifica o modo de read preference do secondary e um valor de maxStalenessSeconds de 120 segundos:

    mongodb://myDatabaseUser:D1fficultP%40ssw0rd@db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&readPreference=secondary&maxStalenessSeconds=120

  • A seguinte connection string para um cluster fragmentado especifica o modo read preference do secondary e um valor de maxStalenessSeconds de 120 segundos:

    mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongos1.example.com,mongos2.example.com/?readPreference=secondary&maxStalenessSeconds=120

  • A connection string a seguir para um cluster fragmentado especifica o modo de read preference secondary , bem como três readPreferenceTags:

    mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongos1.example.com,mongos2.example.com/?readPreference=secondary&readPreferenceTags=dc:ny,rack:r1&readPreferenceTags=dc:ny&readPreferenceTags=

A ordem é importante ao usar vários readPreferenceTags. Os readPreferenceTags são testados em ordem até que uma correspondência seja encontrada. Uma vez encontrada, essa especificação é usada para encontrar todos os membros correspondentes elegíveis e quaisquer readPreferenceTags restantes são ignorados. Para obter detalhes, consulte Ordem de correspondência de tags.

Opção de conexão
Descrição
readPreference

Especifica as preferências de leitura para esta conexão. Os valores possíveis são:

Transações distribuídas que contêm operações de leitura devem usar a read preference primary. Todas as operações em uma determinada transação devem ser roteadas para o mesmo membro.

Esta opção de string de conexão não está disponível para a shell mongo. Consulte, então, cursor.readPref() e Mongo.setReadPref().

maxStalenessSeconds

Especifica, em segundos, o quão obsoleto um secundário pode ser antes de o cliente parar de usá-lo para operações de leitura. Para detalhes, consulte Preferência de leitura maxStalenessSeconds.

Por padrão, não há desatualização máxima e os clientes não considerarão o atraso do secundário ao escolher para onde direcionar uma operação de leitura.

O valor mínimo maxStalenessSeconds é 90 segundos. Especificar um valor entre 0 e 90 segundos produzirá um erro. Os drivers do MongoDB tratam um valor maxStalenessSeconds de -1 como "no max staleness", o mesmo que se maxStalenessSeconds fosse omitido.

Importante

Para usar maxStalenessSeconds, todas as instâncias do MongoDB em sua implantação devem usar o MongoDB 3.4 ou posterior. Se alguma instância estiver em uma versão anterior do MongoDB, o driver ou mongod / mongos gerará um erro.

readPreferenceTags

Especifica o documento de tags como uma lista separada por vírgula de pares de valores-chave separados por dois pontos. Por exemplo,

  • Para especificar o documento de etiquetas { "dc": "ny", "rack": "r1" }, utilize readPreferenceTags=dc:ny,rack:r1 na cadeia de ligação.

  • Para especificar um documento de etiquetas vazias { }, utilize readPreferenceTags= sem definir o valor.

Para especificar uma lista de documentos de tags, use vários readPreferenceTags. Por exemplo, readPreferenceTags=dc:ny,rack:r1&readPreferenceTags=.

A ordem é importante ao usar vários readPreferenceTags. Os readPreferenceTags são testados em ordem até que uma correspondência seja encontrada. Para obter detalhes, consulte Ordem de correspondência de tags.

Esta opção de string de conexão não está disponível para a shell mongo. Consulte, então, cursor.readPref() e Mongo.setReadPref().

Para mais informações, consulte Preferências de leitura.

Opções de autenticação

A seguinte cadeia de caracteres de conexão para um conjunto de réplica especifica o banco de dados do authSource para o admin . Ou seja, as credenciais do usuário são autenticadas no banco de dados admin .

mongodb://myDatabaseUser:D1fficultP%40ssw0rd@mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?replicaSet=myRepl&authSource=admin

Observação

Se o nome de usuário ou senha incluir os seguintes caracteres:

$ : / ? # [ ] @

esses caracteres devem ser convertidos usando codificação percentual.

Opção de conexão
Descrição
authSource

Especifique o nome do banco de dados associado às credenciais do usuário. Se authSource não for especificado, authSource padronizará para o defaultauthdb especificado na string de conexão. Se defaultauthdb não for especificado, então authSource padroniza para admin.

Os mecanismos de autenticação PLAIN (LDAP), GSSAPI (Kerberos) e MONGODB-AWS (IAM) exigem que authSource seja definido como $external, pois esses mecanismos delegam o armazenamento de credenciais a serviços externos.

O MongoDB ignorará os valores authSource se nenhum nome de usuário for fornecido, seja na connection string ou por meio do parâmetro --username .

authMechanism

Padrão: SCRAM-SHA-256

Especifique o mecanismo de autenticação que o MongoDB usa para autenticar a conexão. Se você não especificar um authMechanism, mas fornecer credenciais de usuário, o MongoDB tentará usar o SCRAM-SHA-256. Se isso falhar, ele volta para SCRAM-SHA-1.

Somente instâncias do MongoDB Enterprise mongod e mongos fornecem mecanismos do GSSAPI (Kerberos) e PLAIN (LDAP).

Para usar o MONGODB-X509, você deve ter TLS/SSL ativado.

Para usar MONGODB-AWS o , você deve estar se conectando a um cluster do MongoDB Atlas que tenha sido configurado para suportar autenticação via Credenciais AWS IAM (um ID de chave de acesso da AWS e uma chave de acesso secreta e, opcionalmente, um token de sessão da AWS ). O MONGODB-AWS mecanismo de autenticação exige que o authSource seja definido como $external.

Ao utilizar MONGODB-AWS o , forneça seu ID de chave de acesso AWS como o nome de usuário e a chave de acesso secreta como a senha. Se estiver usando um token de sessão da AWS também, forneça o AWS_SESSION_TOKEN authMechanismProperties valor .

Observação

Se o ID da chave de acesso da AWS, a chave de acesso secreta ou o token de sessão incluírem os seguintes caracteres:

$ : / ? # [ ] @

esses caracteres devem ser convertidos usando codificação percentual.

Como alternativa, se o ID da chave de acesso da AWS, a chave de acesso secreta ou o token de sessão estiverem definidos em sua plataforma usando suas respectivas variáveis de ambiente da AWS IAM mongosh usará esses valores de variáveis de ambiente para autenticar; você não precisa especificá-los na connection string.

Consulte Connect to an Atlas Cluster para ver, por exemplo, o uso do mecanismo de autenticação MONGODB-AWS usando uma connection string e o método de variáveis do ambiente.

Consulte Autenticação para obter mais informações sobre o sistema de autenticação no MongoDB. Considere também Usar certificados x.509 para autenticar clientes para obter mais informações sobre a autenticação x509.

authMechanismProperties

Especifique propriedades para o authMechanism especificado como uma lista separada por vírgula de pares de valores-chave separados por vírgula.

Os possíveis pares de chave-valor são:

SERVICE_NAME:<string>

Defina o nome do serviço Kerberos ao conectar-se a instâncias do MongoDB com suporte do Kerberos. Esse valor deve corresponder ao nome do serviço definido nas instâncias do MongoDB das quais você está se conectando. Válido apenas ao usar o mecanismo de autenticação GSSAPI.

SERVICE_NAME padrão para mongodb para todos os clientes e instâncias MongoDB. Se você alterar a configuração saslServiceName em uma instância do MongoDB, deverá definir SERVICE_NAME para corresponder a essa configuração. Válido apenas ao usar o mecanismo de autenticação GSSAPI.

CANONICALIZE_HOST_NAME:true|false
Canonize o nome de host da máquina host do cliente ao conectar ao servidor Kerberos. Isso pode ser necessário quando os hosts relatam nomes de host diferentes do que está no banco de dados Kerberos. Padrão é false. Válido apenas ao usar o mecanismo de autenticação GSSAPI.
SERVICE_REALM:<string>
Configure a região Kerberos para o serviço MongoDB. Isso pode ser necessário para suportar a autenticação entre domínios onde o usuário existe em um domínio e o serviço em outro. Válido apenas ao usar o mecanismo de autenticação GSSAPI.
AWS_SESSION_TOKEN:<security_token>
Defina o token de sessão da AWS para autenticação com credenciais temporárias ao usar um AssumeRole solicitação ou ao trabalhar com recursos da AWS que especificam esse valor, como Lambda. Válido apenas ao usar o MONGODB-AWS mecanismo de autenticação . Você também deve ter um ID de chave de acesso da AWS e uma chave de acesso secreta. Consulte Conectar-se a um Atlas cluster para obter exemplos de uso.
gssapiServiceName

Defina o nome do serviço Kerberos ao conectar-se a instâncias Kerberized MongoDB. Esse valor deve corresponder ao nome do serviço definido nas instâncias do MongoDB às quais você está se conectando.

gssapiServiceName padrão é mongodb para todos os clientes e instâncias do MongoDB. Se você alterar a configuração saslServiceName em uma instância do MongoDB, deverá definir gssapiServiceName para corresponder a essa configuração.

gssapiServiceName é um alias obsoleto para authMechanismProperties=SERVICE_NAME:mongodb. Para obter mais informações sobre quais opções seu driver oferece suporte e sua prioridade relativa entre si, consulte a documentação da versão do driver de sua preferência.

Seleção de servidor e opções de descoberta

O MongoDB fornece as seguintes opções para configurar como drivers do MongoDB e instâncias do mongos selecionam um servidor para o qual direcionar operações de leitura ou gravação.

Opção de conexão
Descrição
localThresholdMS

O tamanho (em milissegundos) da janela de latência para selecionar entre várias instâncias MongoDB adequadas. Padrão: 15 milissegundos.

Todos os drivers usam o localThresholdMS. Use o alias localThreshold ao especificar o tamanho da janela de latência para mongos.

serverSelectionTimeoutMS
Especifica por quanto tempo (em milissegundos) bloquear para seleção de servidor antes de lançar uma exceção. Padrão: 30.000 milissegundos.
serverSelectionTryOnce

Somente drivers de thread único. Quando o true, instrui o driver a verificar a implantação do MongoDB exatamente uma vez após a falha da seleção do servidor e então selecionar um servidor ou levantar um erro. Quando false, o driver bloqueia e pesquisa um servidor até o valor serverSelectionTimeoutMS . Padrão: true.

Drivers de threads múltiplas e mongos não suportam serverSelectionTryOnce.

heartbeatFrequencyMS

heartbeatFrequencyMS controla quando o driver verifica o estado da implantação do MongoDB. Especifique o intervalo (em milissegundos) entre verificações, contado desde o final da verificação anterior até o início da próxima.

Padrão:

  • Drivers de thread único: 60 segundos.

  • Drivers multithread: 10 segundos.

mongos não oferece suporte à alteração da frequência das verificações de pulsação.

Configurações diversas

Opção de conexão
Descrição
appName

Especifique um nome de aplicativo personalizado. O nome do aplicativo aparece em:

A opção de conexão do appName está disponível para:

retryReads

Habilite leituras repetíveis

Os valores possíveis são:

  • true. Habilita leituras repetíveis para a conexão.

    Os drivers oficiais do MongoDB são padronizados como true.

  • false. Desativa leituras repetíveis para a conexão.

mongosh não oferece suporte a leituras repetíveis.

retryWrites

Habilite gravações repetíveis.

Os valores possíveis são:

  • true. Permite gravações que podem ser repetidas na conexão.

    Os drivers oficiais do MongoDB são padronizados como true.

  • false. Desativa as gravações que podem ser repetidas na conexão.

    Os drivers oficiais compatíveis com MongoDB 4.0 e 3.6 são padronizados para false.

Os drivers do MongoDB tentam novamente a confirmação da transação e abortam as operações, independentemente do valor de retryWrites. Para obter mais informações sobre a capacidade de repetição de transações, consulte Tratamento de erros de transação.

uuidRepresentation

Os valores possíveis são:

standard
A representação binária padrão.
csharpLegacy
A representação predefinida para o condutor C#.
javaLegacy
A representação padrão para o driver Java.
pythonLegacy
A representação padrão do driver Python.

Para saber qual é o padrão, consulte a documentação dos drivers do seu driver.

Observação

Nem todos os motoristas suportam a opção uuidRepresentation . Para obter informações sobre seu motorista, consulte a documentação do motorista .

Exemplos de connection string

Veja a seguir exemplos de strings de URI para destinos de conexão comuns.

Exemplos de connection string de sistema do MongoDB Atlas

As cadeias de conexão de exemplo a seguir se conectam a uma implantação do MongoDB Atlas.

Agrupamento do Atlas do MongoDB que se autentica com um nome de usuário e senha

MongoDB Atlas Cluster que autentica com credenciais AWS IAM

O seguinte se conecta a um cluster do MongoDB Atlas que foi configurado para suportar autenticação via Credenciais AWS IAM:

A conexão ao Atlas utilizando credenciais AWS IAM desta maneira utiliza o MONGODB-AWS authentication mechanism e o $external authSource, como mostrado neste exemplo.

Se estiver usando um token de sessão da AWS , também forneça o AWS_SESSION_TOKEN authMechanismProperties valor , como segue:

Observação

Se o ID da chave de acesso da AWS, a chave de acesso secreta ou o token de sessão incluírem os seguintes caracteres:

$ : / ? # [ ] @

esses caracteres devem ser convertidos usando codificação percentual.

Você também pode definir essas credenciais em sua plataforma usando variáveis de ambiente padrão do AWS IAM . verifica as seguintes variáveis de ambiente quando você usamongosh o MONGODB-AWS authentication mechanism:

  • AWS_ACCESS_KEY_ID

  • AWS_SECRET_ACCESS_KEY

  • AWS_SESSION_TOKEN

Se definidas, essas credenciais não precisam ser especificadas na cadeia de conexão.

O exemplo a seguir define essas variáveis de ambiente no shell bash :

export AWS_ACCESS_KEY_ID='<aws access key id>'
export AWS_SECRET_ACCESS_KEY='<aws secret access key>'
export AWS_SESSION_TOKEN='<aws session token>'

A sintaxe para definir variáveis de ambiente em outros shells será diferente. Consulte a documentação da sua plataforma para obter mais informações.

Você pode verificar se essas variáveis de ambiente foram definidas com o seguinte comando:

env | grep AWS

Depois de definido, o exemplo a seguir se conecta a um MongoDB Atlas cluster usando estas variáveis de ambiente:

Exemplos de strings de conexão de implantação auto-hospedada

As cadeias de conexão de exemplo a seguir se conectam a uma implantação auto-hospedada.

Agrupamento auto-hospedado que se autentica com um nome de usuário e senha

Servidor de banco de dados auto-hospedado em execução localmente

O seguinte se conecta a um servidor de banco de dados em execução localmente na porta padrão:

Banco de dados admin auto-hospedado em execução local

O seguinte conecta e registra no banco de dados do admin como usuário myDatabaseUser com a senha D1fficultP%40ssw0rd:

Banco de dados records auto-hospedado em execução local

O seguinte conecta e registra no banco de dados do records como usuário myDatabaseUser com a senha D1fficultP%40ssw0rd:

Soquete de domínio UNIX auto-hospedado

Use uma cadeia de conexão codificada em URL ao conectar-se a um soquete de domínio UNIX.

O seguinte se conecta a um soquete de domínio UNIX com o caminho de arquivo /tmp/mongodb-27017.sock como usuário myDatabaseUser com a senha D1fficultP%40ssw0rd:

Observação

Nem todos os drivers suportam soquetes de domínio UNIX. Para obter informações sobre o motorista, consulte a documentação Drivers .

Conjunto de réplica auto-hospedada com membros em diferentes máquinas

O seguinte conecta a um conjunto de réplica com dois membros, um no db1.example.net e outro no db2.example.net, como usuário myDatabaseUser com a senha D1fficultP%40ssw0rd:

Observação

Para um conjunto de réplica, especifique o(s) nome(s) de host da(s) instância(s) do mongod como listado na configuração do conjunto de réplicas.

Conjunto de réplica auto-hospedada com membros ligados localhost

O seguinte conecta a uma réplica configurada com três membros executando no localhost nas portas 27017, 27018 e 27019 como usuário myDatabaseUser com a senha D1fficultP%40ssw0rd:

Observação

Para um conjunto de réplica, especifique o(s) nome(s) de host da(s) instância(s) do mongod como listado na configuração do conjunto de réplicas.

Conjunto de réplica auto-hospedada com distribuição de leitura

O seguinte conecta a um conjunto de réplicas com três membros e distribui leituras para os secundários como usuário myDatabaseUser com a senha D1fficultP%40ssw0rd:

Observação

Para um conjunto de réplica, especifique o(s) nome(s) de host da(s) instância(s) do mongod como listado na configuração do conjunto de réplicas.

Conjunto de réplica auto-hospedada com um alto nível de preocupação de escrita

O seguinte se conecta a um conjunto de réplicas com write concern configurado para aguardar que a replicação seja bem-sucedida na maioria dos membros votantes portadores de dados, com um tempo limite de dois segundos. Ele autentica como usuário myDatabaseUser com a senha D1fficultP%40ssw0rd.

Observação

Para um conjunto de réplica, especifique o(s) nome(s) de host da(s) instância(s) do mongod como listado na configuração do conjunto de réplicas.

Cluster fragmentado auto-hospedado

O seguinte se conecta a um cluster fragmentado com três instâncias mongos como usuário myDatabaseUser com a senha D1fficultP%40ssw0rd:

← Mapeamento de definições de arquivos de configuração e opções de linha de comando
Comandos de banco de dados →

Nesta página