pithy migrate

Run every Worker’s migration registry against one environment’s D1 as one named group, or reverse the group a previous run applied.

Synopsis

pithy migrate [--env <env>] [--worker <name>] [--binding <binding>] [--group <value>]
              [--rollback] [--confirm-rollback <phrase>] [--destroy-retained <n>] [--dry-run] [--json]

Flags

FlagMeaning
--env <env>Target environment: dev, staging, prod, or one you declared. Default dev
--worker <name>Migrate one Worker instead of every Worker under apps/
--binding <binding>Migrate only the database behind this D1 binding. Combines with --worker. A binding nothing in scope declares is refused by name
--group <value>Name the group this run applies under, instead of the ISO-8601 timestamp it would generate. On --rollback, the group to reverse — required
--rollbackReverse the --group named, in every database in scope, instead of running forward. Refuses without a group. Narrow it with --worker and --binding. Default false
--confirm-rollback <phrase>Unlock a non-dev rollback non-interactively: the exact phrase yes, i really want to roll back <env>
--destroy-retained <n>DESTRUCTIVE. Let a rollback drop rows in retained tables. Must equal the row count the refusal printed
--dry-runShow the plan and write nothing: the migrations the run would apply, or on --rollback reverse, with every refusal the run makes. Needs no --confirm-rollback. Default false
--jsonMachine-readable output. Default false

What it does

The registry, the ordering and the per-database runs are identical everywhere. Only the driver differs: dev runs locally through Miniflare against .wrangler/state — the same store wrangler dev reads — while staging, prod and any custom environment execute over the D1 REST API against the database that environment’s wrangler.jsonc stanza names. You pass no ids.

It fans out over Workers, and a shared database migrates once. Each Worker contributes its own capabilities’ migrations. Workers whose bindings resolve to the same physical D1 are grouped, their sets merged into one ordered provider, and that provider runs a single time — then each result is credited back to the Worker whose capability declared it, so the report never claims a migration a Worker does not own.

--worker narrows what is reported and which databases are visited. It never narrows the registry a visited database runs, because a shared D1’s ledger holds both Workers’ migrations and a partial provider reads as corrupted state.

Every run is idempotent. A second run with nothing pending is a no-op, and each Worker’s line reads nothing to apply. A project whose Workers bind no database prints Nothing to migrate.

Every run belongs to a group, and a successful run prints it. --group <value> takes any string you hold — a release stamp, a build id — and the run records it against every migration it applies, in every database it touches. One run is one group, however many databases and migrations it spans. A run that names none is stamped with the moment it ran: Group: 2026-10-03T19:52:47.611Z. Passing the same value twice extends that group, which is how a release whose migrate half-failed is retried; a generated group never extends.

The group lives in pithy_migrations_groups, beside the ledger and the owner stamp. Like the owner stamp, the table is not a migration, so a rollback and seed --redo’s full reset leave it standing.

It composes each Worker for the environment it migrates. A pithy.config.ts is code, and compositionEnvironment() answers staging while pithy migrate --env staging evaluates it — exactly as it will inside the deployed Worker. So a config whose migrations differ by environment is migrated with the target environment’s set, and pithy upgrade --env and pithy deploy --env’s pending count count that same set.

It says what it is on, while it is on it. On a remote environment every statement is a D1 round trip, so a run against a fresh database takes minutes, and it used to print nothing until it had finished. You cannot tell a slow schema change from a hung one, and the instinct is Ctrl-C in the middle of it. So each step is named as it starts, one plain line each: the check every database gets before the first write, ▸ Checking DB, SECRETS...; each database and the Workers it serves, ▸ DB (app) for api, collab...; and each migration, ▸ Applying 0300_auth_0001_init to DB... or, on a rollback, ▸ Rolling back 0300_auth_0001_init on DB.... The last ▸ line of an interrupted run names what was in flight. The per-Worker report still prints once, at the end, unchanged. A missing TTY gets the same lines, because a run in CI is the run whose log most needs them. --json prints none of them.

