From f3497dbff3a5f00523ef9439a0d56e842bdd54b7 Mon Sep 17 00:00:00 2001 From: tkinaba Date: Fri, 27 Mar 2026 17:09:12 -0300 Subject: [PATCH] doc: migrations --- migrations/README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/migrations/README.md b/migrations/README.md index 663e81e..83a264b 100644 --- a/migrations/README.md +++ b/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/ 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.