Especificar opções de conexão

Esta seção explica as opções de conexão e autenticação do MongoDB compatíveis com o driver Node.js que você pode definir em uma instância MongoClientOptions.

Para obter mais informações sobre como definir as opções de conexão diretamente em uma string de conexão, consulte Connection strings no manual do MongoDB Server .

Nome	Valores aceitos	Valor padrão	Descrição
appName	string	`null`	Especifica o nome do aplicativo que o driver passa para o servidor nos metadados do cliente como parte da confirmação de conexão. O driver envia o valor de `appName` para o MongoDB ao estabelecer a conexão. Esse valor é registrado no arquivo de registro, nos logs de query lentos e nas collections de perfil.
authMechanism	string	`null`	Especifica o método do mecanismo de autenticação a ser usado para conexão com o servidor. Se você não especificar um valor, o driver utilizará o mecanismo padrão, `SCRAM-SHA-1` ou `SCRAM-SHA-256` dependendo da versão do servidor . Consulte a seção Mecanismos de autenticação para ver os mecanismos de autenticação disponíveis.
authMechanismProperties	chave separada por vírgula:pares de valores, por exemplo, "opt1:val1,opt2:val2"	`null`	Especifica outras opções fornecidas para autenticação, como a opção de ativar a canonização do nome do host para GSSAPI.
authSource	string	`null`	Especifica o banco de dados com o qual as conexões se autenticam.
autoSelectFamily	booleano	`true`	Se definido como `true`, o soquete tentará se conectar a endereços IPv6 e IPv4 até que uma conexão seja estabelecida. Se disponível, o driver selecionará o primeiro endereço IPv6.
autoSelectFamilyAttemptTimeout	non-negative integer	`null`	Especifica a quantidade de tempo, em milissegundos, para aguardar a conclusão de uma tentativa de conexão antes de tentar o próximo endereço ao usar a opção `autoSelectFamily`. Se definido como um número inteiro positivo menor que `10`, o valor `10` será usado.
compressors	lista separada por vírgula de strings, por exemplo, "snappy,zlib,zstd"	`null`	Especifica os tipos de compactação permitidos para mensagens de protocolo de fio enviadas ou recebidas do servidor. Consulte Compressão de rede para mais informações.
connectTimeoutMS	non-negative integer	`30000`	Especifica a quantidade de tempo, em milissegundos, a ser aguardada para estabelecer uma única conexão de soquete TCP com o servidor antes de gerar um erro. Especificar `0` significa que seu aplicação define um tempo limite de soquete infinito ao estabelecer um soquete.
directConnection	booleano	`false`	Especifica se todas as operações devem ser forçadas a serem despachadas para o host especificado no URI de conexão.
enableUtf8Validation	booleano	`true`	A especificação do `true` habilita a validação UTF-8 para a conexão. O MongoDB apresenta um erro quando tenta serializar dados de string que contêm caracteres UTF-8 inválidos para BSON. Isso se aplica tanto às chaves quanto aos valores do documento; essa validação adiciona sobrecarga de processamento. A especificação de `false` desativa a validação de UTF-8 para a conexão. O MongoDB não exibe erros quando os dados contêm dados UTF-8 inválidos. Se você desativar a validação, seu aplicativo evitará a sobrecarga de processamento da validação. Editar dados enquanto a validação está desabilitada pode resultar na perda de dados. A desativação da validação UTF-8 é uma solução temporária para consultar ou exportar dados apenas. Para saber mais sobre os caracteres UTF-8, consulte UTF-8 na Wikipedia.
heartbeatFrequencyMS	inteiro maior ou igual a 500	`null`	Especifica o intervalo, em milissegundos, entre verificações regulares de monitoramento do servidor.
loadBalanced	booleano	`null`	Especifica se o driver está se conectando a um balancer de carga.
localThresholdMS	non-negative integer	`15`	Especifica o tamanho da janela de latência, em milissegundos, no tempo de viagem de ida e volta para selecionar entre os servidores adequados. Especificar `0` significa não esperar, ou seja, o servidor mais rápido disponível.
maxIdleTimeMS	non-negative integer	`0`	Especifica a quantidade de tempo, em milissegundos, que uma conexão pode ficar ociosa antes de ser fechada. Especificar `0` significa que não há mínimo.
maxPoolSize	non-negative integer	`100`	Especifica o número máximo de clientes ou conexões que o driver pode criar em seu repositório de conexões. Esta contagem inclui conexões em uso.
maxConnecting	non-negative integer	`2`	Especifica o número máximo de conexões que um conjunto de conexões do driver pode estar estabelecendo simultaneamente.
maxStalenessSeconds	-1, ou um número inteiro maior ou igual a 90	`null`	Especifica o atraso máximo de replicação, em tempo de relógio de parede, que um secundário pode enfrentar e ainda ser qualificado para seleção de servidor. Especificar `-1` significa que não há máximo.
minPoolSize	non-negative integer	`0`	Especifica o número de conexões que o driver cria e mantém no repositório de conexões mesmo quando nenhuma operação está ocorrendo.Esta contagem inclui conexões em uso.
proxyHost	string	`null`	Especifica o endereço IPv5 de proxy SOCKS4, endereço IPv6 ou nome de domínio.
proxyPort	non-negative integer	`null`	Especifica o número da porta TCP do servidor proxy SOCKS5. Se você definir a opção `proxyHost` , o valor dessa opção será padronizado como `1080`.
proxyUsername	string	`null`	Especifica o nome de usuário para autenticação no servidor proxy SOCKS5. Se você definir essa opção como uma string de comprimento zero, o driver a ignorará.
proxyPassword	string	`null`	Especifica a senha para autenticação no servidor proxy SOCKS5. Se você definir essa opção como uma string de comprimento zero, o driver a ignorará.
readConcernLevel	string	`null`	Especifica a preocupação de leitura padrão para o cliente. Consulte a página Preocupação de leitura para obter mais informações.
readPreference	string	`"primary"`	Especifica a preferência de leitura padrão para o cliente (excluindo tags). Consulte preferência de leitura para obter mais informações.
readPreferenceTags	chave separada por vírgula:pares de valores, por exemplo, "dc:ny,rack:1" e "dc:ny podem ser especificados várias vezes, cada instância desta chave é um conjunto de tags separado	`null`	Especifica as tags de preferência de leitura padrão para o cliente. Esta opção é válida somente se o modo de preferência de leitura não for primário. O condutor utiliza a ordem das etiquetas no URI como ordem para a preferência de leitura.
replicaSet	string	`null`	Especifica o nome do conjunto de réplicas ao qual se conectar.
retryReads	booleano	`true`	Permite leituras que podem ser repetidas.
retryWrites	booleano	`true`	Habilita gravações que podem ser tentadas novamente.
serverMonitoringMode	`auto`, `stream` , `poll`	`auto`	Especifica o modo de monitoramento usado pelos monitores do driver. Quando essa opção é definida como `auto`, o modo de monitoramento é determinado pelo ambiente em que o driver está sendo executado. O driver usa o modo de sondagem em ambientes de função como serviço (FaaS) e o modo de streaming em outros ambientes.
serverSelectionTimeoutMS	non-negative integer	`30000`	Especifica o tempo limite, em milissegundos, para bloquear a seleção do servidor antes de gerar um erro.
socketTimeoutMS	non-negative integer	`0`	Especifica a quantidade de tempo em milissegundos gasto tentando enviar ou receber em um soquete antes do tempo limite. Especificar `0` significa que seu aplicação define um tempo limite de soquete infinito ao estabelecer um soquete.
srvMaxHosts	non-negative integer	`0`	Especifica o número máximo de resultados SRV a serem selecionados aleatoriamente ao preencher inicialmente a lista de sementes ou, durante a sondagem SRV, adicionar novos hosts à topologia.
srvServiceName	um nome de serviço SRV válido de acordo com RFC 6335	`"mongodb"`	Especifica o nome do serviço a ser usado para a pesquisa de SRV na descoberta inicial da lista de sementes de DNS.
ssl	booleano	`false`	O `ssl` é um alias para a opção `tls`.
tls	booleano	`false`	Especifica se o TLS é necessário para conexões com o servidor. Usar `srvServiceName` de `"mongodb+srv"` ou especificar outras opções com prefixo `tls` define implicitamente o valor de `tls` como `true`.
tlsAllowInvalidCertificates	booleano	`false`	Especifica se o driver gera um erro quando o certificado TLS do servidor é inválido. Defina esta opção como `true` somente para fins de teste.
tlsAllowInvalidHostnames	booleano	`false`	Especifica se o driver gera um erro quando há uma incompatibilidade entre o nome de host do servidor e o nome de host especificado pelo certificado TLS. Defina esta opção como `true` apenas para fins de teste.
tlsCAFile	string	`null`	Especifica o caminho para um arquivo com uma única autoridade de certificação ou um pacote de autoridades de certificação em que se deve confiar ao fazer uma conexão TLS. Para saber mais sobre como definir essa opção de conexão, consulte a seção Fornecer caminhos de arquivo de certificado do guia TLS.
tlsCertificateKeyFile	string	`null`	Especifica o caminho para o arquivo de certificado do cliente ou o arquivo de chave privada do cliente. Se você precisar de ambos, deverá concatenar os arquivos. Para saber mais sobre como definir essa opção de conexão, consulte a seção Fornecer caminhos de arquivo de certificado do guia TLS.
tlsCertificateKeyFilePassword	string	`null`	Especifica a senha para descriptografar a chave privada do cliente a ser usada para conexões TLS.
tlsInsecure	booleano	`false`	Especifica para relaxar as restrições de TLS o máximo possível, como permitir certificados inválidos ou incompatibilidades de nome de host. Defina esta opção como `true` somente para fins de teste.
waitQueueTimeoutMS	non-negative integer	`0`	Especifica o tempo, em milissegundos, gasto tentando verificar uma conexão do repositório de conexão de um servidor antes do tempo limite. `0` indica que não há tempo-limite.
zlibCompressionLevel	inteiro entre `-1` e `9` (inclusive)	`-1`	Especifica o nível de compressão ao usar zlib para comprimir mensagens de protocolo de fio. `-1` significa o nível padrão, `0` significa nenhuma compressão, `1` significa a velocidade mais rápida e `9` significa a melhor compressão. Consulte Compressão de rede para obter mais informações.

