> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrações de banco de dados

> Rode as migrações de esquema PostgreSQL do Midaz Ledger e do Tracer com imagens dedicadas de runner, para que as aplicações subam contra um banco de dados já migrado.

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](#security-posture)).

## Imagens do runner

***

Cada release inclui duas imagens:

| Imagem | Aplica-se a | Bancos de dados |
| - | - | - |
| `midaz-ledger-migrations` | Migrações de onboarding e transaction do Ledger | Dois: `onboarding`, `transaction` |
| `midaz-tracer-migrations` | Esquema do Tracer | Um |

As duas imagens compartilham a mesma estrutura:

* Base: [`migrate/migrate`](https://github.com/golang-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

| Banco de dados | Override de URL | Montada a partir de |
| - | - | - |
| onboarding | `ONBOARDING_DATABASE_URL` | `DB_ONBOARDING_HOST`, `DB_ONBOARDING_PORT` (padrão `5432`), `DB_ONBOARDING_USER`, `DB_ONBOARDING_PASSWORD`, `DB_ONBOARDING_NAME`, `DB_ONBOARDING_SSLMODE` (padrão `disable`) |
| transaction | `TRANSACTION_DATABASE_URL` | `DB_TRANSACTION_*` (mesmo formato) |

### Runner do Tracer

| Override de URL | Montada a partir de |
| - | - |
| `DATABASE_URL` | `DB_HOST`, `DB_PORT` (padrão `5432`), `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `DB_SSL_MODE` (padrão `disable`) |

### Formato da DSN

Quando o entrypoint monta a DSN a partir das variáveis `DB_*`, ele produz:

```text theme={null}
postgres://<user>:<encoded-password>@<host>:<port>/<name>?sslmode=<sslmode>
```

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:

```bash theme={null}
docker run --rm \
  -e DB_ONBOARDING_HOST="postgres.example.com" \
  -e DB_ONBOARDING_PORT=5432 \
  -e DB_ONBOARDING_USER=midaz \
  -e DB_ONBOARDING_PASSWORD="change-me" \
  -e DB_ONBOARDING_NAME=onboarding \
  -e DB_ONBOARDING_SSLMODE=disable \
  -e DB_TRANSACTION_HOST="postgres.example.com" \
  -e DB_TRANSACTION_PORT=5432 \
  -e DB_TRANSACTION_USER=midaz \
  -e DB_TRANSACTION_PASSWORD="change-me" \
  -e DB_TRANSACTION_NAME=transaction \
  -e DB_TRANSACTION_SSLMODE=disable \
  lerianstudio/midaz-ledger-migrations:4.4.0
```

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.

> [!NOTE]
>
> 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

***

* [Instalando o Midaz](https://docs.lerian.studio/pt/products/midaz/midaz-setup.md): as imagens do Midaz e o Helm chart.
* [Atualizando o Midaz](https://docs.lerian.studio/pt/products/midaz/updating-midaz.md): regras de upgrade.
* [Estratégias de deploy](https://docs.lerian.studio/pt/products/midaz/deployment.md): visão geral do deploy BYOC.
* [Variáveis de ambiente do Tracer](https://docs.lerian.studio/pt/products/tracer/tracer-environment-variables.md): referência completa de configuração do Tracer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.