doc: migrations

migrations/README.md

@@ -1,3 +1,37 @@
 # Migrations
 
+Este projeto utiliza [pressly/goose](https://github.com/pressly/goose) para
+gerenciamento de migrações de banco de dados. Cada ERP possui seu próprio set de
+migrations. Por exemplo, `migrations/C5/*.sql`, `migrations/SENIOR/*.sql`...
 
+## Instalação
+
+```bash
+go install github.com/pressly/goose/v3/cmd/goose@latest
+```
+
+## Criando uma migração
+
+```bash
+goose -dir migrations/<ERP> create nome_da_migracao sql
+```
+
+Isso gera um arquivo com timestamp no formato
+`YYYYMMDDHHMMSS_nome_da_migracao.sql` contendo seções `-- +goose Up` e `--
++goose Down`.
+
+## Boas práticas
+
+- **Sempre escreva a migração `Down`**: garante que a migração possa ser
+  revertida com segurança.
+- **Uma mudança por migração**: mantenha cada arquivo focado em uma única
+  alteração (criar tabela, adicionar coluna, etc.).
+- **Migrações devem ser idempotentes quando possível**: use `IF NOT EXISTS` /
+  `IF EXISTS` para evitar falhas em re-execução.
+- **Nunca altere uma migração já aplicada**: se algo precisa ser corrigido, crie
+  uma nova migração.
+- **Evite migrações destrutivas em produção**: prefira adicionar colunas
+  nullable e remover as antigas em uma migração posterior, em vez de renomear ou
+  deletar diretamente.
+- **Teste localmente antes de aplicar**: rode `up` e `down` no ambiente local
+  para verificar que ambas as direções funcionam.