Especificar opções de conexão

Visão geral

Esta seção descreve as opções de conexão e autenticação do MongoDB disponíveis no driver Ruby. Você pode configurar sua conexão usando o URI de conexão (também chamado de string de conexão) ou passando argumentos para o construtor Mongo::Client.

Como utilizar o URI de conexão

Se você passar um URI de conexão para o construtor Mongo::Client, poderá incluir opções de conexão na cadeia de caracteres como pares <name>=<value>. No exemplo a seguir, o URI de conexão contém a opção connectTimeoutMS com um valor de 60000 e a opção tls com um valor de true:

uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true"client = Mongo::Client.new(uri)

Usando um Mongo::Client

Você pode passar as opções de conexão como argumentos para o construtor Mongo::Client em vez de incluí-las em seu URI de conexão. Ao configurar sua conexão dessa forma, é mais fácil para você alterar as configurações no tempo de execução e detectar erros durante a compilação. O exemplo seguinte mostra como utilizar o construtor Mongo::Client para configurar opções de conexão:

uri = "mongodb://<hostname>:<port>"client = Mongo::Client.new(uri, connect_timeout: 60000, ssl: true)

Opções de conexão

As seções a seguir descrevem as opções de conexão disponíveis no driver Ruby.

Compactação de rede

Opção de conexão	Descrição
:compressors	Uma lista de compressores em potencial para usar, em ordem de preferência. O driver escolhe o primeiro compressor que também é compatível com o servidor. Atualmente, o driver só oferece suporte a `zstd`, `snappy` e `zlib`. Tipo de dados: `Array<String>` Padrão: nenhum Exemplo de cliente: `compressors: ['snappy', 'zstd', 'zlib']` Exemplo de URI de conexão: `compressors=snappy,zstd,zlib`
:zlib_compression_level	O nível de compactação zlib a ser usado, se estiver usando compactação. Esta opção aceita um valor inteiro entre `-1` e `9`: - -1: o zlib usa seu nível de compactação padrão (geralmente `6`). - 0: sem compactação. - 1: velocidade mais rápida, mas menor compactação. - 9: melhor compactação, mas velocidade mais lenta. Para obter mais informações, consulte a documentação do módulo zlib do Ruby. Tipo de dados: `Integer` Padrão: `None` Exemplo de cliente: `zlib_compression_level: 3` Exemplo de URI de conexão: `zlibCompressionLevel=3`

Opção de conexão

Descrição

:compressors

Uma lista de compressores em potencial para usar, em ordem de preferência. O driver escolhe o primeiro compressor que também é compatível com o servidor. Atualmente, o driver só oferece suporte a zstd, snappy e zlib.

Tipo de dados: Array<String>
Padrão: nenhum
Exemplo de cliente: compressors: ['snappy', 'zstd', 'zlib']
Exemplo de URI de conexão: compressors=snappy,zstd,zlib

:zlib_compression_level

O nível de compactação zlib a ser usado, se estiver usando compactação. Esta opção aceita um valor inteiro entre -1 e 9:

- -1: o zlib usa seu nível de compactação padrão (geralmente 6).
- 0: sem compactação.
- 1: velocidade mais rápida, mas menor compactação.
- 9: melhor compactação, mas velocidade mais lenta.

Para obter mais informações, consulte a documentação do módulo zlib do Ruby.

Tipo de dados: Integer
Padrão: None
Exemplo de cliente: zlib_compression_level: 3
Exemplo de URI de conexão: zlibCompressionLevel=3

Tempo limite

Opção de conexão	Descrição
:connect_timeout	O número de segundos para aguardar para estabelecer uma conexão de soquete antes de gerar uma exceção. Esse tempo limite também é usado para resolução de registro DNS SRV. `nil` e `0` significam nenhum tempo limite. A criação do cliente falhará com um erro se um valor de tempo limite inválido for passado (como um valor negativo ou um valor não numérico). Tipo de dados: `Float` Padrão: `10.0` Exemplo de cliente: `connect_timeout: 10.0` Exemplo de URI de conexão: `connectTimeoutMS=10000`
:timeout_ms	O número de milissegundos para aguardar a execução de uma operação antes de gerar uma exceção. `0` significa que não há tempo-limite. A criação do cliente falhará com um erro se um valor de tempo limite inválido for passado (como um valor negativo ou um valor não numérico). Tipo de dados: `Integer` Padrão: nenhum Exemplo de cliente: `timeout_ms: 5000` Exemplo de URI de conexão: `timeoutMS=5000`

Opção de conexão

Descrição

:connect_timeout