A database has to exist before it can be migrated, which is pithy provision’s job — and provisioning ends by running this command, so the two are usually one act.

The database has an owner. Every database in the run is claimed for this project — a row beside the migration ledger — before any of them is written to, and a database another project owns aborts the whole run rather than being discovered halfway through. An unstamped database is adopted on first migrate; your own is a no-op.

This is why migrate needs name in the root pithy.config.ts and refuses to guess one. A guessed name would stamp one value and check a different one next run, locking a project out of its own database.

The ledger has to match the declaration, in both directions. Before anything is written, every database in the run is read back. A migration this project declares and the database has not applied is what the run applies. A migration the database has applied that nothing declares any more is refused by name.

That second state is what deleting a migration file leaves behind, and Kysely treats it as a corrupted chain — so nothing can migrate until the two agree. No migration is broken there, so the remedy is not fix the migration: on dev it is to delete .wrangler/state and run again, and on a deployed environment it is to restore the migration or remove its pithy_migrations row, because that database has real rows in it. pithy doctor reports the same state before you reach for migrate.

Declared secret tables: it writes the migration, and stops

A Worker that declares secret tables (defineSecretTable, composed through secretTablesDatabase — see Declared tables) gets their migrations written for it. Before anything is applied, a forward run diffs each declaration against the chain that Worker composes. A table the chain has never seen, or one that gained a key, gained a secret name or lost one, gets the next migration written into apps/<worker>/migrations/secrets/, and that directory’s index.ts is rewritten from the listing. A secret name removed from the declaration leaves the table’s registration, printed as - secret NAME; rows already holding it stay as they are. Then the run stops, whichever of these it wrote:

$ pithy migrate --env dev
Declaration changed: customer
  + key     teamId

Wrote apps/api/migrations/secrets/0002_customer_team_id.ts
Review it, then run migrate again.

Secret-table migrations written. Nothing was applied.
Review and commit what it wrote. Then run `pithy migrate --env dev` to apply it.

It writes and never applies in the same pass. The file is yours to read before it runs, and running pithy migrate again applies it. So the run ends core/person_required, exit 5, on every environment, and never with Done.: nothing was applied, and pithy migrate --env prod && pithy deploy --env prod must not go on to deploy over a schema missing what the file adds. In CI that is the point — a file written in a CI checkout is in no deployed chain, so the job stops and a person commits it. Under --json the report is still the stdout line, with generatedMigrations, and the refusal is the stderr line. --dry-run writes nothing and exits 0.

A declaration that matches its chain writes nothing and migrates normally, so running twice writes one file, not two. The chain stays append-only: the next change is a new file, never an edit to one that has shipped. A generated file is an ordinary migration once written. A hand-written one in the same directory — default-exporting its migration under the same NNNN_slug.ts naming — runs only once you import it in index.ts and add it to secretTableMigrations yourself. From then on it stays in the index and counts toward the next number. Dropped in without that, it is the second refusal below.

Three things are refused before anything is written, each naming what to change:

  • A key column removed or renamed. A rename reads as a removal beside an addition, and a migration that drops a column holding somebody’s key is a data loss you author on purpose. The refusal names the key.
  • A migration file in migrations/secrets/ that the Worker’s config does not compose — written, and secretTableMigrations never passed to secretTablesDatabase, or written by hand and never added to index.ts. Diffing against a chain missing it would write it again. The refusal names the file, and which of the two to fix.
  • One table declared by two Workers. One Worker owns a table’s migrations; another reads it with .table(T), which needs the declaration alone.

--dry-run says which files it would write and writes none. --rollback never generates.

Rolling back

A rollback names the group it reverses, and pithy migrate --rollback on its own reverses nothing. It refuses, names the group on top, says what reversing it would undo, and names the command that does it — as a person’s decision, never as a fix:

