Migrations guide
ruprizzle generates migrations by diffing your current schema.ruprizzle
against the state of the migration history. You edit the schema, run a command,
and the tool writes, applies, and tracks the SQL for you.
The two commands
| Command | When to use | What it does |
|---|---|---|
ruprizzle migrate dev | Local development | Diff schema → write migration files → apply → regenerate client. |
ruprizzle migrate deploy | CI / production | Apply pending migrations/*.sql files only. |
These are deliberately separate. deploy never writes migration files, prompts,
or diffs the schema, so a habit of running migrate deploy cannot accidentally
drop a production column.
Development workflow
# 1. Edit schema.ruprizzle
# 2. Create, apply, and regenerate the client
ruprizzle migrate dev --name add_profile
# If the migration would lose data and you accept it:
ruprizzle migrate dev --name drop_legacy --accept-data-loss
# Write the migration without applying it:
ruprizzle migrate dev --name draft --create-only
migrate dev is the only command that diffs, writes, and applies. Every other
command is read-only or apply-only.
Backfills
Adding a NOT NULL column without a default requires a three-step migration:
- Add the column as nullable.
- Fill existing rows (
RUPRIZZLE:BACKFILLblock in the generatedup.sql). - Alter the column to
NOT NULL.
Edit the generated up.sql and replace the placeholder expression before
applying. The RUPRIZZLE:BACKFILL block is preserved when you re-run
migrate dev.
Drift and migrate status
ruprizzle migrate status introspects the live database and compares it to the
migration history. If someone hand-edited the database, it reports the
differences.
ruprizzle migrate status
Resolve drift by either:
- writing a new migration that brings the schema back into sync, or
ruprizzle migrate reset --forcein development to drop everything and replay.
Prototyping: db push
ruprizzle db push
# If the change would lose data:
ruprizzle db push --accept-data-loss
This diffs and applies directly with no migration file. It is intended for prototyping only and prints a warning every time. Do not use it in production.
Introspection: db pull
db pull reads an existing database and generates a schema.ruprizzle from it.
Use it to adopt an existing database or to inspect a schema that was not created
by ruprizzle.
ruprizzle db pull
The command will:
- read the live database from
DATABASE_URL, - generate a
schema.ruprizzlethat describes the current tables, columns, indexes, and foreign keys, - overwrite
schema.ruprizzlein place (review the diff before committing).
Review the generated schema before committing it. Names and types may need manual cleanup, especially for columns that do not map cleanly to ruprizzle scalar types.
Seeding: db seed
db seed loads fixture data from a JSON file and upserts it by primary key.
- Create
seeds/main.jsonnext toschema.ruprizzle:
{
"User": [
{ "id": 1, "email": "alice@example.com", "name": "Alice" },
{ "id": 2, "email": "bob@example.com", "name": "Bob" }
]
}
- Run:
ruprizzle db seed
Seed rows are upserted by primary key in a single transaction. The legacy
seeds/main.sql file is also supported if no seeds/main.json exists. The
client is not regenerated; run ruprizzle generate afterwards if you added new
models.
migrate squash
Squashing collapses the existing migration history into a baseline and archives
the old up.sql / down.sql files.
# Use an auto-generated baseline name:
ruprizzle migrate squash --force
# Or name the baseline explicitly:
ruprizzle migrate squash --name baseline --force
Requirements:
- the migration history must be fully applied,
- all checksums must be valid,
- the database must be in the exact state described by the final migration.
This rewrites history; pass --force to confirm. Old migrations are archived
under migrations/.archive/ and a new baseline migration is created.
migrate resolve
If a migration was partially applied or failed outside ruprizzle, you can mark it as applied without re-running it.
ruprizzle migrate resolve 20260101000000_broken
Use this only after manually inspecting the database and confirming it is in the state the migration would have produced.
migrate reset
Drop the database and replay the full migration history from the beginning.
ruprizzle migrate reset --force
This is destructive and --force is required. It is intended for development
prototyping only.
Running migrations in CI / production
In CI and production, use migrate deploy.
ruprizzle migrate deploy
This command:
- reads
migrations/in order, - skips migrations that are already recorded in the
_ruprizzle_migrationstable, - applies each pending
up.sqlinside a transaction, - never diffs or writes new migration files.
A typical container deploy looks like this:
# Build the application image first
...
# At container start, before binding the port:
CMD ["sh", "-c", "ruprizzle migrate deploy && exec ./my-app"]
Destructive changes and --accept-data-loss
migrate dev will stop and warn when a change would drop data, such as:
- dropping a column,
- dropping a table,
- changing a
NOT NULLcolumn to nullable and then back, - narrowing a
BigInttoIntwhere values may not fit.
Pass --accept-data-loss when the loss is intentional in development.
The 12 change classes
The migration engine is tested against all common schema changes:
- Add / drop a model
- Add nullable column
- Add
NOT NULLcolumn with default - Add
NOT NULLcolumn without default - Drop column
- Widen / narrow
Int↔BigInt - Nullable →
NOT NULL - Add / drop index or unique
- Add / drop foreign key
- Add / drop enum variant
- Rename column / model (with
@renamedFromor heuristic detection) - Add / remove default expression
Rename detection
Renames are detected by comparing column/model fingerprints. If ruprizzle is
confident, it suggests a RENAME change. If you know a rename happened, use
@renamedFrom in the schema:
model User {
email String @renamedFrom("email_address")
}
Without @renamedFrom, the engine may produce a DROP + ADD pair, which
loses data. Always review renames.
If the new name is already taken by a column that still exists — for example
email is renamed to legacy_email in the database you are migrating, and a new
email field says @renamedFrom("email_address") — the existing email column is
dropped first and then email_address is renamed onto its name (since 1.6; earlier
versions planned a RENAME that failed at apply time). The drop is destructive, so
migrate dev / migrate deploy require --accept-data-loss for it. Copy anything you
need out of the old column before applying.
Mutual foreign-key cycles
If two or more models reference each other in a closed loop, the migration planner will:
- add
DEFERRABLE INITIALLY IMMEDIATEto the generated foreign key constraints; - wrap the
up.sqlwith a backend-specific command that defers enforcement until the end of the migration transaction; - add the matching re-enable command before
COMMIT.
The generated SQL is:
| Dialect | Preamble | Postamble | down.sql behaviour |
|---|---|---|---|
| Postgres | SET CONSTRAINTS ALL DEFERRED; | SET CONSTRAINTS ALL IMMEDIATE; | DROP TABLE ... CASCADE for cycle tables |
| SQLite | PRAGMA defer_foreign_keys = ON; | PRAGMA defer_foreign_keys = OFF; | PRAGMA foreign_keys = OFF; before drops, then PRAGMA foreign_key_check; and PRAGMA foreign_keys = ON; |
| MySQL | SET FOREIGN_KEY_CHECKS = 0; | SET FOREIGN_KEY_CHECKS = 1; | SET FOREIGN_KEY_CHECKS = 0/1 around drops |
This lets you create, populate, and roll back schemas with cyclic foreign keys without having to split them across multiple migrations by hand.
SQLite migration notes
SQLite handles some of the change classes (notably type changes and NOT NULL
transitions) by rebuilding the table. Postgres uses direct ALTER statements
where possible. MySQL uses ALTER TABLE and MODIFY COLUMN.
Best practices
- Commit
migrations/with the same PR that changesschema.ruprizzle. - Run
ruprizzle migrate deployin CI before running the application. - Never run
migrate devon a production database. - Review
up.sqlanddown.sqlbefore applying destructive changes. - Use
--create-onlyto draft a migration for review in a team PR.