O número de segundos para aguardar para estabelecer uma conexão de soquete antes de gerar uma exceção. Esse tempo limite também é usado para resolução de registro DNS SRV.

nil e 0 significam nenhum tempo limite. A criação do cliente falhará com um erro se um valor de tempo limite inválido for passado (como um valor negativo ou um valor não numérico).

Tipo de dados: Float
Padrão: 10.0
Exemplo de cliente: connect_timeout: 10.0
Exemplo de URI de conexão: connectTimeoutMS=10000

:timeout_ms

O número de milissegundos para aguardar a execução de uma operação antes de gerar uma exceção.

0 significa que não há tempo-limite. A criação do cliente falhará com um erro se um valor de tempo limite inválido for passado (como um valor negativo ou um valor não numérico).

Tipo de dados: Integer
Padrão: nenhum
Exemplo de cliente: timeout_ms: 5000
Exemplo de URI de conexão: timeoutMS=5000

Seleção do Servidor

Opção de conexão	Descrição
:load_balanced	Se deve esperar para se conectar a um balanceador de carga. Tipo de dados: `Boolean` Padrão: `false` Exemplo de cliente: `load_balanced: { true }` Exemplo de URI de conexão: N/A
:server_monitoring_mode	O protocolo de monitoramento do servidor a ser usado. 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), como o Amazon Web Services Lambda, e o modo de streaming em outros ambientes. Tipo de dados: `Symbol` Padrão: `:auto` Exemplo de cliente: `server_monitoring_mode: :poll` Exemplo de URI de conexão: `serverMonitoringMode=poll`
:server_selection_timeout	A quantidade máxima de tempo, em segundos, que o driver aguarda o sucesso da seleção do servidor antes de lançar uma exceção. Tipo de dados: `Integer` Padrão: `30` Exemplo de cliente: `server_selection_timeout: 30` Exemplo de URI de conexão: `serverSelectionTimeoutMS=30000`

Para obter mais informações sobre a seleção de servidor, consulte o guia Seleção de Servidor.

Autenticação

Opção de conexão	Descrição
:auth_mech	O mecanismo que o driver Ruby usa para autenticar o aplicativo. Tipo de dados: `Symbol` Padrão: `:scram256` `nil` se as credenciais do usuário não forem fornecidas. Exemplo de cliente: `auth_mech: :scram256` Exemplo de URI de conexão: `authMechanism=SCRAM-SHA-256`
:auth_mech_properties	Opções específicas para o mecanismo de autenticação. Esta opção não é necessária para todos os mecanismos de autenticação. Tipo de dados: `Hash` Padrão: Ao usar o mecanismo de autenticação GSSAPI, as propriedades padrão são `{service_name: "mongodb"}`. Caso contrário, o padrão é `nil`. Exemplo de cliente: `auth_mech_properties: {aws_session_token: '12345'}` Exemplo de URI de conexão: `authMechanismProperties=AWS_SESSION_TOKEN:12345`
:auth_source	O banco de dados para autenticar. Tipo de dados: `String` Padrão: `admin`, se as credenciais forem fornecidas Exemplo de cliente: `auth_source: admin` Exemplo de URI de conexão: `authSource=admin`
: user	O nome de usuário para autenticação. Quando essa opção é incluída em um URI de conexão, você deve codificá-la em porcentagem. Tipo de dados: `String` Padrão: nenhum Exemplo de cliente: `user: my+user` Exemplo de URI de conexão: `username=my+user`
:password	A senha para autenticação. Quando essa opção é incluída em um URI de conexão, você deve codificá-la em porcentagem. Tipo de dados: `String` Padrão: nenhum Exemplo de cliente: `password: strong+password` Exemplo de URI de conexão: `password=strong+password`

Operações de leitura e escrita