$ pithy migrate --rollback
Refusing to roll back without a group. The newest group is 2026-10-03T19:52:47.611Z, applied 2026-10-03 19:52 UTC: DB holds 2000_app_0003_release_notes, EMAIL_SUPPRESSIONS holds 0100_email_0002_reasons.
Reverse it. `pithy migrate --env dev --rollback --group 2026-10-03T19:52:47.611Z` with its --confirm-rollback phrase, which only a person gives, deletes the schema a migration group applied. That is a person's decision, not a fix.

The command it names is your own run, with the group added: every flag you passed is carried, --worker and --binding included, so it reverses the group in exactly the databases your run was scoped to. When the databases in scope hold different newest groups, it says to reverse one database at a time and names the first, by --binding and, where you named no Worker, by --worker.

That is a breaking change, and it is the point. A rollback used to step back one migration in every database in scope, so what one command reversed depended on what each database happened to apply last, and reversing a deploy that moved three migrations took three invocations.

--rollback --group <value> reverses exactly that group — each database’s portion, in reverse chain order, and nothing outside it. A database that holds none of the group is left alone.

Only the group on top can be reversed. Reversing a buried group would mean reversing everything over it, so a request for any other group is refused, naming the group that is actually on top: Only the group on top can be reversed. DB applied release-7 over release-6. A migration applied under no group at all — by an older kit, or by seed --redo — buries the groups beneath it just as another group would, and the refusal names it.

When databases hold different newest groups, the refusal names each one rather than choosing. Reverse them one at a time, narrowed to their own database.

A group reverses completely or not at all. Every refusal condition is checked across every database in the group before the first down — the retained-table count, a database another environment binds, and a migration in the group that declares no down.

--group composes with the narrowing. --rollback --group <v> --binding DB reverses that group’s portion of one database and leaves the rest of the group applied.

Retained tables refuse. Some tables hold rows that exist nowhere else — the secrets vault (pithy_secrets_system_secrets, pithy_secrets_rotations, and every declared secret table) and the email suppression list (pithy_email_suppressions). Their capability declares them retained. A globally installed pithy reads that declaration through its own copy of core, so a project on @pithy-sh/core older than 0.20.1 upgrades it, or the rollback finds no retained table to refuse over. Before anything moves, a rollback counts every retained table in the databases the group reverses, and if one holds rows it refuses, naming each table and the total:

$ pithy migrate --rollback --group 2026.10.3-1
Retained 5 rows would be dropped: pithy_secrets_system_secrets on SECRETS (5 rows). Refused before any down against them ran.
They exist nowhere else. Back them up, or pass --destroy-retained 5 to drop them.

The refusal is database-wide. Any down against a database holding retained rows is refused, even one that never touches them, because a down cannot be inspected without running it. --destroy-retained takes the number, not a yes: it must equal the count, so a flag typed for another run does not agree to this one. One budget is spent across the whole group, so an agreement to five rows cannot destroy five in every database. The same refusal stands under the migration runner itself, so pithy seed --redo and pithy remove --drop meet it too.

A database other environments bind is never reversed. EMAIL_SUPPRESSIONS is one database, bound by every environment’s stanza. A --env staging rollback reversing it would reverse production’s suppression list. A group that holds part of such a database is refused whole — EMAIL_SUPPRESSIONS is bound by prod too. A staging rollback of group release-7 does not reverse it. — because the group cannot come down completely. A group that holds none of it leaves it alone and says so: EMAIL_SUPPRESSIONS kept. prod binds it too.

Outside dev, a rollback is asked for in words. The phrase names its environment, so one typed for staging cannot be pasted into a command aimed at prod. Interactively the prompt asks; in CI pass --confirm-rollback. A run that may not ask — --json, --no-input, PITHY_NONINTERACTIVE=1, or no terminal — and passed no phrase, or a wrong one, is refused core/person_required, exit 5. The phrase is a person’s to give, so an agent stops and asks rather than trying variations.

After a rollback fails partway, fix the down before anything else. The databases that already moved stay moved. Each migration’s group row is forgotten as it comes down, so re-running the same --group reverses what is left of it and nothing else — but pithy doctor is what shows where each database stands first.

Seeing it first: --dry-run

