Um container pode estar em execução enquanto o PostgreSQL ainda inicializa os arquivos de dados. Se a API tenta conectar nesse intervalo, pode encerrar antes de o banco aceitar conexões. Configure um healthcheck no serviço do banco e faça a API depender do estado saudável.

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: local-dev
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 10
  api:
    build: .
    depends_on:
      db:
        condition: service_healthy

O exemplo usa uma senha para desenvolvimento local. Use a configuração de segredos do ambiente ao implantar. A API deve apontar para db:5432 dentro da rede do Compose.

pg_isready confirma que o servidor aceita conexões. A existência das tabelas e a aplicação das migrações exigem uma etapa própria. Teste também o que a API faz se o banco reiniciar depois da inicialização. A ordem do Compose só resolve a espera no momento de subir os serviços.

Documentação de referência

A prontidão tem mais de uma camada

pg_isready confirma que o servidor PostgreSQL aceita conexões, mas não autentica a aplicação nem garante que o banco certo e o schema esperado estejam prontos. A API pode executar uma verificação própria depois de resolver DNS e abrir uma conexão com suas credenciais. Essa rota deve responder rapidamente e evitar realizar uma consulta pesada a cada sondagem.

depends_on com service_healthy controla a sequência inicial no Compose. Ele não reinicia a API só porque o banco fica indisponível depois, e não substitui o tratamento de falhas de conexão no código. A aplicação precisa aplicar retry com limite e atraso, fechar conexões quebradas e informar readiness de acordo com a política de dependência. Uma indisponibilidade temporária não deve criar um ciclo de reinício sem fim.

Mantenha a configuração local segura

Credenciais de exemplo devem ficar em arquivos ignorados pelo Git ou em variáveis do ambiente. Não reutilize a senha local em produção. Se o serviço publica a porta do banco no host, limite-a a loopback quando só ferramentas locais precisam acessá-la. A rede interna do Compose permite que a API use o nome do serviço e a porta do container.

Confira o healthcheck com banco recém-criado, reinicialização e credencial incorreta. Observe o estado no comando de inspeção do Compose e compare o log da API. Também teste o caminho de migração: readiness pode depender da existência das tabelas, mas a tarefa de migração deve ser uma etapa única e coordenada, não executada por cada réplica simultaneamente.

Uma política de restart do container responde à saída do processo, não ao sucesso do banco. Marcar o serviço como unhealthy também não encerra a API por si só. A aplicação precisa lidar com perda de conexão em runtime e voltar a ficar pronta quando a dependência se recuperar. No Compose, simule o banco parando depois que a API iniciou e acompanhe se as requisições falham de modo controlado, se o processo permanece íntegro e se readiness volta após o banco retornar.