Opção de conexão	Descrição
:replica_set	Especifica o nome do conjunto de réplicas ao qual se conectar. Tipo de dados: `String` Padrão: nenhum Exemplo de cliente: `replica_set: 'myRS'` Exemplo de URI de conexão: `replicaSet=myRS`
:direct_connection	Se deve conectar diretamente ao hospedar especificado Tipo de dados: `Boolean` Padrão: `false` Exemplo de cliente: `direct_connection: true` Exemplo de URI de conexão: `directConnection=true`
:enable_overload_tartargeting	Se o driver desprioriza um servidor que retorna um erro de sobrecarga, reduzindo a probabilidade de tentar novamente no mesmo servidor sobrecarregado. Tipo de dados: `Boolean` Padrão: `false` Exemplo de cliente: `enable_overload_retargeting: true` Exemplo de URI de conexão: `enableOverloadRetargeting=true`
:max_adaptive_retry	O número máximo de tentativas a serem feitas quando o driver encontrar erros de sobrecarga. Tipo de dados: `Integer` Padrão: `2` Exemplo de cliente: `max_adaptive_retries: 3` Exemplo de URI de conexão: `maxAdaptiveRetries=3`
:read	As opções de preferência de leitura. Para obter mais informações, consulte preferência de leitura no manual do MongoDB Server. Tipo de dados: `Hash` Padrão: `{ mode: :primary }` Exemplo de cliente: `read: { mode: :primary }` Exemplo de URI de conexão: `readPreference=primary`
:read_concern	Especifica as opções de read concern. Para obter mais informações, consulte read concern no manual do MongoDB Server. Tipo de dados: `Hash` Padrão: nenhum Exemplo de cliente: `read: { level: :majority }` Exemplo de URI de conexão: `readConcern=majority`
:write_concern	Especifica a write concern do cliente. Para obter mais informações, consulte Write Concern no manual do MongoDB Server. Tipo de dados: `Hash` Padrão: `write_concern: { w: 1 }` Exemplo de cliente: `write_concern: { w: 2 }` Exemplo de URI de conexão: `w=2`
:local_threshold	A janela de latência, em segundos, para a elegibilidade de um nó do conjunto de réplicas. Se o ping de ida e volta de um nó demorar mais do que o tempo de ping de ida e volta do servidor mais rápido mais esse valor, o servidor não estará qualificado para seleção. Tipo de dados: `Float` Padrão: `0.015` Exemplo de cliente: `local_threshold: 0.020` Exemplo de URI de conexão: `localThresholdMS=20`

Pool de Conexões

Opção de conexão	Descrição
:max_pool_size	O número máximo de conexões simultâneas que o pool mantém. Se o número de conexões em uso com um servidor atingir o valor especificado, a próxima solicitação para esse servidor aguardará até que uma conexão fique disponível. Definir esta opção como `0` cria um pool de conexões ilimitado. Tipo de dados: `Integer` Padrão: `100` Exemplo de cliente: `max_pool_size: 100` Exemplo de URI de conexão: `maxPoolSize=100`
:max_connecting	O número máximo de conexões que cada pool pode estabelecer simultaneamente. Tipo de dados: `Integer` Padrão: `2` Exemplo de cliente: `max_connecting: 2` Exemplo de URI de conexão: `maxConnecting=2`
:min_pool_size	O número mínimo de conexões simultâneas que o pool mantém. Tipo de dados: `Integer` Padrão: `0` Exemplo de cliente: `min_pool_size: 1` Exemplo de URI de conexão: `minPoolSize=1`
:max_idle_time	O número máximo de segundos que uma conexão pode permanecer ociosa no pool. Tipo de dados: `Integer` Padrão: `0` (sem limite) Exemplo de cliente: `max_idle_time: 10` Exemplo de URI de conexão: `maxIdleTimeMS=10000`

Para obter mais informações sobre pools de conexões, consulte o guia pools de conexões.

Observação

Descarte de carga no Intelligent Gerenciamento de Carga de Trabalho (IWM)

Se erros com os rótulos SystemOverloadedError ou RetryableError estiverem causando falhas em seu aplicativo ou aparecendo em seus logs de aplicativo, o Load Shedding pode estar ativo em seu cluster e seu driver pode não ter sido atualizado para uma versão que o suporte. Recomendamos atualizar seu driver do MongoDB para Ruby para a versão 2.24 ou posterior. Se você continuar a ver esses erros após a atualização, poderá resolvê-los por meio de alterações no lado do servidor, como revisar sua configuração de Load Shedding, ou por meio de alterações no lado do aplicativo, como implementar tratamento de erros personalizado ou limitação de solicitação do lado do cliente. Dependendo da sua situação, as alterações no lado do aplicativo podem ser preferíveis ou necessárias.

O Load Shedding é um recurso do IWM e ajuda a gerenciar a carga do servidor rejeitando operações em excesso durante a sobrecarga sustentada. Este recurso está disponível no MongoDB 9.0 e posterior.

Para obter mais informações sobre IWM ou como lidar com erros de sobrecarga, consulte a página Gerenciamento inteligente de carga de trabalho ou a página Erros de sobrecarga na documentação do Atlas.

Documentação da API

Para obter mais informações sobre as opções de Mongo::Client para o driver Ruby, consulte a documentação da API do Mongo::Client.

Voltar

Escolha um destino de conexão

Comprimir tráfego de rede