Skip to content
PtahPtah
Edit this pagePropose a change on GitHubView sourceOpen the source used for this buildReport a documentation issueOpen a prefilled GitHub issue

Direct schema changes

You have a description of the schema you want and a database that does not match it, and you would rather move the database now than commit a migration file first. In a direct change, Ptah reads the live schema, computes the difference against the desired schema, and executes it. Nothing is written to a migration directory, and nothing is recorded in a revision table.

Direct names how the change lands, not how it was written

Section titled “Direct names how the change lands, not how it was written”

This group is named for how a change reaches the database. ptah migrations generate reads the same desired schema and turns the same difference into a reviewed pair of SQL files, so “declarative” does not separate the two groups. What separates them is whether the difference runs now or is committed as a file first. Choose a workflow covers that decision alongside the independent question of where the change comes from.

The loop

Section titled “The loop”

Four verbs, in the order a change passes through them: read the database, compare it with the desired schema, save the difference for review, run the saved plan.

Terminal window
ptah db read      --db-url "$DATABASE_URL"
ptah schema drift --db-url "$DATABASE_URL" --schema-file schema.sql
ptah schema plan  --db-url "$DATABASE_URL" --schema-file schema.sql --output change.plan.json
ptah schema apply --db-url "$DATABASE_URL" --plan change.plan.json

Only the last step changes the database. ptah schema apply also runs without a saved plan: it computes the change, prints the SQL, and prompts for approval before executing it.

Task Page
Read a live schema as SQL, HCL, JSON, DBML, or Go annotations Inspect a database
See how a database differs, and fail a pipeline when it does Compare and drift
Separate review from execution with a signed plan file Plan and approve changes
Run the change against the database Apply directly

What it costs

Section titled “What it costs”

The live database is the only record of what happened. Run ptah migrations status against a database changed this way and it reports Current Version: 0 and Applied Migrations: 0, whatever the schema now holds. No migration wrote a revision row. Rolling back means computing a new difference toward the schema you want back, rather than replaying a committed down file.

Three surfaces stand in for that history, and they are the whole of the audit trail:

  • --dry-run prints the SQL and changes nothing.
  • A saved plan file records a fingerprint of the state it was computed against, and can require a reviewer’s signature.
  • ptah schema drift fails a pipeline once a database has diverged.

What this group leaves to other pages

Section titled “What this group leaves to other pages”

Writing the desired schema is a separate subject. The formats Ptah reads, and how several of them merge into one, are under Work with a desired schema. Recording each change as ordered files that every environment replays in the same order is Versioned migrations.

Next steps

Section titled “Next steps”