Pular para o conteúdo principal
O Midaz aplica migrações de esquema PostgreSQL por meio de imagens dedicadas de runner (uma para o Ledger, uma para o Tracer), desacopladas dos binários da aplicação. As aplicações não migram na inicialização. Elas sobem contra um esquema que o runner já migrou.

​
Por que um runner dedicado

O runner dedicado tem estas propriedades:
  • As migrações rodam uma vez, como uma etapa separada.
  • A imagem da aplicação não inclui o SQL de migração e não altera o esquema.
  • A imagem do runner roda sob um contexto de segurança reforçado (veja Postura de segurança).

​
Imagens do runner

Cada release inclui duas imagens: As duas imagens compartilham a mesma estrutura:
  • Base: migrate/migrate, em uma versão fixada.
  • Roda como USER 65532:65532 (non-root, independente de UID).
  • Entrypoint em shell POSIX que monta uma DSN a partir de variáveis de ambiente, executa migrate ... up e sai.
  • Não escreve nada em disco. O Postgres controla o progresso das migrações na tabela schema_migrations, então readOnlyRootFilesystem: true é seguro.
O runner do Ledger aplica onboarding primeiro, depois transaction, em uma única invocação. O runner do Tracer aplica seu único banco de dados em uma única passagem.

​
Contrato de ambiente

Cada entrypoint aceita um override de URL pronto ou as variáveis individuais DB_*. O override de URL tem precedência quando definido.

​
Runner do Ledger

​
Runner do Tracer

​
Formato da DSN

Quando o entrypoint monta a DSN a partir das variáveis DB_*, ele produz:
A senha é codificada em percent-encoding para que caracteres reservados de URI (% @ : / ? # & + space [ ]) não quebrem a DSN. O % é codificado primeiro para que escapes já inseridos não sejam codificados duas vezes. O entrypoint imprime marcadores de fase (applying onboarding migrations, applying transaction migrations, applying tracer migrations, migrations complete).

​
Rodar o runner do Ledger manualmente

O Helm chart executa o runner para você. Para rodá-lo manualmente, aponte-o para seus bancos de dados via DB_* (ou *_DATABASE_URL) e rode-o uma vez antes de o ledger iniciar:
O runner sai com 0 em caso de sucesso (incluindo o caso idempotente de no-op) e com código diferente de zero em caso de falha.

​
Deploy no Kubernetes

Em produção, rode cada runner de migração como um Job do Kubernetes (normalmente um PreSync Job do Argo CD ou um hook do Helm) que é concluído antes do rollout da aplicação. O Helm chart já configura isso para você. As seções abaixo cobrem as propriedades que importam se você criar seus próprios manifestos.
O runner migra os bancos de dados apontados pelo seu ambiente, uma vez.

​
Postura de segurança

O runner funciona sob um contexto de segurança de pod reforçado:
  • Non-root: a imagem define USER 65532:65532.
  • Independente de UID: os arquivos de migração pertencem ao root e têm permissão de leitura para todos, então qualquer UID pode lê-los.
  • Seguro para readOnlyRootFilesystem: o migrate não escreve nenhum estado no sistema de arquivos.
A mesma imagem roda sem problemas sob runAsNonRoot: true, readOnlyRootFilesystem: true e capabilities: drop [ALL].

​
TLS

Os entrypoints respeitam o sslmode definido no ambiente (DB_ONBOARDING_SSLMODE, DB_TRANSACTION_SSLMODE ou DB_SSL_MODE), com padrão disable. Recomenda-se que deploys de produção definam require (ou algo mais restritivo). O runner em shell não reproduz a aplicação de TLS em código, a classificação de erros ou a telemetria que as aplicações usam para suas próprias conexões. Você controla o TLS das migrações apenas por meio do sslmode, em troca de um runner mínimo e sem dependências.

​
Convenções e idempotência

  • Pareadas up/down: cada migração tem um arquivo .up.sql e um .down.sql.
  • Idempotente: rodar migrate up quando o esquema já está na versão mais recente é um no-op. Rodar o runner novamente após uma aplicação parcial ou completa é seguro.
  • CLI fixa: as imagens do runner usam uma versão fixada do golang-migrate.

​
Atualizando a partir de versões anteriores

Para adotar o novo modelo:
  1. Baixe o release que inclui as imagens do runner.
  2. No Kubernetes, adicione os Jobs midaz-ledger-migrations e midaz-tracer-migrations ao seu pipeline de deploy para que rodem antes do rollout da aplicação. Se você usa o Helm chart oficial, isso já é feito para você.

​
Páginas relacionadas