embed para Migraciones SQL y Datos de Inicialización

Go 1.16+ embed te permite enviar archivos de migración SQL y scripts de inicialización dentro del binario compilado.

Los artefactos de despliegue permanecen autocontenidos: la misma imagen de contenedor que ejecuta la API puede aplicar versiones de esquema sin montar un directorio del host.

Resumen

//go:embed adjunta archivos o directorios a variables de tipo embed.FS.

Las bibliotecas de migración aceptan adaptadores io/fs o http.FileSystem sobre el FS incrustado.

Los datos de inicialización para desarrollo y pruebas pueden enviarse en un árbol incrustado separado de las migraciones de producción.

Receta

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

package migrations
 
import (
    "embed"
    "io/fs"
)
 
//go:embed sql/*.sql
var files embed.FS
 
func FS() fs.FS {
    sub, _ := fs.Sub(files, "sql")
    return sub
}

import (
    "github.com/golang-migrate/migrate/v4"
    _ "github.com/golang-migrate/migrate/v4/database/postgres"
    "github.com/golang-migrate/migrate/v4/source/iofs"
)
 
source, _ := iofs.New(migrations.FS(), ".")
m, _ := migrate.NewWithSourceInstance("iofs", source, dbURL)
_ = m.Up()

Cuándo recurrir a esto:

• Despliegues de binario único (Kubernetes, contenedores sin servidor) sin SQL montado por ConfigMap.
• Herramientas CLI que deben migrar portátiles sin conexión sin un checkout de git.
• Pruebas de integración que necesitan un esquema conocido incrustado junto al código de prueba.

Ejemplo de Trabajo

package main
 
import (
    "database/sql"
    "embed"
    "fmt"
    "io/fs"
 
    "github.com/pressly/goose/v3"
    _ "github.com/mattn/go-sqlite3"
)
 
//go:embed migrations/*.sql
var migrationFiles embed.FS
 
func main() {
    db, _ := sql.Open("sqlite3", ":memory:")
    defer db.Close()
 
    goose.SetBaseFS(migrationFiles)
    goose.SetDialect("sqlite3")
    if err := goose.Up(db, "migrations"); err != nil {
        panic(err)
    }
 
    var n int
    _ = db.QueryRow(`SELECT COUNT(*) FROM sqlite_master WHERE type='table'`).Scan(&n)
    fmt.Println("tables:", n)
}

migrations/00001_init.sql:

-- +goose Up
CREATE TABLE widgets (id INTEGER PRIMARY KEY, name TEXT);
 
-- +goose Down
DROP TABLE widgets;

Lo que esto demuestra:

• go:embed agrupa los archivos SQL junto al archivo fuente de Go.
• goose.SetBaseFS lee las migraciones desde la memoria en lugar del disco.
• El mismo patrón funciona para el controlador de origen iofs de golang-migrate.
• SQLite en memoria demuestra el flujo sin archivos externos en tiempo de ejecución.

Análisis Profundo

Cómo Funciona

• El compilador registra los archivos coincidentes en el binario en tiempo de compilación.
• embed.FS es de solo lectura y seguro para compartir entre goroutines.
• fs.Sub reduce la raíz cuando el SQL vive en un subdirectorio.
• Cambiar el SQL requiere recompilación y redespliegue, lo cual es deseable para lanzamientos reproducibles.

Convenciones de Diseño

golang-migrate con iofs

d, err := iofs.New(migrations.FS(), ".")
m, err := migrate.NewWithInstance("iofs", d, "postgres", dbURL)

• El nombre de origen "iofs" se empareja con el nombre del controlador de base de datos en NewWithInstance.
• El bloqueo todavía usa la base de datos; embed solo reemplaza las lecturas del sistema de archivos.
• CI debería ejecutar las mismas pruebas de FS incrustado que producción.

Patrones de Datos de Inicialización

• Seeds solo para desarrollo: etiqueta de compilación o //go:embed seed/* separado importado solo desde main_dev.go.
• Seeds idempotentes: INSERT ... ON CONFLICT DO NOTHING o migración Go de goose con bucles.
• Nunca incrustes secretos de producción - las seeds contienen solo datos ficticios.

Trampas

• Ruta de embed incorrecta después de refactorización - La compilación falla con "pattern matches no files". Solución: mantén el directorio SQL adyacente al archivo Go que contiene go:embed.
• Editar migraciones sin recompilar - Ejecutar un binario antiguo aplica un esquema obsoleto. Solución: vincula la etiqueta de la imagen al SHA de git; la tabla de versión de migración detecta desviaciones.
• Archivos de seed enormes hinchan el binario - El tamaño del contenedor y el tiempo de enlace aumentan. Solución: comprime las seeds de desarrollo o carga desde almacenamiento de objetos solo en entornos no de producción.
• Suposición de embed.FS escribible - Embed es de solo lectura; las herramientas que reescriben archivos necesitan disco o copias temporales. Solución: usa APIs de biblioteca que lean desde fs.FS.
• Mezcla de fuentes del host y embed - Comportamiento diferente en desarrollo vs producción. Solución: una única fuente de verdad; el desarrollo local usa el mismo embed o go run desde la raíz del módulo.
• Secretos en archivos SQL - Credenciales comprometidas en scripts de inicialización. Solución: parametriza el DSN desde el entorno; el SQL no contiene contraseñas.

Alternativas

Preguntas Frecuentes

Relacionado

• Migraciones con golang-migrate & goose - comandos de herramientas y CI
• Conceptos Básicos de Bases de Datos - ejecución de SQL
• Bases de Datos y Mejores Prácticas de Acceso a Datos - artefactos de migración inmutables
• Acceso a Datos en Go: database/sql como Fundación - cableado del pool después de migrar

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