Parâmetros na Connection String | MongoDB | Banco de Dados
- Parâmetros na Connection String | MongoDB | Banco de Dados
Configurações de conexão no MongoDB
warning
Cuidado com o sufixo após o mongodb
| URI | Correto? | Quando usar |
|---|---|---|
mongodb://localhost:27017/?maxPoolSize=50 | Sim | conexão direta/local |
mongodb://host1:27017,host2:27017/?replicaSet=rs0&maxPoolSize=50 | Sim | replica set com hosts informados manualmente |
mongodb+srv://cluster.mongodb.net/?maxPoolSize=50 | Sim | cluster com DNS Seed List |
mongodb+srv://localhost:27017 | Não | inválido para esse propósito |
As opções de conexão no MongoDB são passadas como pares nome=valor na URI, separadas por &. A documentação oficial recomenda usar mongodb+srv:// quando possível; já mongodb:// exige informar manualmente os hosts do cluster. (MongoDB)
Exemplo
mongodb+srv://usuario:senha@cluster.mongodb.net/appdb?retryWrites=true&w=majority&appName=MinhaApi
Tabela das principais opções
| Opção | Para que serve | Exemplo | Observação prática |
|---|---|---|---|
replicaSet | Informa o nome do replica set | replicaSet=rs0 | Importante para comportamento consistente ao conectar em replica set. (MongoDB) |
directConnection | Força conexão direta com um único host | directConnection=true | Com true, o cliente não descobre os outros membros; útil em dev/teste, especialmente com Docker. (MongoDB) |
tls | Ativa/desativa TLS/SSL | tls=true | Em URI SRV, o padrão é true; em URI padrão, o padrão é false. ssl é equivalente. (MongoDB) |
ssl | Equivalente a tls | ssl=true | Mantido por compatibilidade. (MongoDB) |
authSource | Define em qual banco as credenciais serão validadas | authSource=admin | Se não for informado, usa defaultauthdb ou admin, dependendo do caso. (MongoDB) |
authMechanism | Define o mecanismo de autenticação | authMechanism=SCRAM-SHA-256 | O padrão é SCRAM-SHA-256; pode haver fallback para SCRAM-SHA-1. (MongoDB) |
readPreference | Define de qual nó as leituras podem sair | readPreference=secondary | O padrão é primary. Em transações com leitura, deve ser primary. (MongoDB) |
readPreferenceTags | Filtra leitura por tags dos nós | readPreferenceTags=dc:sp,rack:r1 | Usado junto com readPreference, normalmente em ambientes distribuídos. (MongoDB) |
maxStalenessSeconds | Limita o atraso máximo aceitável de um secundário | maxStalenessSeconds=120 | Serve para evitar leitura em secundário muito defasado. (MongoDB) |
w | Define o write concern | w=majority | majority é a opção mais comum para maior durabilidade. Atlas aplica majority por padrão se você não informar write concern. (MongoDB) |
journal | Exige confirmação de gravação no journal | journal=true | Aumenta durabilidade da escrita. (MongoDB) |
wtimeoutMS | Tempo limite do write concern | wtimeoutMS=5000 | Está deprecated; a documentação manda usar timeoutMS no lugar. (MongoDB) |
retryWrites | Habilita retry automático de escritas elegíveis | retryWrites=true | Drivers oficiais usam true por padrão. Muito importante para failover/eleições. (MongoDB) |
retryReads | Habilita retry automático de leituras elegíveis | retryReads=true | Drivers oficiais usam true por padrão. (MongoDB) |
connectTimeoutMS | Tempo máximo para estabelecer conexão | connectTimeoutMS=10000 | O padrão geral é 10s, mas pode variar por driver. (MongoDB) |
socketTimeoutMS | Tempo máximo para envio/recebimento em socket | socketTimeoutMS=30000 | O padrão costuma ser sem timeout, mas pode variar por driver. (MongoDB) |
serverSelectionTimeoutMS | Tempo máximo para o driver encontrar um servidor adequado | serverSelectionTimeoutMS=30000 | Muito útil para ajustar comportamento em quedas e failover. O padrão é 30s. (MongoDB) |
localThresholdMS | Janela de latência aceitável entre nós elegíveis | localThresholdMS=15 | Ajuda o driver a decidir entre múltiplos nós válidos. Padrão: 15 ms. (MongoDB) |
heartbeatFrequencyMS | Intervalo de verificação do estado do cluster | heartbeatFrequencyMS=10000 | Controla a frequência com que o driver monitora os nós. (MongoDB) |
maxPoolSize | Máximo de conexões no pool | maxPoolSize=100 | Padrão: 100. Importante para APIs com concorrência. (MongoDB) |
minPoolSize | Mínimo de conexões mantidas no pool | minPoolSize=10 | Evita pool “frio” em apps com tráfego constante. (MongoDB) |
maxIdleTimeMS | Tempo máximo que uma conexão pode ficar ociosa no pool | maxIdleTimeMS=60000 | Nem todo driver suporta. (MongoDB) |
waitQueueTimeoutMS | Tempo máximo que uma thread espera por conexão livre no pool | waitQueueTimeoutMS=5000 | Ajuda a controlar contenção no pool. (MongoDB) |
compressors | Habilita compressão de tráfego entre cliente e servidor | compressors=zstd,snappy | Pode usar snappy, zlib e zstd. Só funciona se cliente e servidor compartilharem compressor. (MongoDB) |
zlibCompressionLevel | Nível de compressão do zlib | zlibCompressionLevel=6 | Quanto maior, maior compressão e menor velocidade. (MongoDB) |
appName | Define nome da aplicação na conexão | appName=MinhaApi | Aparece em logs, profiler e currentOp, ótimo para observabilidade. (MongoDB) |
loadBalanced | Indica conexão via load balancer | loadBalanced=true | Só pode ser usado em cenários específicos. (MongoDB) |
As opções que você mais vai usar no dia a dia
| Cenário | Opções mais comuns |
|---|---|
| Conexão básica segura | tls=true, authSource=admin, appName=MinhaApi |
| Replica set em produção | replicaSet=rs0, retryWrites=true, w=majority |
| Leitura em secundário | readPreference=secondary |
| Ajuste de timeout | connectTimeoutMS, socketTimeoutMS, serverSelectionTimeoutMS |
| Ajuste de pool | maxPoolSize, minPoolSize, maxIdleTimeMS |
| Melhor observabilidade | appName=... |
Exemplos prontos
1. Replica set com escrita durável
mongodb://user:senha@db1:27017,db2:27017,db3:27017/?replicaSet=rs0&retryWrites=true&w=majority
2. Atlas com TLS e nome da aplicação
mongodb+srv://user:senha@cluster.mongodb.net/appdb?retryWrites=true&w=majority&appName=MinhaApi
3. Leitura em secundário com limite de atraso
mongodb://user:senha@db1:27017,db2:27017,db3:27017/?replicaSet=rs0&readPreference=secondary&maxStalenessSeconds=120
4. Ajustando pool e timeout
mongodb://user:senha@db1:27017/?maxPoolSize=200&minPoolSize=20&connectTimeoutMS=10000&serverSelectionTimeoutMS=5000
Resumo prático
| Tipo | Opções principais |
|---|---|
| Descoberta do cluster | replicaSet, directConnection |
| Segurança | tls, ssl, authSource, authMechanism |
| Leitura | readPreference, readPreferenceTags, maxStalenessSeconds |
| Escrita | w, journal, retryWrites |
| Timeout | connectTimeoutMS, socketTimeoutMS, serverSelectionTimeoutMS |
| Pool | maxPoolSize, minPoolSize, maxIdleTimeMS, waitQueueTimeoutMS |
| Rede | compressors, zlibCompressionLevel |
| Observabilidade | appName |
Observações importantes
-
Prefira
mongodb+srv://quando possível, porque ele simplifica a descoberta dos hosts do cluster. (MongoDB) -
Em replica set, usar
replicaSet=...ajuda a manter comportamento consistente entre drivers. (MongoDB) -
Para cenários de produção com failover, normalmente a combinação mais forte é:
retryWrites=truew=majority
-
wtimeoutMSestá depreciado; o caminho atual é usartimeoutMS. (MongoDB)