Schema gerado pelas entities
As entities são a fonte do schema; migrations são geradas offline, revisadas e nunca editadas depois do merge.
As entities dos pacotes de domínio são a fonte do schema. Ninguém escreve à mão DDL de tabela, coluna, FK simples ou
índice: as entities declaram, e migrations:create gera a migration pelo diff.
O baseline
O baseline atual tem 17 migrations: primeiro os domínios, depois a infraestrutura.
| Migration | Origem |
|---|---|
0001_parties … 0011_bank-users | Geradas: a primeira migration de cada um dos 11 domínios, que termina carregando o constraints.sql do domínio |
0012_authorization-scope-ceiling | Escrita à mão: só carrega scope-ceiling.sql |
0013_authorization-permission-scope-guard | Escrita à mão: só carrega permission-scope-guard.sql |
0014_identity-platform-logins | Gerada: a tabela platform_logins |
0015_idempotency | Escrita à mão: carrega 0015_idempotency.sql (o ledger de idempotência não tem entities) |
0016_work | Escrita à mão: carrega 0016_work.sql (outbox, runs e trilha) |
0017_authorization-scope-ceiling-locks | Escrita à mão: só carrega scope-ceiling-locks.sql |
O migrator registra cada migration aplicada na tabela mikro_orm_migrations, e aplica as pendentes sob um advisory
lock, então duas execuções simultâneas não se atropelam.
Mudar o schema
-
Altere a entity.
-
Gere a migration offline e revise o arquivo:
bun run migrations:create <nome> -
bun run migrations:check(também no CI) falha enquanto entities e migrations divergem, e também se algum SQL congelado foi editado (ver SQL congelado).
Uma migration mergeada nunca é editada: qualquer correção é uma migration nova.
Nomes
- O nome puro do domínio (
parties) é só da primeira migration do domínio, a que carrega oconstraints.sqldele. - Toda migration seguinte do domínio usa
<domínio>-<mudança>, comoidentity-platform-logins, e não carrega arquivo de constraints. - O gerador numera o arquivo (
0018_…) e recusa um nome já usado.
Diff por snapshot, não contra o banco
O diff compara as entities com um snapshot (.snapshot-entities.json), não com um banco vivo. Comparar com o banco
derrubaria objetos criados por SQL à mão, como EXCLUDE e triggers, que o ORM não conhece.
O que vai na entity e o que vai em SQL
| Na entity | Em SQL escrito à mão |
|---|---|
PK GENERATED ALWAYS AS IDENTITY, colunas, FKs simples | EXCLUDE com GiST |
| UNIQUE, incluindo os UNIQUE de apoio | FK composta que reusa colunas de outra FK |
Índice único parcial (where) e NULLS NOT DISTINCT | FK para um domínio posterior (criada pelo domínio posterior) |
| CHECK, enums em texto, colunas geradas | Funções e triggers |
Rede contra deriva
Além do migrations:check, um teste de paridade compara o banco migrado com o modelo de dados: colunas, padrões, FKs
(ação e DEFERRABLE) e índices únicos. Se o modelo e as entities divergirem, o teste falha.