PostgreSQL em Docker: os cinco defaults do contêiner que derrubam a produção

- Leitura
- 7 min
- Tabelas
- 1
- Código
- 3
- Fontes
- 1
Um guia do engenheiro Aleksei Aleinikov mostra por que volumes mal montados, memória compartilhada de 64 MB e um timeout de desligamento de 10 segundos respondem pela maioria dos incidentes com PostgreSQL em contêiner, não o Docker em si.
O Docker não é o vilão, o default é
Rodar PostgreSQL↳PostgreSQL11 conteúdosPostgreSQL via SSL com GolangData · abr 20195 itens legais sobre data types do PostgreSQLData · mar 20195 serviços gratuitos na cloud para bancos de dados PostgresData · fev 2025Ver tudo em Data → dentro de um contêiner leva segundos para subir em desenvolvimento. Em produção, segundo o engenheiro Aleksei Aleinikov, o mesmo compose.yaml copiado de um tutorial pode levar poucos minutos para perder dados. O argumento dele, publicado no próprio blog e replicado pelo Planet PostgreSQL, é direto: a maioria dos incidentes não nasce do Docker↳Docker46 conteúdosE o Docker Swarm? Contextos e motivadores diáriosDevSecOps · ago 2024Automatizando o ambiente de desenvolvimento e testes com DockerDevSecOps · mai 2019MySQL + Adminer + Docker Compose: montando rapidamente um ambiente para usoData · abr 2019Ver tudo em DevSecOps →, nasce do encontro entre os valores padrão do Docker e a forma como o PostgreSQL gerencia memória, checkpoints e arquivos em disco.
Quatro defaults colidem de frente com o motor do Postgres: os 64 MB de /dev/shm, o timeout de 10 segundos antes do SIGKILL, a tag :latest sem versão fixa e o caminho de volume que mudou no PostgreSQL 18. Nenhum desses valores foi pensado para um banco relacional com checkpoints, memória compartilhada dinâmica e um processo de sistema operacional por conexão. Quem sobe Postgres em contêiner sem revisar esses pontos está herdando configuração pensada para serviços stateless.
A mudança estrutural no PostgreSQL 18+
A partir do PostgreSQL 18, a imagem oficial no Docker Hub passou a montar o PGDATA em subdiretórios versionados dentro de /var/lib/postgresql (por exemplo /var/lib/postgresql/18/docker), em vez do caminho fixo /var/lib/postgresql/data usado até a versão 17. O alvo de VOLUME no Dockerfile oficial também mudou, de /var/lib/postgresql/data para /var/lib/postgresql. É uma breaking change estrutural, não cosmética.
A razão, segundo a documentação da imagem oficial citada por Aleinikov, é alinhar o layout do contêiner à convenção pg_ctlcluster do Debian, para que futuras execuções de pg_upgrade --link consigam promover versões major dentro do mesmo diretório pai. Quem apontar um contêiner postgres:18 direto para um volume de PG 17 não vai ver upgrade automático: vai ver o banco simplesmente não inicializar.
O caminho seguro de migração, como descrito na fonte, mantém o volume antigo intocado como rollback instantâneo até confirmar que o novo contêiner subiu corretamente:
docker exec -t pg-prod pg_dumpall -U app_admin > pg17_full.sql
docker compose down
# atualize o compose.yaml para postgres:18.1-bookworm com volume em /var/lib/postgresql
docker compose up -d postgres
docker exec -i pg-prod psql -U app_admin -d postgres < pg17_full.sqlPular o pg_dumpall ou reaproveitar o volume antigo apontando direto para a imagem nova é o erro mais comum do troubleshooting listado na fonte: o contêiner não inicializa, porque não encontra o layout que espera.
Os cinco pontos que viram outage
Aleinikov cataloga cinco armadilhas silenciosas, nenhuma exótica. Elas se repetem porque nascem de omissão: ninguém definiu um valor explícito, e o default do Docker ficou valendo.
/dev/shm de 64 MB
O Docker limita /dev/shm a 64 MB por padrão. O PostgreSQL usa memória compartilhada POSIX para segmentos de memória compartilhada dinâmica (DSM), workers de query paralela e parallel hash join. Sob carga real, a query falha assim:
ERROR: could not resize shared memory segment "/PostgreSQL.12345" to 67108864 bytes: No space left on deviceA correção é declarar shm_size: 1gb (ou 2 a 4 GB em nós maiores) direto no serviço do Compose. É uma linha, mas sem ela toda query paralela vira uma aposta.
O SIGKILL em 10 segundos
Ao rodar docker compose down ou docker stop, o Docker manda SIGTERM e espera só 10 segundos antes de disparar SIGKILL. Se o Postgres tem gigabytes de buffers sujos para gravar num checkpoint, 10 segundos não bastam: o processo é morto no meio do flush, forçando recuperação de WAL lenta na próxima subida. A correção é stop_grace_period: 60s (ou 120s em instâncias com muita escrita), tempo suficiente para o SIGTERM completar o checkpoint.
Healthcheck que mente
Um healthcheck escrito só como pg_isready, sem flags, testa o usuário padrão (root) e o banco padrão, podendo retornar sucesso durante uma reinicialização de initdb, antes do seu banco e do seu usuário existirem de fato. É um falso positivo clássico: o orquestrador acha que o Postgres está pronto, e não está. A versão correta especifica usuário e banco de destino:
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
start_period: 20sExaustão de conexões sem pooler
Diferente de motores baseados em threads, o PostgreSQL cria um processo de sistema operacional dedicado para cada conexão de cliente, de 5 a 10 MB de RAM cada, mais o work_mem de cada query. Uma rajada de 300 funções serverless ou contêineres de worker abrindo conexão ao mesmo tempo basta para o OOM killer do Linux agir dentro de um contêiner com memória limitada.
Volume nomeado, bind mount e permissão
Em host Linux de produção, volume nomeado do Docker sobre NVMe local, ou um bind mount para diretório dedicado com dono 999:999 (UID/GID da imagem Debian), funcionam bem. Compartilhamento via SMB ou CIFS sem garantia estrita de locking está fora de cogitação para PGDATA. Em macOS e Windows, o bind mount direto do host sofre overhead de I/O e corrompe permissão; a recomendação é sempre volume nomeado dentro da VM Linux que o Docker Desktop já usa.
Por que o PgBouncer entra antes de qualquer tuning fino
O modelo de processo por conexão do PostgreSQL não é um detalhe de implementação: é a razão pela qual pooling de conexão é arquitetura, não otimização. Colocar o PgBouncer em modo de pooling por transação na frente do banco, mantendo max_connections do Postgres em algo razoável (100 a 150) enquanto o PgBouncer absorve 500 ou mais conexões de cliente, resolve o problema na camada certa.
Vale notar um detalhe que muda a conta para quem usa ORM: desde o PgBouncer 1.21, prepared statements em nível de protocolo funcionam nativamente em modo transação via MAX_PREPARED_STATEMENTS. Isso tira do Prisma, do SQLAlchemy e do pgx a necessidade de workarounds que eles precisavam manter só para conviver com pooling agressivo.
Trade-off que fica: pooling em modo transação quebra algumas garantias de sessão, como variáveis definidas com SET e LISTEN/NOTIFY persistente entre queries da mesma conexão lógica. Para a maioria das aplicações web isso é irrelevante; para quem depende de estado de sessão no nível do protocolo, a solução é isolar essas conexões específicas fora do pool, não abandonar o PgBouncer.
Dimensionando memória por tamanho de host
O compose.yaml de referência da fonte, pensado para um host de 8 GB, fixa shared_buffers=2GB, effective_cache_size=6GB, work_mem=16MB e max_connections=120, deixando entre metade e três quartos da RAM fora do shared_buffers de propósito: o PostgreSQL depende pesadamente do page cache do Linux, e devolver memória para o SO cachear arquivos é parte do desenho, não desperdício.
| RAM do host | shm_size | shared_buffers | effective_cache_size | work_mem | max_connections |
|---|---|---|---|---|---|
| 2 GB | 512mb | 512MB | 1536MB | 4MB | 60 |
| 4 GB | 1gb | 1GB | 3GB | 8MB | 80 |
| 8 GB | 1gb | 2GB | 6GB | 16MB | 120 |
| 16 GB | 2gb | 4GB | 12GB | 32MB | 150 |
| 32 GB | 4gb | 8GB | 24GB | 64MB | 200 |
Backup não é tar de volume vivo
Mesmo em host com RAID ou ZFS, snapshot de RAID não é disaster recovery. Copiar os arquivos brutos do PGDATA com tar ou rsync enquanto o PostgreSQL está rodando captura páginas cortadas (torn pages) e produz um backup que não restaura.
A fonte propõe dois padrões, e a escolha depende do tamanho do banco e do RPO exigido:
- Dump lógico comprimido, para bancos de até 30-50 GB:
pg_dump -Fcagendado, com verificação de exit status, e envio do arquivo criptografado para armazenamento compatível com S3 (Cloudflare R2, por exemplo) viaresticourclone. - WAL contínuo com PITR, para bancos maiores ou RPO baixo:
pgBackRestouWAL-Grodando numa imagem customizada ou sidecar que compartilha o volume, permitindo restaurar para qualquer segundo exato antes de uma migração ruim.
Nenhum dos dois vale nada sem teste de restore. A recomendação da fonte é mensal: subir um contêiner descartável, restaurar o dump mais recente e conferir contagem de linhas antes de confiar no backup de novo. Backup que nunca foi restaurado é só uma esperança com nome bonito.
Quando Docker não é a resposta certa
Nada do que Aleinikov descreve é motivo para evitar contêiner com Postgres, mas vale marcar onde a conta não fecha. Bancos muito grandes, com I/O sustentado acima do que NVMe local em contêiner entrega, ou cargas que dependem de tuning de filesystem fora do que o Docker expõe, tendem a se beneficiar mais de um host dedicado ou de um serviço gerenciado do que de um contêiner ajustado à mão.
A régua é simples: contêiner com os cinco pontos corrigidos resolve bem a maioria dos times que já usam Docker para o resto da stack e querem Postgres no mesmo fluxo de deploy. Quem está escolhendo a stack do zero, com banco na casa dos terabytes ou SLA muito apertado, deveria colocar RDS, Cloud SQL ou host físico dedicado na mesma planilha de decisão antes de assinar embaixo do compose.yaml.
Fonte: Planet PostgreSQL
Highlights
- PostgreSQL 18+ mudou PGDATA de /var/lib/postgresql/data para /var/lib/postgresql/18/docker, breaking change estrutural
- Defina shm_size: 1gb e stop_grace_period: 60s no Compose para evitar crashes de memória compartilhada e morte abrupta
- PgBouncer 1.21+ suporta prepared statements nativamente em modo transação, eliminando workarounds de ORMs
- Tabela de dimensionamento: 8 GB de RAM = 2 GB shared_buffers, 6 GB effective_cache_size, 120 conexões max
- Nunca faça tar ou rsync de PGDATA vivo; use pg_dump -Fc comprimido ou WAL-G para bancos maiores com PITR
Este artigo foi escrito por Roberto Diniz, colunista de banco de dados. Conteúdo produzido por agente de IA da redação iMasters, sob revisão editorial humana. Saiba como produzimos no expediente.
Postgres 18.7 quebra ABI de extensões ao corrigir CVE crítica
O patch que corrige a CVE-2026-6460 muda a forma como o Postgres interpreta tipos compostos internamente, e isso obriga a recompilar extensões em C, sob risco de elas simplesmente pararem de carregar.













