The Zuri Standard Library Zuri

Databases

sql.migrate

import sql.migrate
Zuri

sql does 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')
}
Zuri

Migrator 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()
Zuri

zuri 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
Zuri

Several 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'
Zuri

The table a Migrator records migrations in unless told another.

DEFAULT_DIRECTORY

sql.migrate.DEFAULT_DIRECTORY = 'migrations'
Zuri

The directory a Migrator reads migrations from unless told another, relative to the working directory.

Functions

is_name()

sql.migrate.is_name(name: string) -> bool
Zuri

Whether 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
Zuri

Writes 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
Zuri

Parameters

  • 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
Zuri

A 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(), so echo and print() show something useful

Fields

Field Type Description
migration The migration's name, or nil.

Constructor

sql.migrate.MigrationError(message, migration)
Zuri

Parameters

  • message (string)
  • migration (string|nil)

Migration

class sql.migrate.Migration
Zuri

One migration file.

  • printable — has a @to_string(), so echo and print() 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)
Zuri

Parameters

  • path (string)
  • name (string)
  • version (string)
  • checksum (string)

Migration.module()

sql.migrate.Migration.module() -> module
Zuri

The 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
Zuri

Whether the migration can be rolled back.

Returns bool

Migration.in_transaction()

sql.migrate.Migration.in_transaction() -> bool
Zuri

Whether the migration runs inside a transaction: true unless it sets transaction to false.

Returns bool

Migration.to_string()

sql.migrate.Migration.to_string()
Zuri

Migrator

class sql.migrate.Migrator
Zuri

Applies 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()
Zuri

The 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(), so echo and print() 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)
Zuri

Parameters

  • 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 to migrations, and table, the table that records them, which defaults to zuri_migrations.

Migrator.migrations()

sql.migrate.Migrator.migrations() -> list[Migration]
Zuri

Every 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]
Zuri

What 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]
Zuri

The migrations the database has not had, in the order they apply.

Returns list[Migration]

Migrator.status()

sql.migrate.Migrator.status() -> list[dict]
Zuri

Every 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]
Zuri

Applies 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' })
Zuri

A 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, or to, 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]
Zuri

Rolls back applied migrations, newest first.

migrator.down()                # the latest batch
migrator.down({ steps: 2 })    # the two most recent
migrator.down({ to: '20261011143000_create_posts' })
Zuri

Every 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, or to, 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]
Zuri

Rolls 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()
Zuri

2026, Richard Ore and Zuri contributors