fn_registry/functions/infra/sqlite_apply_versioned_migrations.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path, params, output

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path	params	output
sqlite_apply_versioned_migrations	function	go	infra	1.0.0	impure	func ApplyVersionedMigrations(conn *sql.DB, fsys fs.FS, dir string) error	Aplica migraciones SQLite pendientes desde un fs.FS con tracking explicito de versiones en schema_migrations. Cada migracion corre en su propia transaccion; si falla se hace rollback y se retorna el error sin avanzar la version.	sqlite migrations schema versioned transactional embed infra		error_go_core		false	error_go_core	database/sql io/fs fmt path sort strconv strings time	true	aplica todas desde cero y registra schema_migrations idempotente por version, no vuelve a aplicar migracion intermedia falla, version anterior no avanza archivos sin prefijo numerico se ignoran dir vacio no error y no crea schema_migrations	functions/infra/sqlite_apply_versioned_migrations_test.go	functions/infra/sqlite_apply_versioned_migrations.go	name desc conn Conexion SQLite abierta. Debe apuntar a la base de datos donde se gestionaran las migraciones. name desc fsys Sistema de archivos (embed.FS, os.DirFS, fstest.MapFS, etc.) que contiene el directorio de migraciones. name desc dir Ruta del directorio dentro de fsys que contiene los archivos .sql (ej. 'migrations').	nil si todas las migraciones pendientes se aplicaron correctamente; error descriptivo con el nombre del archivo que fallo en caso contrario.

Ejemplo

//go:embed migrations/*.sql
var migrationsFS embed.FS

func openDB(path string) (*sql.DB, error) {
    db, err := sql.Open("sqlite3", path+"?_foreign_keys=on&_journal_mode=WAL")
    if err != nil {
        return nil, err
    }
    if err := infra.ApplyVersionedMigrations(db, migrationsFS, "migrations"); err != nil {
        db.Close()
        return nil, fmt.Errorf("migrations: %w", err)
    }
    return db, nil
}

Diferencias vs sqlite_apply_migrations_go_infra (naive)

Aspecto	sqlite_apply_versioned_migrations (esta)	sqlite_apply_migrations (naive)
Tracking	Tabla schema_migrations — sabe exactamente que versiones estan aplicadas	Sin tabla de tracking — reaplica todo cada vez
Idempotencia	Por numero de version (version <= current se salta)	Por error — ignora "duplicate column / already exists"
Transacciones	Una transaccion por archivo — rollback limpio si falla	Sin transacciones — sentencias sueltas
Parsing SQL	Confia en SQLite multi-statement (tx.Exec del contenido completo)	Split manual por ; (fragil con strings)
Uso ideal	Apps con operations.db propias, BDs con datos vivos, deploy multi-PC	Bootstrap rapido, scripts de seed, migraciones sin estado persistente

Regla practica: usa sqlite_apply_versioned_migrations cuando necesites saber que se aplico, cuando, y garantizar que un fallo no deja la BD a medio migrar. Usa sqlite_apply_migrations para scripts de seed o inicializacion que no importa repetir.

Notas

• La funcion esta adaptada directamente de fn_operations/migrate.go — el patron probado en produccion del registry.
• schema_migrations guarda version (INTEGER PK), name (filename), applied_at (RFC3339 UTC).
• El SQL de cada archivo se ejecuta con una sola llamada tx.Exec(content) sin split por ;. Esto funciona correctamente con el driver go-sqlite3 (CGO) que soporta multi-statement. No usar con drivers pure-Go que no soporten multi-statement.
• Archivos sin prefijo numerico parseable o sin extension .sql se ignoran silenciosamente.
• Compatible con embed.FS, os.DirFS, y fstest.MapFS (util en tests).