pre-alpha

3.9 · Guides

Migrations

Hinoki compares each registered app's models with that app's migration state recorded in files. It can write a migration plan, but never applies schema changes when an application starts. hinoki new creates an explicit hinoki.toml; hinoki app create NAME adds another app and its migration package, and hinoki app add NAME --models MODULE registers a package that already exists.

Create a migration

uv run hinoki migrations plan --name add-published
uv run hinoki migrations plan --app billing --name add-invoice-index

The app can be named as an argument or with --app: hinoki migrations plan billing and hinoki migrations plan --app billing are the same. Naming it twice with different values is an error.

The manifest must register the selected app. A single-app project defaults to that app; in a multi-app project, writing a plan requires --app. Read-only --dry-run and --check without --app cover every registered app in dependency order. The planner targets the local SQLite default unless a URL is provided through HINOKI_DATABASE_URL or --database. It writes a numbered .sql file and a matching .state.json file into the registered migration package. Numbering and a stable slug derived from the first schema change are automatic; an optional --name replaces only that slug for a focused plan. Review both files before applying the change. Cross-app model references require an explicit requires dependency in hinoki.toml; this lets Hinoki validate references and order migrations without assigning another app's tables to the current app's migration state.

--dry-run previews ordinary destructive changes without --allow-destructive and writes no files. An all-app preview is hypothetical: it can show a child app change against a prerequisite's current candidate models before that prerequisite has a recorded migration. Do not treat displayed plans as ready to apply in that order. An all-app preview cannot use --name; select one app to preview a named migration.

Cross-app migration safety

Before writing a focused app plan, Hinoki checks cross-app foreign keys against the prerequisite app's recorded migration state. The referenced table and column must already be recorded, the column must be a primary key, and its logical type must be compatible. If the prerequisite has not been planned yet, plan and review it first. The prerequisite migration does not need to have been applied to the database before the dependent app can be planned.

Hinoki also refuses to plan a parent table or referenced-column teardown while any recorded state snapshot of another app still refers to it. This guard applies to focused/all-app plans, --dry-run, and --check, and cannot be overridden with --allow-destructive. An all-app command fails without printing partial diffs. This prevents a generated parent drop from preceding a child foreign-key removal. Perform cross-app teardowns as reviewed, separately deployed phases: remove and apply the child reference first, then prepare and apply the parent teardown. The planner does not infer live database safety from migration files.

The state file stores logical column types that are stable across backends; the generated SQL uses the selected backend's types. Existing state files that recorded SQLite or MySQL-specific type names are normalized when planning, so switching the planner's backend does not appear as a destructive type change.

New Model classes may omit table=; Hinoki derives the table name <app>_<models> from the package of the model's models module and the Python class name. Keep table= explicit for models with existing migration history so later Python class renames do not change physical table identity. A changed implicit name appears as a drop/create plan and the destructive guard still applies. Hinoki refuses generated names reserved for its migration ledger or SQLite internals. See Models and queries for display-name overrides and the fallback naming rules.

Check migration drift

To check that model changes have a migration file in CI, run:

uv run hinoki migrations plan --check

It exits 1 when operations are pending, including destructive operations, and 0 when every selected app matches its latest migration state file. It does not write migration files or connect to a database. It imports registered model and migration modules (cross-app foreign keys require every model module), so those imports must be safe in CI. In a multi-app project, no --app checks every app in dependency order; --app NAME checks one app and its prerequisites. This check concerns file state only. Use migrations status to compare files with a live database's applied migration ledger. --dry-run without --app previews every registered app and exits successfully when changes are pending.

For example, billing can depend on accounts:

[[apps]]
name = "billing"
models = "sample.apps.billing.models"
migrations = "sample.apps.billing.migrations"
requires = ["accounts"]

Apply and inspect

apply and status take the app the same way: hinoki migrations apply billing applies billing and its prerequisites. Planning and applying stay two separate commands, so a migration is never written and applied in one step.

export HINOKI_DATABASE_URL="$BLOG_DATABASE__URL"
uv run hinoki migrations status
uv run hinoki migrations sql --app accounts 0001-initial
uv run hinoki migrations apply

With no URL, status and apply use sqlite://./.hinoki/local.sqlite3 and create the migration ledger/database as needed. In a manifest project this implicit path is anchored at the directory containing hinoki.toml, even when the command runs from a subdirectory. Without a manifest it stays relative to the current working directory. An explicit relative SQLite URL from HINOKI_DATABASE_URL or --database remains relative to the current working directory. Both commands operate on every registered app in dependency order. --app NAME limits them to that app and its prerequisites. sql requires --app in a multi-app project. The scaffolded root app keeps the traditional unprefixed migration ledger keys, so a project can add a manifest without replaying its existing migration history; added apps use namespaced keys, so accounts/0001-initial.sql and billing/0001-initial.sql are distinct records. Set HINOKI_DATABASE_URL or use --database URL to target another supported backend. A URL argument is visible in the process list and shell history, so do not pass a URL containing a password that way. A failed connection is reported as error: database: … with exit code 1, without the URL.

Existing projects without a hinoki.toml can continue using explicit --models MODULE and --dir PATH options. These options cannot be combined with a project manifest; use the manifest as the single source for registered apps.

Use a disposable database to review a migration before running it against important data.

Concurrent apply runs are serialized: each migration file runs in one transaction that takes a PostgreSQL advisory lock, a MySQL/MariaDB migration lock or, on SQLite, BEGIN IMMEDIATE, and reads the ledger inside it, so a file is applied once. On SQLite a second runner waits for the write lock for at most the busy timeout (5 seconds) and then fails with a locked-database error, so run apply from one process, as a deployment step.

SQLite uses table rebuilds when a schema change cannot be expressed safely with ALTER TABLE. Review the generated SQL carefully. Dropping columns, changing types or constraints, and adding non-null columns can be destructive and require --allow-destructive. Hinoki holds the SQLite pool during a migration, suspends foreign-key enforcement on reserved connections, runs PRAGMA foreign_key_check before commit, and rolls the migration back if references are invalid.

MySQL and MariaDB migrations declare foreign keys at table level. For databases migrated with an older Hinoki version, inspect SHOW CREATE TABLE: MySQL ignores inline REFERENCES clauses, while MariaDB behavior varies by server version. Add any missing constraint through a reviewed manual migration; applied migrations are never rewritten automatically. Automatic removal of a foreign key column is refused for these backends because the planner cannot know whether an older migration actually created its constraint.

Destructive changes

Operations that can remove data are reported as destructive and are not written unless --allow-destructive is passed to plan. Read the generated migration before opting in. Changing a constraint on an existing column may require a hand-written migration.

Migrations are files committed with the application. Do not run them from every server worker's startup hook. For the connection lifecycle, see settings.