Migraciones con golang-migrate y goose

Los cambios de esquema pertenecen a archivos de migración versionados, no a ALTER ad hoc al iniciar la aplicación.

golang-migrate y goose son herramientas populares compatibles con Go que aplican migraciones SQL (o Go) ordenadas y soportan reversiones en pipelines de CI y despliegue.

Resumen

Las migraciones son archivos con marca de tiempo o secuenciados con secciones up y down.

Aplica migraciones antes de que el nuevo código sirva tráfico, o usa patrones expandir-contraer para despliegues con cero tiempo de inactividad.

Ejecuta trabajos de migración en CI contra bases de datos efímeras para detectar errores SQL temprano.

Nunca ejecutes migraciones dentro de manejadores HTTP por solicitud.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

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

// Incrustar migraciones (ver artículo hermano)
//go:embed migrations/*.sql
var migrationFS embed.FS

Cuándo usar esto:

• Cualquier esquema SQL gestionado por el equipo y compartido entre entornos.
• Pipelines de despliegue que deben fallar si existe deriva de esquema.
• Simulacros de reversión donde las migraciones down restauran la forma anterior en staging.

Ejemplo de Trabajo

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("migraciones aplicadas")
}

Ejemplo migrations/00001_create_users.sql:

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

Lo que esto demuestra:

• goose.Up aplica archivos pendientes en orden léxico.
• Cada archivo documenta pasos hacia adelante y hacia atrás.
• SetDialect selecciona las peculiaridades de SQL para Postgres, MySQL o SQLite.
• La migración se ejecuta como un hook de despliegue o un contenedor de inicialización, no por solicitud HTTP.

Profundización

Cómo Funciona

• Las herramientas rastrean las versiones aplicadas en una tabla de metadatos (schema_migrations o tabla de versiones de goose).
• up ejecuta archivos pendientes; down revierte los últimos N pasos.
• golang-migrate nombra los archivos 000001_init.up.sql y 000001_init.down.sql.
• goose soporta migraciones SQL y Go para backfills de datos que necesitan bucles.

Flujo de CI y Despliegue

Patrones de Cero Tiempo de Inactividad

1. Expandir: añadir columna nullable o tabla nueva; desplegar código que escribe en ambos (antiguo y nuevo).
2. Migrar datos: trabajo de backfill fuera de la ruta de solicitud.
3. Contraer: eliminar columna antigua después de que el tráfico use la nueva forma.

Los cambios destructivos (NOT NULL sin valor predeterminado, renombrar en el lugar) requieren lanzamientos multifase.

golang-migrate vs goose

Trampas

• Editar archivos de migración aplicados - Los entornos divergen silenciosamente. Solución: nueva migración solo hacia adelante para corregir el estado.
• Migración down faltante - Los simulacros de reversión fallan. Solución: requerir down en la revisión para cambios reversibles; documentar operaciones irreversibles.
• Migración de larga duración en tiempo de espera de despliegue - El despliegue mata el trabajo a mitad de ALTER. Solución: ejecutar migraciones pesadas como un trabajo de mantenimiento separado con monitorización de bloqueos.
• AutoMigrate al inicio de la aplicación en producción - Carrera entre réplicas; diferencias no rastreadas. Solución: trabajo de migración explícito con tabla de versiones.
• Sin base de datos de CI - SQL roto llega a producción. Solución: servicio Postgres efímero en el pipeline aplicando up antes de las pruebas.
• down destructivo en producción - Pérdida de datos en la reversión. Solución: tratar down solo para staging; las reversiones de producción restauran copias de seguridad.

Alternativas

Preguntas Frecuentes

Relacionado

• embed para Migraciones SQL y Datos de Semilla - empaqueta archivos en el binario
• Conceptos Básicos de Bases de Datos - conceptos básicos de ejecución SQL
• Transacciones, Sentencias Preparadas y sql.Tx - límites de transacciones DDL
• GORM vs sqlx vs Raw database/sql - compromisos de AutoMigrate
• Mejores Prácticas de Bases de Datos y Acceso a Datos - reglas de CI de migración

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, go fix modernizers - verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación), y golangci-lint (última versión - verificar conjunto de linters en la compilación). cGJxcnRodnFyZi52YnxwdHZiNDA3fDIwMjYwNw==