Opções de tempo limite de conexão

Contexto	Descrição
connectTimeoutMS	`connectTimeoutMS` é uma opção de conexão que define o tempo, em milésimos de segundo, para que uma conexão individual do seu pool de conexões estabeleça uma conexão TCP com o MongoDB Server antes de atingir o tempo limite. Para modificar o tempo permitido para MongoClient.connect estabelecer uma conexão com um MongoDB Server, utilize a opção `serverSelectionTimeoutMS`. Padrão: 30000
socketTimeoutMS	`socketTimeoutMS` especifica o tempo que o condutor aguarda uma tomada inativa antes de a fechar. O valor padrão é nunca atingir o tempo limite do soquete. Essa opção se aplica somente aos soquetes que já foram conectados.
maxTimeMS	maxTimeMS especifica o tempo máximo que o servidor aguarda a conclusão de uma operação depois que ela chega ao servidor. Se uma operação for executada acima do limite de tempo especificado, ela retornará um erro de tempo limite. Você pode passar o `maxTimeMS` somente para uma operação individual ou para um cursor.

Para especificar as configurações opcionais para seu MongoClient, declare uma ou mais configurações disponíveis no objeto options do construtor como segue:

const client = new MongoClient(uri, {
  connectTimeoutMS: <integer value>,
  socketTimeoutMS: <integer value>
});