--dry-run lists what the run would move, and moves nothing. It reads each database exactly as the run reads it before the first write — the ledger refusal, the group check and the retained count all stand, so a plan for a run that would be refused is refused — and then names, per database, the migrations the run would apply, or on --rollback the group’s own, newest first. It claims no database. In dev it reads a copy of the local store, because opening a Miniflare store can write to it. It asks for no rollback phrase, because nothing it plans comes down.

$ pithy migrate --env staging --dry-run
▸ Checking DB...
Would apply 1000_app_0002_more to app (DB, staging).
Dry run. Nothing written.

Migrate never seeds and never deploys. It moves the schema your capabilities and your app declare. Data fixtures are pithy seed; shipping code is pithy deploy, which warns when the target environment’s schema is behind but never migrates for you.

Credentials for a remote run are CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, from a session pithy cloudflare connect bound to this directory, or else <config>/cloudflare.json locally — or straight from the environment in CI, which has no config file. A dev run needs neither.

--json

One line on stdout, whose workers array groups the run exactly as the human output does. A failure is one {"error": …} line on stderr, and the process exits by its class.

KeyTypeMeaning
commandstring"migrate"
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
projectstringThe project this run was claimed as — name from the root pithy.config.ts
envstringThe environment migrated
rollbackbooleanWhether the run reversed a group rather than running forward. Mirrors --rollback
groupstringThe group this run applied under, or reversed — the --group value, or the timestamp the run generated. Absent from a forward --dry-run that names no --group
dryRunbooleanWhether this was --dry-run. Nothing was applied or reversed when it is true
workersobject[]One entry per Worker in the fan-out, in report order. A Worker with no migrations still appears
workers[].workerstringThe Worker’s name
workers[].databasesobject[]The databases that Worker’s registry touched, in registry order. Empty when it composes no migrations
workers[].databases[].databasestringThe database name — a capability’s databases key
workers[].databases[].bindingstringThe D1 binding it resolves to in that Worker’s wrangler.jsonc
workers[].databases[].resultsobject[]What the migrator did, credited to this Worker. Empty when nothing moved, and empty under --dry-run
…results[].migrationNamestringThe composed migration name, carrying its capability namespace
…results[].directionstring"Up" or "Down"
…results[].statusstring"Success", "Error", or "NotExecuted" — the last meaning an earlier migration failed first
workers[].databases[].sharedWithstring[], optionalThe other Workers bound to this same physical D1. Present only when the database is shared
workers[].databases[].boundBystring[], optionalThe other environments whose stanzas bind this same database. Present only on a rollback that kept it for that reason; its results is empty
generatedMigrationsobject[], optionalPresent only on a run that wrote declared secret-table migrations and stopped — or, under --dry-run, would write them. Each entry names the worker, the table, the change (create or alter), the file relative to the project root, and the addedKeys, addedSecrets and removedSecrets. workers is empty beside it, because nothing was applied
planobjectPresent only under --dry-run: plan.migrations names each migration the run would apply (up) or reverse (down), with its environment, Worker, database and binding

A run that died partway

A fan-out has no transaction across databases: the third one throws and the first two are already ahead of it. So the failure line still goes to stderr and the exit is still non-zero, and stdout carries what the run changed on the way — the record you need most when a migration dies mid-fan-out.

$ pithy migrate --env staging --json
{"command":"migrate","schemaVersion":2,"project":"acme","env":"staging","rollback":false,"group":"2026-10-03T19:52:47.611Z","dryRun":false,"workers":[…],"failed":{"binding":"COLLAB_DB","database":"collab"},"unreached":[{"binding":"MEDIA_DB","database":"media"}],"interrupted":true}
KeyTypeMeaning
interruptedbooleanPresent and true on this line alone. It is what says workers is a truncated report, not a whole one
workersobject[]Here, only the databases whose pass completed before the failure. Same shape as above
failedobjectThe database the run died on, as its binding and database. Its schema is in whatever state the failed pass left it. No reason — what a migration threw is on the {"error": …} line
unreachedobject[]Every database in scope the run never opened, in fan-out order. Empty means the failure was on the last one, never nothing was scanned

