GuidesData
Migrations¶
Hinoki compares each app's models with the migration state recorded in its
migration package and writes SQL files you review and commit. Nothing changes a
database until you run apply; an application never migrates at startup.
hinoki migrations plan billing
hinoki migrations apply
Commands run from the project, where hinoki.toml registers each app's models
and migrations (hinoki new, hinoki app create). Prefix them with uv run
or activate .venv.
Plan a migration¶
hinoki migrations plan # a project with one app
hinoki migrations plan billing # one app of several
hinoki migrations plan billing --name add-invoice-index
plan writes two files into the app's migration package:
0001-create-table-billing-invoices.sql and its .state.json. The number is
automatic; the slug comes from the first change (create table
billing_invoices) unless --name replaces it.
In a project with several apps, plan needs the app name; --check and
--dry-run without one cover every app.
Plan for the backend you deploy
The SQL uses the dialect of the selected database:
usually the application's own database setting. Point it at the
production backend (a disposable database of the same kind) before
planning. The state file is backend-neutral.
Review before applying¶
Read both files. Changes that can lose data are destructive and are not
written unless you pass --allow-destructive:
- dropping a table or column, changing a type or constraint, adding a non-null column;
- a changed derived table name (renaming the class or moving its module), which
is planned as a drop and a create. Pin the name with
@db.table(...)(table names).
hinoki migrations plan billing --dry-run
hinoki migrations plan billing --allow-destructive
--dry-run prints the plan, destructive operations included, and writes
nothing. Changing a constraint on an existing column may need a hand-written
migration.
Apply and inspect¶
hinoki migrations status
hinoki migrations sql 0001-create-table-billing-invoices
hinoki migrations apply
hinoki migrations apply billing
| Command | Effect |
|---|---|
status [APP] |
lists applied and pending migrations (nothing when there are none); creates the ledger, and a SQLite file, if missing |
sql NAME |
prints one migration's SQL; add --app APP only when the name is ambiguous |
apply [APP] |
applies pending migrations of every app, or of APP and its prerequisites, in dependency order |
Which database¶
plan, status and apply use the first of:
--database URL;- the
HINOKI_DATABASE_URLenvironment variable; - the project's application (
project.applicationinhinoki.toml): aDatabaseModuleit passes inmodules=or installs withapp.install(...), otherwise itsdatabasesetting, read from its settings sources as the server reads them, for exampleNOTES_DATABASE__URLor.env; - local SQLite,
sqlite://./.hinoki/local.sqlite3.
The application is imported from the project root to read its settings, so
.env and other relative settings files are the ones beside hinoki.toml,
even from a subdirectory. Anything it prints while importing goes to standard
error. No connection opens until the command needs one, and nothing is
started. The command never falls back to another database: it stops with exit
2 when
- the application cannot be imported (the message names the missing module or attribute) or its settings cannot be loaded;
- it installs a database module of its own whose URL Hinoki cannot read;
- the application's database is in-memory SQLite (
sqlite://:memory:), where nothing it migrates would survive. A--database sqlite://:memory:URL is refused with exit1instead, because SQLite needs a file URL there.
Fix the application, or choose the database with --database or
HINOKI_DATABASE_URL, which skip step 3 and never import the application. An
application without a database still migrates the local SQLite default, but
the server has none to use: declare database: settings.DatabaseSettings
(configure a database).
Outside a project (--models/--dir), step 3 is skipped.
plan, status and apply print the chosen database and its source on
standard error. Everything before the host (user and password) and the URL
options are masked, and a URL that does not parse is not echoed:
$ NOTES_DATABASE__URL=postgresql://notes:secret@db.internal/notes hinoki migrations status
database: postgresql://***@db.internal/notes (from settings: ProjectSettings.database)
A relative SQLite path from the settings or the default is anchored beside
hinoki.toml, so migrations run from a subdirectory use the same file; a
relative SQLite URL given with --database or HINOKI_DATABASE_URL stays
relative to the current directory. The server and hinoki settings do not
anchor: they resolve the path, and read .env, from the directory they start
in, so start them from the project root. A connection failure prints
error: database: … and exits 1. A
--database URL is visible in the process list and shell history: do not put
a password in it.
The root app keeps unprefixed ledger keys; added apps use namespaced keys, so
accounts/0001-initial.sql and billing/0001-initial.sql are distinct records.
Run apply once per deployment, from one process, never from every worker's
startup (settings). Concurrent
runs are serialized: each file runs in one transaction under a PostgreSQL
advisory lock, a MySQL/MariaDB migration lock or SQLite BEGIN IMMEDIATE, and
reads the ledger inside it. On SQLite a second runner waits at most the busy
timeout (5 seconds), then fails as locked.
Check migration drift¶
hinoki migrations plan --check
Exits 1 when any app has model changes without a migration file, destructive
ones included, 0 otherwise, and 2 when the database whose dialect it plans
for cannot be resolved (which database). It covers every
app in dependency order (plan billing --check: that app and its
prerequisites), writes nothing and opens no connection. It imports every
registered model and migration module and, unless --database or
HINOKI_DATABASE_URL names the database, the project's application to read
its database, so those imports must be safe in CI:
HINOKI_DATABASE_URL=postgresql://ci@localhost/notes hinoki migrations plan --check
status compares files with a live database instead.
Apps and dependencies¶
An app that references another app's models declares it in requires:
# hinoki.toml
[[apps]]
name = "billing"
models = "notes.apps.billing.models"
migrations = "notes.apps.billing.migrations"
requires = ["accounts"]
hinoki app create billing asks for requires; hinoki app add NAME --models
MODULE registers an existing package. Each app's tables belong only to its
own migration state.
Cross-app migration safety¶
- Before planning
billing, the referenced table and primary key must already be recorded inaccounts' migration state with a compatible type; plan and reviewaccountsfirst. It does not need to be applied yet. - A parent table or referenced column is never dropped while another app's
recorded state still refers to it, in
plan,--dry-runand--check;--allow-destructivedoes not override this, and an all-app command fails without partial output. Remove and apply the child reference first, then plan the parent teardown in a separate deployment. --dry-runwithout an app previews every app, possibly against a prerequisite's not-yet-planned models: do not apply in that order. It cannot take--name.
Backend behaviour¶
| Backend | Behaviour |
|---|---|
| SQLite | rebuilds a table when ALTER TABLE cannot express the change safely; holds the pool, suspends foreign-key enforcement on reserved connections, runs PRAGMA foreign_key_check before commit and rolls back on invalid references |
| PostgreSQL | each migration runs in a transaction |
| MySQL | DDL commits implicitly: a failed migration may be partially applied (Hinoki says so). Check the schema and status before retrying; keep a backup |
| MariaDB | separate backend on the MySQL wire protocol; JSON is a text alias decoded by typed fields |
MySQL and MariaDB foreign keys are table-level constraints. For databases
migrated by an older Hinoki, check SHOW CREATE TABLE: MySQL ignores inline
REFERENCES, and MariaDB varies by version. Add a missing constraint with a
reviewed manual migration; applied migrations are never rewritten. Automatic
removal of a foreign-key column is refused on these backends.
State files record logical types; files from older versions that recorded SQLite or MySQL type names are normalized, so switching the planner's backend is not reported as a type change.
Without a manifest¶
A project without hinoki.toml passes the models module and directory:
hinoki migrations --dir app/migrations plan --models app.models
These options cannot be combined with a manifest. Prefer adding one: the root app keeps its ledger keys, so existing history is not replayed.