Databases
sql.migrate
import sql.migrate
Zuri
sqldoes not re-export this module, so it is reached only by importing it directly.
Versioned changes to a database's schema, each applied once, in order, on every engine.
A migration is a Zuri file in a directory of migrations. Its name starts with a version, which is a sequence of digits, followed by a description of what it does:
migrations/
20261011143000_create_posts.zu
20261012091500_add_slug_to_posts.zu
Each migration exports up(db), which makes the change, and down(db),
which undoes it. db is the Transaction that the migration runs in,
or the Connection itself when it runs outside a transaction. That's
always the case on MySQL and MariaDB, and on any engine for a migration
that asks for it. Its type is Transaction|Connection, and the change
is described once, with db.schema and a Blueprint, for every engine
the program runs against:
import sql { Blueprint, Connection, Transaction }
def up(db: Transaction|Connection) {
db.schema.create_table('posts', (table: Blueprint) {
table.id()
table.string('title', 200)
table.timestamps()
})
}
def down(db: Transaction|Connection) {
db.schema.drop_table('posts')
}
ZuriMigrator applies the migrations that a database hasn't had yet and
rolls back the ones it has, and records each one in a table of its own,
which is zuri_migrations by default:
import sql
import sql.migrate { Migrator }
var db = sql.open(env.require('DATABASE_URL'))
Migrator(db, { directory: 'migrations' }).up()
Zurizuri migrate does the same from the command line.
How a migration runs
Each migration runs in a transaction of its own, together with the row that records it. On SQLite and PostgreSQL, a migration that fails partway through therefore leaves nothing behind and isn't recorded. MySQL and MariaDB commit after every schema change, so there a migration runs outside a transaction and is recorded once it has finished, and a migration that fails partway through leaves the statements before the failure in place.
On SQLite, foreign key enforcement is turned off while a migration runs, so that rebuilding a table doesn't also delete the rows that refer to it. Every foreign key is checked before the migration commits.
A migration that has to run outside a transaction, as PostgreSQL's
create index concurrently does, says so:
var transaction = false
ZuriSeveral processes at once
If two processes migrate the same database at the same time, each migration is still applied once. On PostgreSQL, MySQL and MariaDB, a run holds a lock provided by the engine, and a second run waits for the first to finish. On SQLite, each migration takes the write lock when it starts and checks the record again once it holds the lock, so a migration that another process has applied in the meantime is skipped.
Batches
All the migrations applied by one call to up() share a batch number.
down() with no options rolls back the whole of the latest batch, which
is everything the last run applied, however many migrations that was.
Constants
DEFAULT_TABLE
sql.migrate.DEFAULT_TABLE = 'zuri_migrations'
ZuriThe table a Migrator records migrations in unless told another.
DEFAULT_DIRECTORY
sql.migrate.DEFAULT_DIRECTORY = 'migrations'
ZuriThe directory a Migrator reads migrations from unless told another,
relative to the working directory.
Functions
is_name()
sql.migrate.is_name(name: string) -> bool
ZuriWhether name can name a migration: one or more letters, digits and
underscores, such as create_posts.
Parameters
name(string)
Returns bool
create()
sql.migrate.create(directory: string, name: string) -> string
ZuriWrites a new, empty migration into directory, and returns its path.
The version is the moment it was made, in UTC, as YYYYMMDDHHMMSS,
moved on a second at a time past any version the directory already
holds. The file is the version, an underscore and name, exactly as
given.
A name of the form create_<table> starts the migration creating that
table, with an id() and timestamps(), and dropping it on the way
down. Any other name starts it empty. Either way up() and down()
start typed, db: Transaction|Connection, with the classes imported
from sql.
migrate.create('migrations', 'create_posts')
# migrations/20261011143000_create_posts.zu
ZuriParameters
directory(string) — Created when it is not there.name(string) — Letters, digits and underscores.
Returns string — The new file's path.
Raises MigrationError if name is empty or has anything but
letters, digits and underscores in it, and nothing is written.
Classes
MigrationError
class sql.migrate.MigrationError < SqlError
ZuriA migration that cannot be run as asked: a directory or a file that
breaks the naming rules, a file without up(), a rollback of one
without down(), or a version two files share.
migration names the migration concerned, where there is one.
- printable — has a
@to_string(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
migration |
The migration's name, or nil. |
Constructor
sql.migrate.MigrationError(message, migration)
ZuriParameters
message(string)migration(string|nil)
Migration
class sql.migrate.Migration
ZuriOne migration file.
- printable — has a
@to_string(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
name |
string |
The migration's name: its file name without .zu, such as 20261011143000_create_posts. |
version |
string |
The digits the name starts with. |
path |
string |
The file. |
checksum |
string |
The SHA-256 of the file as it is now, in hex. |
Constructor
sql.migrate.Migration(path, name, version, checksum)
ZuriParameters
path(string)name(string)version(string)checksum(string)
Migration.module()
sql.migrate.Migration.module() -> module
ZuriThe migration's module, imported the first time it is asked for.
Returns module
Raises MigrationError if it does not export up().
Migration.has_down()
sql.migrate.Migration.has_down() -> bool
ZuriWhether the migration can be rolled back.
Returns bool
Migration.in_transaction()
sql.migrate.Migration.in_transaction() -> bool
ZuriWhether the migration runs inside a transaction: true unless it sets
transaction to false.
Returns bool
Migration.to_string()
sql.migrate.Migration.to_string()
ZuriMigrator
class sql.migrate.Migrator
ZuriApplies a directory of migrations to one database, and rolls them back.
var migrator = Migrator(db, { directory: 'migrations' })
for entry in migrator.status() {
echo '${entry.state} ${entry.name}'
}
migrator.up()
ZuriThe record of what has been applied lives in the database, in the table
table names, created the first time a Migrator needs it.
- printable — has a
@to_string(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
connection |
Connection |
The connection migrated. |
directory |
string |
The directory the migrations are read from. |
table |
string |
The table migrations are recorded in. |
Constructor
sql.migrate.Migrator(connection, options)
ZuriParameters
connection(Connection) — A connection used only by the migrator. A run holds it from start to finish, along with a session lock on PostgreSQL and MySQL. A connection taken from a pool is returned to the pool afterwards by the caller, like any other.options(dict|nil) —directory, the directory of migrations, which defaults tomigrations, andtable, the table that records them, which defaults tozuri_migrations.
Migrator.migrations()
sql.migrate.Migrator.migrations() -> list[Migration]
ZuriEvery migration in the directory, in the order they apply: by version, then by name.
A .zu file whose name starts with _ is not a migration, which is
where code several migrations share goes. Files that are not .zu are
left alone.
Returns list[Migration]
Raises MigrationError if the directory is not there, a file's name
does not start with a version and an underscore, or two files share a
version.
Migrator.applied()
sql.migrate.Migrator.applied() -> list[dict]
ZuriWhat the database records as applied, oldest first. Each is { name, batch, checksum, applied_at }.
Returns list[dict]
Migrator.pending()
sql.migrate.Migrator.pending() -> list[Migration]
ZuriThe migrations the database has not had, in the order they apply.
Returns list[Migration]
Migrator.status()
sql.migrate.Migrator.status() -> list[dict]
ZuriEvery migration that's either in a file or in the record, with what's
known about it. Each one is { name, state, batch, applied_at }, and
state is one of these:
| State | Meaning |
|---|---|
applied |
recorded, and the file is the same as when it ran |
changed |
recorded, and the file has changed since it ran |
missing |
recorded, but its file no longer exists |
pending |
a file that hasn't been applied to the database |
batch and applied_at are nil for a pending migration.
Returns list[dict]
Migrator.up()
sql.migrate.Migrator.up(options) -> list[string]
ZuriApplies pending migrations, in order, as one batch.
migrator.up() # everything pending
migrator.up({ steps: 1 }) # the next one
migrator.up({ to: '20261012091500_add_slug_to_posts' })
ZuriA migration that fails stops the run. The migrations before it stay applied, and it and the ones after it stay pending.
Parameters
options(dict|nil) —steps, the most migrations to apply, orto, the name of the last one to apply. If neither is given, everything pending is applied.
Returns list[string] — The names of the migrations applied, in
order.
Raises MigrationError if to doesn't name a pending migration, or
a file can't be run.
Migrator.down()
sql.migrate.Migrator.down(options) -> list[string]
ZuriRolls back applied migrations, newest first.
migrator.down() # the latest batch
migrator.down({ steps: 2 }) # the two most recent
migrator.down({ to: '20261011143000_create_posts' })
ZuriEvery migration that's about to be rolled back is checked first. Each
one must still have its file, with a down() function, or nothing is
rolled back at all.
Parameters
options(dict|nil) —steps, the number of migrations to roll back, orto, the name of a migration to leave as the latest applied one, rolling back everything after it. If neither is given, the latest batch is rolled back.
Returns list[string] — The names of the migrations rolled back, in
the order they were rolled back.
Raises MigrationError if to doesn't name an applied migration,
or a migration to be rolled back has no file or no down().
Migrator.reset()
sql.migrate.Migrator.reset() -> list[string]
ZuriRolls back every applied migration, newest first.
Returns list[string] — The names of the migrations rolled back.
Raises MigrationError if a migration has no file or no down().
In that case, nothing is rolled back.
Migrator.to_string()
sql.migrate.Migrator.to_string()
Zuri2026, Richard Ore and Zuri contributors