Errors

  • No pithy.config.ts here. Run it from a Pithy project.
  • A migration run needs a project name. Set name in the root pithy.config.ts. The stamp is what refuses another project’s database instead of silently merging two schemas.
  • A database another project owns. The refusal names both projects, and nothing in the run has been written. Nothing clears a stamp: handing a database to another project deliberately means dropping that table by hand.
  • <worker>: wrangler.jsonc has no env.<env> stanza. Add the environment and its D1 bindings. A Worker outside the run’s scope with no stanza for that environment is skipped instead, because it has never migrated there.
  • wrangler.jsonc env.<env> has no database_id for the "<binding>" binding. A remote run needs a real id; there is no local fallback to migrate the wrong store against.
  • Cloudflare credentials are missing. Remote runs only.
  • Two databases on one binding, within a Worker. A wiring mistake — they would migrate against a single physical store. Give each its own binding.
  • Two Workers migrating one binding under one namespace with different migrations. A pair of capabilities wearing one name; their composed keys would collide in the ledger. Rename one, or bind the Workers to different databases.
  • <binding> records <migration>. This project no longer declares it. The ledger holds a migration this project has since dropped, so the migrator refuses the whole chain. The action line says which remedy applies to this database.
  • Refusing to roll back without a group. A --rollback with no --group. The refusal names the group on top and prints the command that reverses it.
  • Only the group on top can be reversed. The group named is buried under another, or under an ungrouped migration. The refusal names what is on top.
  • Retained <n> rows would be dropped: … A rollback reached a database whose retained tables hold rows. Nothing moved. Back them up, or pass --destroy-retained <n> with the printed number. A different number is refused, and says so.
  • <binding> is bound by <envs> too. The group reaches a database another environment binds, so none of it is reversed from one environment.
  • Rolling back <env> reverses a group of migrations in every database it binds. A non-dev rollback without its phrase. Pass --confirm-rollback "yes, i reallywantto roll back <env>". A run that cannot ask is refused core/person_required, exit 5. The phrase is checked before any database is read, so it is answered before a missing --group is.
  • No database in scope is bound to "<binding>". The action lists the bindings this run does have.
  • A migration itself failing. The refusal names the migration, the binding it was running against, and what the runtime actually said. The chain is applied one migration at a time, so detail also carries the migrations applied before it, which stay applied. The failed migration is not among them: each migration’s statements go to D1 as one batch, which is one transaction, so a migration that fails partway applies none of itself and records nothing.
  • --env is validated at the flag. production is answered with prod before any config loads or any database opens, exit 2.

Examples

# Local, the default. Prints the group it applied under.
pithy migrate

# Promote the schema under the release's own stamp, so the rollback command is known in advance.
pithy migrate --env staging --group 2026.10.3-1 --json
pithy migrate --env prod --group 2026.10.3-1 --json

# Reverse that release, every database it touched.
pithy migrate --env prod --rollback --group 2026.10.3-1 --confirm-rollback "yes, i really want to roll back prod"

# Reverse only one database's portion of it.
pithy migrate --env staging --rollback --group 2026.10.3-1 --binding DB --confirm-rollback "yes, i really want to roll back staging"

# One Worker only.
pithy migrate --env prod --worker api --json

# See what a release would apply before it applies it.
pithy migrate --env prod --dry-run

A shared database, reported from both sides:

{"command":"migrate","schemaVersion":2,"project":"acme","env":"prod","rollback":false,"group":"2026.10.3-1","dryRun":false,"workers":[{"worker":"acme-api","databases":[{"database":"app","binding":"DB","results":[{"migrationName":"auth_0001_init","direction":"Up","status":"Success"}],"sharedWith":["acme-collab"]}]},{"worker":"acme-collab","databases":[{"database":"app","binding":"DB","results":[],"sharedWith":["acme-api"]}]}]}

Nothing in that payload is a credential.

ESC