Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

Especificar opções de conexão

Visão geral

Esta página descreve as opções de conexão e autenticação MongoDB disponíveis na biblioteca PHP.

Definir opções de conexão

Você pode configurar sua conexão especificando opções no URI de conexão ou passando-as para o construtor MongoDB\Client .

Como utilizar o URI de conexão

Se você passar um URI de conexão para o construtor MongoDB\Client , poderá incluir opções de conexão no URI como pares <name>=<value> . No exemplo a seguir, o URI de conexão define a opção tls como true e a opção tlsCertificateKeyFile como /path/to/file.pem:

// Replace the placeholders with your actual hostname, port, and path to the certificate key file$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/file.pem';
// Create a MongoDB client$client = new MongoDB\Client($uri);

Usando um objeto MongoDB\Client

Você pode passar as opções de conexão para o construtor MongoDB\Client em vez de incluí-las em seu URI de conexão.

O exemplo seguinte mostra como utilizar o parâmetro $uriOptions do construtor MongoDB\Client para configurar opções de conexão:

// Replace the placeholders with your actual hostname and port$uri = 'mongodb://<hostname>:<port>/';
// Set the connection options// Replace the placeholder with the actual path to the certificate key file$uriOptions = [    'tls' => true,    'tlsCertificateKeyFile' => '/path/to/file.pem',];
// Create a MongoDB client with the URI and options$client = new Client($uri, $uriOptions);

Observação

Se você especificar uma opção no parâmetro $uriOptions e no URI de conexão, o valor em $uriOptions terá precedência.

Opções de URI de conexão

As seções a seguir descrevem as opções que você pode definir para sua conexão com o MongoDB. Cada opção de conexão está vinculada à sua entrada correspondente no manual do MongoDB Server .

Importante

Codificação percentual

Se o valor de uma opção de conexão contiver caracteres especiais, você deverá codificar percentualmente o valor antes de incluí-lo no URI de conexão. Você pode usar o método rawurlencode() para codificar esses valores de acordo com a sintaxe URI especificada em RFC 3986.

Não codifique por cento as opções de conexão ao incluí-las no parâmetro $uriOptions .

Para saber mais, consulte os seguintes recursos:

Opções de conjunto de réplicas

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

Tipo de dados: bool
Exemplo de cliente MongoDB: $uriOptions = ['directConnection' => true];
Exemplo de URI de conexão: directConnection=true

Tipo de dados: string
Exemplo de cliente MongoDB: $uriOptions = ['replicaSet' => 'replicaSetName'];
Exemplo de URI de conexão: replicaSet=replicaSetName

Opções de conexão

Opções de TLS

Para saber mais sobre as opções de TLS disponíveis na biblioteca PHP, consulte a página TLS .

Opções de tempo limite

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

Tipo de dados: int
Exemplo de cliente MongoDB: $uriOptions = ['connectTimeoutMS' => 2000];
Exemplo de URI de conexão: connectTimeoutMS=2000

Tipo de dados: int
Exemplo de cliente MongoDB: $uriOptions = ['socketTimeoutMS' => 20000];
Exemplo de URI de conexão: socketTimeoutMS=20000

Opções de compressão

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

Tipo de dados: string
Exemplo de cliente MongoDB: $uriOptions = ['compressors' => 'snappy,zstd,zlib'];
Exemplo de URI de conexão: compressors=snappy,zstd,zlib

Tipo de dados: int
Exemplo de cliente MongoDB: $uriOptions = ['zlibCompressionLevel' => 3];
Exemplo de URI de conexão: zlibCompressionLevel=3

Opções de write concern

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

Tipo de dados: string
Exemplo de cliente MongoDB: $uriOptions = ['w' => 'majority'];
Exemplo de URI de conexão: w=majority

Tipo de dados: int
Exemplo de cliente MongoDB: $uriOptions = ['wTimeoutMS' => 10000];
Exemplo de URI de conexão: wTimeoutMS=10000

Tipo de dados: bool
Exemplo de cliente MongoDB: $uriOptions = ['journal' => true];
Exemplo de URI de conexão: journal=true

Opções de read concern

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

Tipo de dados: string
Exemplo de cliente MongoDB: $uriOptions = ['readConcernLevel' => 'majority'];
Exemplo de URI de conexão: readConcernLevel=majority

Opções de read preference

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

Tipo de dados: MongoDB\driver\ReadPreference
Exemplo de MongoDB\cliente: $uriOptions = ['readPreference' => 'secondaryPreferred'];
Exemplo de URI de conexão: readPreference=secondaryPreferred

Tipo de dados: int
Exemplo de cliente MongoDB: $uriOptions = ['maxStalenessSeconds' => 30];
Exemplo de URI de conexão: maxStalenessSeconds=30

Tipo de dados: array
Exemplo de MongoDB\cliente:

$uriOptions = [    'readPreferenceTags' => [        ['dc' => 'ny', 'rack' => 'r1'],        [],    ],];

Exemplo de URI de conexão: readPreferenceTags=dc:ny,rack:r1&readPreferenceTags=

Opções de autenticação

Para saber mais sobre as opções de autenticação disponíveis na biblioteca PHP, consulte Mecanismos de autenticação.

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

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

Tipo de dados: int
Exemplo de cliente MongoDB: $uriOptions = ['localThresholdMS' => 20];
Exemplo de URI de conexão: localThresholdMS=20

Tipo de dados: int
Exemplo de cliente MongoDB: $uriOptions = ['serverSelectionTimeoutMS' => 5000];
Exemplo de URI de conexão: serverSelectionTimeoutMS=5000

Tipo de dados: bool
Exemplo de cliente MongoDB: $uriOptions = ['serverSelectionTryOnce' => false];
Exemplo de URI de conexão: serverSelectionTryOnce=false

Tipo de dados: int
Exemplo de cliente MongoDB: $uriOptions = ['heartbeatFrequencyMS' => 30000];
Exemplo de URI de conexão: heartbeatFrequencyMS=30000

Tipo de dados: int
Exemplo de cliente MongoDB: $uriOptions = ['socketCheckIntervalMS' => 4000];
Exemplo de URI de conexão: socketCheckIntervalMS=4000

Configurações diversas

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

Tipo de dados: string
Exemplo de cliente MongoDB: $uriOptions = ['appName' => 'myApp'];
Exemplo de URI de conexão: appName=myApp

Tipo de dados: bool
Exemplo de cliente MongoDB: $uriOptions = ['retryReads' => false];
Exemplo de URI de conexão: retryReads=false

Tipo de dados: bool
Exemplo de cliente MongoDB: $uriOptions = ['retryWrites' => false];
Exemplo de URI de conexão: retryWrites=false

Tipo de dados: bool
Exemplo de cliente MongoDB: $uriOptions = ['loadBalanced' => true];
Exemplo de URI de conexão: loadBalanced=true

Tipo de dados: int
Exemplo de cliente MongoDB: $uriOptions = ['srvMaxHosts' => 5];
Exemplo de URI de conexão: srvMaxHosts=5

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 sua biblioteca MongoDB PHP para a versão 2.3 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 a classe MongoDB\Client , consulte a seguinte documentação da API da biblioteca PHP:

Para obter mais informações sobre a classe MongoDB\Driver\ReadPreference , consulte a seguinte documentação da API de extensão PHP:

Voltar
Escolha um destino de conexão
Próximo
Stable API
Avalie esta página

Nesta página