Migrations
Migrations propagate changes you make to your models (adding a field, deleting a model, adding an index) into your database schema. They are generated from your models, stored as TypeScript files in each app, committed to version control, and applied in order. They are dialect-neutral: the same files run on D1, SQLite and Postgres, which is what makes moving between databases a settings change.
The commands
Section titled “The commands”| Command | Does |
|---|---|
ghuri makemigrations [app...] |
Compare models with the migration history and write new migration files. |
ghuri migrate [app] [name] |
Apply (or, with a target name, roll back to) migrations. |
ghuri showmigrations [app...] |
List migrations and whether each is applied ([X] / [ ]). |
ghuri sqlmigrate <app> <name> |
Print the SQL a migration would run. |
Their options:
| Command | Options |
|---|---|
makemigrations |
--name <n>, --empty, --dry-run, --check (exit non-zero if changes are missing migrations; writes nothing), --merge, --no-input |
migrate |
--fake, --fake-initial, --plan, --run-syncdb, --no-input, --database <alias> |
showmigrations |
--plan, --database <alias> |
sqlmigrate |
--backwards, --dialect sqlite|postgresql, --all [--out <dir>], --database <alias> |
--database picks a key of DATABASES (default default), with Django’s semantics. Every
command also accepts the CLI’s global --remote to work against your deployed Cloudflare
resources instead of the local simulation. See the CLI reference for
details.
Migration files
Section titled “Migration files”src/blog/migrations/├── 0001_initial.ts├── 0002_post_summary.ts└── index.ts # generated: exports every migration in orderAn app opts in to migrations with a migrations package (created by ghuri startapp) and a
path, which tells the CLI where to write files:
import { AppConfig } from '@ghuri/core'import * as migrations from './migrations'import * as models from './models'
export class BlogConfig extends AppConfig { name = 'blog' path = import.meta.dirname // CLI only: where migrations/ lives models = models migrations = migrations // the generated index: works on Workers (no file system)}A migration is a Migration with dependencies and a list of operations:
import { Migration, operations as ops } from '@ghuri/orm/migrations'
export default new Migration({ dependencies: [['blog', '0001_initial'], ['auth', '0001_initial']], operations: [ ops.AddField({ modelName: 'Post', name: 'summary', field: { type: 'CharField', maxLength: 300, blank: true, default: '' }, }), ops.AddField({ modelName: 'Post', name: 'slug', field: { type: 'SlugField' }, oneOffDefault: 'post', // fills existing rows; not kept on the field }), ],})Fields are written as plain data ({ type, ...options }), produced by each field’s
deconstruct(). Migrations therefore do not import your models: they describe the state of the
schema at that point in history, which is what lets old migrations keep working after the models
have moved on. Index and constraint names are always written out explicitly.
The index.ts file exists because Workers have no filesystem. makemigrations regenerates it
every time (it exports every migration plus an ordered migrations map), and
AppConfig.migrations imports it, so migrations are part of your bundle.
What makemigrations detects
Section titled “What makemigrations detects”- Created, deleted and renamed models and fields; altered fields; many-to-many fields.
Meta.indexes,Meta.constraints,uniqueTogether,dbTableand other Meta options.- Dependencies between apps (
['auth', '0001_initial']). Foreign-key cycles between apps are split into two migrations.
It is interactive by default. When a field or model disappears and a similar one appears, it
asks whether you renamed it, so you get RenameField / RenameModel instead of losing data.
When you add a NOT NULL field without a default (or make a field NOT NULL), it asks for a
one-off default to fill existing rows, stored as oneOffDefault on the operation. Callable
defaults (default: () => ({})) are evaluated once to fill existing rows, and
autoNow/autoNowAdd fields get the current time.
With --no-input, renames are treated as a removal plus an addition. A new NOT NULL field
without a default is an error; making an existing field NOT NULL only prints a warning,
and the migration will fail if NULL rows remain. Edit the generated file if you need a rename
in a non-interactive run, or call makeMigrations({ questioner: new NonInteractiveQuestioner({ renames: true, defaults: { 'blog.Post.slug': 'post' } }) })
from code.
Names follow Django: 0001_initial, 0002_post_slug, 0003_remove_post_body, or
auto_YYYYMMDD_HHMM when no better name fits. --name overrides the part after the number.
Operations
Section titled “Operations”| Operation | Purpose |
|---|---|
CreateModel, DeleteModel, RenameModel |
Tables |
AlterModelTable, AlterModelOptions |
Table name, Meta options (ordering, verbose names, permissions) |
AddField, RemoveField, AlterField, RenameField |
Columns |
AddIndex, RemoveIndex |
Indexes |
AddConstraint, RemoveConstraint, AlterUniqueTogether |
Constraints |
RunSQL({ sql?, sqlite?, postgresql?, reverse?, stateOperations? }) |
Raw SQL, per dialect |
RunCode(forwards, backwards?) |
Data migrations in TypeScript |
RunSQL takes SQL for both dialects (sql) or per dialect; a dialect without SQL is skipped,
which keeps the migration portable. reverse makes it reversible (ops.RunSQL.noop for a
reversible no-op), and stateOperations tells the autodetector what schema change the SQL made:
ops.RunSQL({ sqlite: "UPDATE blog_post SET slug = lower(title) WHERE slug = ''", postgresql: "UPDATE blog_post SET slug = lower(title) WHERE slug = ''", reverse: ops.RunSQL.noop,})Data migrations
Section titled “Data migrations”To change data rather than schema, create an empty migration and add a RunCode operation:
npx ghuri makemigrations blog --empty --name backfill_summariesimport { Migration, operations as ops } from '@ghuri/orm/migrations'
export default new Migration({ dependencies: [['blog', '0002_post_summary']], operations: [ ops.RunCode( async (apps, conn, { using }) => { const Post = apps.getModel('blog', 'Post') // or apps.getModel('blog.Post') for await (const post of Post.objects.using(using).filter({ summary: '' })) { post.summary = String(post.body).slice(0, 280) await post.save({ updateFields: ['summary'], using }) } }, ops.RunCode.noop, // reversible as a no-op ), ],})Always use apps.getModel() inside RunCode. It returns a historical model that matches the
schema at this point in the migration history, not your current class, which may have fields
the database does not have yet. Custom methods are not available on historical models.
The second argument is the Connection, for raw SQL inside the same migration
(await conn.execute('UPDATE ...')), and the third carries the database alias (using) being
migrated. Pass using on to queries so the migration works with --database.
Swappable models in migrations
Section titled “Swappable models in migrations”Relations to a swappable model are written through its
setting, so a reusable app’s migrations work whichever model the project picked (Django’s
settings.AUTH_USER_MODEL and swappable_dependency()):
import { Migration, operations as ops, swappableDependency, swappableModel } from '@ghuri/orm/migrations'
export default new Migration({ dependencies: [['blog', '0001_initial'], swappableDependency('AUTH_USER_MODEL', 'auth.User')], operations: [ ops.AddField({ modelName: 'Post', name: 'editor', field: { type: 'ForeignKey', to: swappableModel('AUTH_USER_MODEL', 'auth.User'), onDelete: 'CASCADE' }, }), ],})makemigrationswrites these for every relation to a model named by a swappable setting (auth.User, or your user model whenAUTH_USER_MODELpoints at it). Existing migrations that name the model directly keep working.swappableModel(setting, default)reads as the label the setting names when the migration runs.swappableDependency(setting, default)depends on the migration that creates that model (else on the first migration of its app, Django’s__first__). It is ignored when it names the migration’s own app, it falls back to__first__when the creating migration itself depends on this one, and an already applied migration is not reported as an inconsistent history because of it.- A
CreateModelwithoptions.swappable(written for models withMeta.swappable) is skipped when the setting names another model, together with every later operation on that model, so the swapped model gets no table.
Dialects: D1, SQLite and Postgres
Section titled “Dialects: D1, SQLite and Postgres”Operations are dialect-neutral; a schema editor per dialect turns them into SQL.
- Postgres uses plain
ALTER TABLE ... ALTER COLUMN TYPE / SET NOT NULL / SET DEFAULT, named unique and check constraints, andDEFERRABLE INITIALLY DEFERREDforeign keys. Each migration runs in a transaction together with itsghuri_migrationsrecord. - SQLite and D1 use
ALTER TABLE ... ADD / DROP / RENAME COLUMNwhere SQLite allows it. Anything else (changing a column, unique /NOT NULL/ foreign-key columns, check constraints) rebuilds the table like Django’s SQLite backend, in a D1-safe way: D1 cannot disable foreign keys, so Ghuri setsPRAGMA defer_foreign_keys = ON, copies the rows through a temporary table, recreates the table and its indexes, and copies the rows back. Data is kept.
Check what will run before applying a migration to a big D1 table:
npx ghuri sqlmigrate blog 0004 --dialect sqlitenpx ghuri sqlmigrate blog 0004 --dialect postgresql --backwardsSignals
Section titled “Signals”migrate sends preMigrate before and postMigrate after applying migrations, once per
installed app, with the AppConfig as sender and { appConfig, using, plan } as arguments.
@ghuri/auth uses postMigrate to create content types and permissions. postMigrate is
also sent after flush and by setupTestDatabase() in tests.
import { postMigrate } from '@ghuri/orm'
postMigrate.connect(async ({ appConfig, using }) => { if (appConfig.appLabel === 'blog') await ensureDefaultCategories(using)})Applying migrations in production
Section titled “Applying migrations in production”On Cloudflare:
npx ghuri migrate --remoteIf you would rather let Wrangler own migrations (for example in a CI pipeline that already runs
wrangler d1 migrations apply), export plain SQL files:
npx ghuri sqlmigrate --all --out migrations-sqlnpx wrangler d1 migrations apply DB --remoteand point migrations_dir in wrangler.jsonc at that directory. sqlmigrate --all writes one
numbered file per migration in dependency order (0001_blog_0001_initial.sql, …), using the
SQLite dialect unless you pass --dialect. Each file also inserts its own ghuri_migrations
row, so ghuri showmigrations agrees with what Wrangler applied. Re-running it only adds files
for new migrations; existing numbers never change. Still, pick one way of applying migrations
per database: Wrangler records applied files in its own table and does not read
ghuri_migrations.
On Node with Postgres, run npx ghuri migrate as a release step before starting the new
version. See Node and Postgres. With several databases
configured, migrate each one: npx ghuri migrate --database pg.
Existing databases: --fake and --fake-initial
Section titled “Existing databases: --fake and --fake-initial”migrate --fake records migrations as applied without running them, for when the schema
already matches. migrate --fake-initial fakes only initial migrations whose tables already
exist, which is handy when adopting migrations on an existing database. migrate --plan shows
what would run without running it, and --run-syncdb creates tables for apps that have no
migrations.
Rolling back
Section titled “Rolling back”migrate with an app and a migration name migrates to that state, unapplying later migrations:
npx ghuri migrate blog 0002 # unapply 0003 and laternpx ghuri migrate blog zero # unapply everything in blogOperations generated by makemigrations are reversible. RunSQL needs a reverse and
RunCode needs a backwards function to be reversible; otherwise rolling back past them raises
IrreversibleError.
Working in a team
Section titled “Working in a team”- Commit migrations with the model changes that produced them.
- If two branches both add a migration to the same app,
migrateandmakemigrationsreport conflicting leaf nodes. Runnpx ghuri makemigrations --mergeto generate a merge migration that depends on both leaves, as in Django. - Run
npx ghuri makemigrations --checkin CI to fail when someone changed models without generating a migration. - Never edit a migration that has been applied somewhere you do not control. Write a new one.
Programmatic API
Section titled “Programmatic API”@ghuri/orm/migrations is Workers-safe (no file system access), so you can migrate from code,
for example in a scheduled job or a test:
import { makeMigrations, migrate, showMigrations, sqlMigrate } from '@ghuri/orm/migrations'
await migrate({ using: 'default' })await migrate({ appLabel: 'blog', target: 'zero' })const statements = await sqlMigrate('blog', '0002', { dialect: 'postgresql' }) // string[]const status = await showMigrations() // [{ app, name, applied, dependencies }]await makeMigrations({ dryRun: true }) // writing files needs @ghuri/orm/commands (Node)The same entry point exports the building blocks: Migration, operations, ProjectState /
StateApps, MigrationLoader, MigrationGraph, MigrationExecutor, MigrationRecorder,
MigrationAutodetector, MigrationWriter, sqlMigrateAll, the schema editors, and the data
helpers dumpData, loadData, flushDatabase and copyData. @ghuri/orm/commands (Node
only) exports the command classes, registerOrmCommands(), which adds them to core’s command
registry, and setMigrationImporter(), which replaces how migration files are imported from
disk.