Migrações com golang-migrate & goose

Alterações de esquema pertencem a arquivos de migração versionados, não a ALTER ad hoc na inicialização do aplicativo.

golang-migrate e goose são ferramentas populares compatíveis com Go que aplicam migrações SQL (ou Go) ordenadas e suportam rollbacks em pipelines de CI e implantação.

Resumo

Migrações são arquivos com timestamp ou sequenciados com seções up e down.

Aplique migrações antes que o novo código sirva tráfego, ou use padrões expand-contract para implantações sem tempo de inatividade.

Execute trabalhos de migração em CI contra bancos de dados efêmeros para capturar erros SQL precocemente.

Nunca execute migrações dentro de manipuladores HTTP por solicitação.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# CLI do golang-migrate
migrate -path ./migrations -database "${DATABASE_URL}" up
migrate -path ./migrations -database "${DATABASE_URL}" down 1
 
# CLI do goose
goose -dir ./migrations postgres "$DATABASE_URL" up
goose -dir ./migrations postgres "$DATABASE_URL" down

// incorporar migrações (veja artigo irmão)
//go:embed migrations/*.sql
var migrationFS embed.FS

Quando usar isso:

• Qualquer esquema SQL gerenciado pela equipe e compartilhado entre ambientes.
• Pipelines de implantação que devem falhar se houver desvio de esquema.
• Simulações de rollback onde as migrações down restauram a forma anterior no staging.

Exemplo de Trabalho

package main
 
import (
    "database/sql"
    "fmt"
    "log"
 
    "github.com/pressly/goose/v3"
    _ "github.com/jackc/pgx/v5/stdlib"
)
 
func main() {
    db, err := sql.Open("pgx", "postgres://localhost:5432/app?sslmode=disable")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()
 
    goose.SetDialect("postgres")
    if err := goose.Up(db, "migrations"); err != nil {
        log.Fatal(err)
    }
    fmt.Println("migrações aplicadas")
}

Exemplo migrations/00001_create_users.sql:

-- +goose Up
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    email TEXT NOT NULL UNIQUE
);
 
-- +goose Down
DROP TABLE users;

O que isso demonstra:

• goose.Up aplica arquivos pendentes em ordem lexical.
• Cada arquivo documenta etapas de avanço e reversão.
• SetDialect seleciona peculiaridades SQL para Postgres, MySQL ou SQLite.
• A migração é executada como um hook de implantação ou contêiner de inicialização, não por solicitação HTTP.

Mergulho Profundo

Como Funciona

• Ferramentas rastreiam versões aplicadas em uma tabela de metadados (schema_migrations ou tabela de versão do goose).
• up executa arquivos pendentes; down reverte as últimas N etapas.
• golang-migrate nomeia arquivos 000001_init.up.sql e 000001_init.down.sql.
• goose suporta migrações SQL e Go para preenchimento de dados que precisam de loops.

Fluxo de CI e Implantação

Padrões de Tempo de Inatividade Zero

1. Expandir: adicionar coluna anulável ou nova tabela; implantar código que escreve em ambos, o antigo e o novo.
2. Migrar dados: trabalho de preenchimento fora do caminho de solicitação.
3. Contrair: remover a coluna antiga depois que o tráfego usar a nova forma.

Alterações que quebram compatibilidade (NOT NULL sem padrão, renomear no local) exigem lançamentos multifásicos.

golang-migrate vs goose

Armadilhas

• Editar arquivos de migração aplicados - Ambientes divergem silenciosamente. Correção: nova migração somente para frente para corrigir o estado.
• Migração down ausente - Simulações de rollback falham. Correção: exigir down na revisão para alterações reversíveis; documentar operações irreversíveis.
• Migração de longa duração no tempo limite de implantação - A implantação encerra o trabalho no meio do ALTER. Correção: executar migrações pesadas como trabalho de manutenção separado com monitoramento de locks.
• AutoMigrate na inicialização do aplicativo em produção - Corrida entre réplicas; diferenças não rastreadas. Correção: trabalho de migração explícito com tabela de versão.
• Sem banco de dados de CI - SQL quebrado chega à produção. Correção: serviço Postgres efêmero no pipeline aplicando up antes dos testes.
• down destrutivo em produção - Perda de dados no rollback. Correção: tratar down apenas para staging; rollbacks de produção restauram backups.

Alternativas

FAQs

Relacionado

• embed para Migrações SQL e Dados de Seed - agrupar arquivos no binário
• Noções Básicas de Banco de Dados - noções básicas de execução SQL
• Transações, Declarações Preparadas & sql.Tx - limites de transação DDL
• GORM vs sqlx vs Banco de Dados/sql Bruto - contrapartidas do AutoMigrate
• Melhores Práticas de Banco de Dados e Acesso a Dados - regras de CI de migração

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão GC Green Tea, go fix modernizers - verifique o patch na compilação), chi (mais recente - verifique na compilação), gin (mais recente - verifique na compilação), echo (mais recente - verifique na compilação), google.golang.org/grpc (mais recente - verifique na compilação), sigs.k8s.io/controller-runtime (mais recente - verifique na compilação), kubebuilder (mais recente - verifique na compilação), tinygo (mais recente - verifique os alvos de placa na compilação), wazero (mais recente - verifique na compilação) e golangci-lint (mais recente - verifique o conjunto de linters na compilação). cGJxcnRodnFyZi52YnxwdHZiNDA3fDIwMjYwNw==