#sqlmigrate API reference

A version-tracked schema-migration runner over the sql library. It applies ordered, reversible DDL migrations and records what ran in a schema_migrations tracking table, so each migration runs exactly once and can be rolled back.

It is deliberately decoupled from the orm mapper: a migration's up / down are plain list of string DDL statements, so you build them with orm's DDL helpers (orm.createTable / orm.dropTable / orm.addColumn / ...) or hand-written SQL - the runner never touches a Schema or a Query. That keeps it usable for any sql program, ORM or not.

The runner owns transaction control: each migration's up (or down) statements plus its tracking-table write run inside one sql transaction, so a failed statement rolls the whole step back and leaves schema_migrations consistent. It takes a raw sql.Connection (not an orm.Session) for that reason.

Migrations are ordered by version lexically, so zero-pad numeric versions ("001", "002", ...) or use a sortable timestamp ("20260101120000"). The tracking table (version VARCHAR(255) PRIMARY KEY, description TEXT) is accepted verbatim by both MySQL and PostgreSQL, so the runner needs no dialect.

Needs sql, so the default jennifer binary.

Import with import "sqlmigrate.j" as sqlmigrate;. See the sqlmigrate guide for prose and examples.

#Functions

#sqlmigrate.migrate(conn as sql.Connection, migrations as list of Migration)

Apply every pending migration in version order, each inside its own transaction, recording it in the schema_migrations tracking table (created if absent). Idempotent: already-applied versions are skipped.

Parameters

• conn {sql.Connection} - the open connection
• migrations {list of Migration} - the full migration set (any order)

Returns {int} - the number of migrations applied this run

#sqlmigrate.migrationStatus(conn as sql.Connection, migrations as list of Migration)

The applied / pending state of every migration, in version order.

Parameters

• conn {sql.Connection} - the open connection
• migrations {list of Migration} - the full migration set

Returns {list of MigrationStatus} - one entry per migration, in version order

#sqlmigrate.rollbackMigrations(conn as sql.Connection, migrations as list of Migration, steps as int)

Roll back the steps most-recently-applied migrations (by version order), running each one's down statements newest-first inside its own transaction and removing its tracking-table row.

Parameters

• conn {sql.Connection} - the open connection
• migrations {list of Migration} - the full migration set
• steps {int} - how many applied migrations to reverse

Returns {int} - the number of migrations rolled back

#Structs

#sqlmigrate.Migration

One schema migration: an ordered up and reverse down list of DDL statements (build them with orm's DDL helpers or hand-written SQL), identified by version. Runs are ordered by version lexically, so zero-pad numeric versions ("001", "002", ...) or use a sortable timestamp.

#sqlmigrate.MigrationStatus

The applied / pending state of one migration, from sqlmigrate.migrationStatus.