Para ver todas as configurações disponíveis, consulte a documentação da API MongoClientOptions.

Para especificar maxTimeMS, passe o método maxTimeMS como uma opção com uma especificação de tempo limite para uma operação que retorna um Cursor:

const Cursor = collection.distinct('my-key', { maxTimeMS: 50 });

Fechar soquetes após a conexão

Se você enfrentar um comportamento de rede inesperado ou se um processo do MongoDB falhar com um erro, talvez você não receba a confirmação de que o driver fechou corretamente o soquete correspondente.

Para garantir que o driver feche corretamente o soquete nesses casos, defina a opção socketTimeoutMS. Quando um processo MongoDB expirar, o driver fechará o soquete. Recomendamos que você selecione um valor de socketTimeoutMS que seja duas a três vezes maior que a duração esperada da operação mais lenta executada pelo seu aplicativo.

Evite que operações de longa duração tornem o servidor lento

Você pode evitar que operações de longa duração reduzam a velocidade do servidor especificando um valor de tempo limite. Você pode encadear o método maxTimeMS() a uma operação que retorna Cursor para definir um tempo limite para uma ação específica.

O exemplo a seguir mostra como você pode encadear o método maxTimeMS() a uma operação que retorna Cursor:

// Execute a find command
await collection
  .find({ $where: "sleep(100) || true" })
  .maxTimeMS(50);

Opção de conexão keepAlive

A opção de conexão keepAlive especifica se deve ser ativado o protocolo de controle de transmissão (TCP) keepalives em um soquete TCP. Se você habilitar o keepalives, o driver verificará se a conexão está ativa enviando pings periódicos para seu sistema do MongoDB . Esta funcionalidade funciona somente se o seu sistema operacional suportar a opção de soquete SO_KEEPALIVE.

A opção keepAliveInitialDelay especifica o número de milésimos de segundo que o condutor espera antes de iniciar uma manutenção.

O lançamento da versão 5.3 do driver desativou essas opções. A partir da versão 6.0 do driver, a opção keepAlive é definida permanentemente como true e a keepAliveInitialDelay é definida como 300.000 milissegundos (300 segundos).

Aviso

Se o firewall ignorar ou descartar as mensagens keepalive, talvez você não consiga identificar conexões perdidas.

Informações adicionais

Para saber mais sobre as opções de conexão que você pode definir em uma MongoClientOptions instância do, consulte MongoClientOptions na documentação da API.

Voltar

Guia de conexão

Comprimir tráfego de rede