November 4, 20264 min read

How to Evaluate Ptah on an Existing PostgreSQL Database

Try Ptah on a copy of an existing PostgreSQL database: inspect its schema, verify a baseline, generate a migration, and detect drift.

Simon HartSolutions Engineer

Ptah helps you plan, review, and apply database migrations. Try in your browser

An existing PostgreSQL database has application data and a schema created before Ptah entered the workflow. The team wants to evaluate a database migration tool without giving it control of production. We can run Ptah against a disposable copy, inspect the SQL it proposes, and check the result before deciding on a handoff.

In this trial, Ptah 0.17.0 generated a reviewed migration, replayed it forward, back, and forward on a shadow database, and applied it to the copy. The four invoice rows remained intact. Ptah also detected an extra column introduced outside the desired schema. We used PostgreSQL 18.6. The complete example and recorded output are beside this post.

Start from a populated copy

Our sample database has accounts and invoices, a foreign key, an index, and four invoice rows. Its original SQL and seed data stand in for a team’s existing schema and data. We made trial_db from source_db with PostgreSQL’s CREATE DATABASE ... TEMPLATE ...; the setup commands show the copy. All subsequent writes target trial_db or disposable replay databases.

First, let Ptah read what is there and compare it with the original schema file:

ptah schema inspect --db-url "$TRIAL_DB_URL" --schemas public --format hcl > observed.hcl
ptah schema compare --db-url "$TRIAL_DB_URL" --schema-file original-schema.sql --schemas public --exit-code

The captured HCL contains both tables, the foreign key, and the index. The comparison exited 0 with No schema differences detected. That gives us a checked starting point before writing a migration.

Give the copy a verified baseline

We generated an initial migration from the original SQL against empty_db. Ptah replayed the resulting files on shadow_db. Then we previewed the baseline and recorded that migration as already applied on the populated copy:

ptah migrations generate --schema-file original-schema.sql --db-url "$EMPTY_DB_URL" --migrations-dir migrations --name initial --shadow-db "$SHADOW_DB_URL" --schemas public
ptah migrations hash --dir migrations
ptah migrations baseline --db-url "$TRIAL_DB_URL" --migrations-dir migrations --schemas public --shadow-db "$SHADOW_DB_URL" --dry-run
ptah migrations baseline --db-url "$TRIAL_DB_URL" --migrations-dir migrations --schemas public --shadow-db "$SHADOW_DB_URL"
ptah migrations status --db-url "$TRIAL_DB_URL" --migrations-dir migrations --verify-sum --exit-code

Baselined 1 migration(s) through version 1793797179 in "schema_migrations"

The dry run wrote no metadata. The actual baseline replayed the migration on shadow_db and compared its schema with trial_db before recording one revision in the copy. It did not execute the initial CREATE TABLE statements against the populated copy. source_db still had its four invoices and no Ptah revision table. A new run will generate its own version number.

Get the next change from a desired schema

The desired SQL adds optional paid_at and an index for status queries. We asked Ptah for the plan before creating files:

ptah migrations plan --schema-file desired-schema.sql --db-url "$TRIAL_DB_URL" --schemas public

-- Add/modify columns for table: public.invoices
ALTER TABLE "public"."invoices" ADD COLUMN "paid_at" timestamp with time zone;

CREATE INDEX IF NOT EXISTS "invoices_status_idx" ON "public"."invoices" ("status");

Generated 2 migration statements.

The full plan classified both schema changes as safe from data loss. We then generated the up and down files. With --shadow-db, Ptah applied the full history, rolled the new migration back, and applied it again before keeping those files:

ptah migrations generate --schema-file desired-schema.sql --db-url "$TRIAL_DB_URL" --migrations-dir migrations --name invoice_tracking --shadow-db "$SHADOW_DB_URL" --schemas public

Reviewing that SQL is still the team’s decision. In this run, migrations lint flagged that an ordinary PostgreSQL index build can block writes on a populated table. For a busy production table, plan the index rollout accordingly. The lint output is part of the trial record.

Apply on the copy and check the result

After review, we hashed the directory, linted it, previewed the pending execution, and applied the change to trial_db:

ptah migrations hash --dir migrations
ptah migrations lint --dir migrations --dialect postgres --latest 1 --fail-on error
ptah migrations up --db-url "$TRIAL_DB_URL" --migrations-dir migrations --verify-sum --dry-run
ptah migrations up --db-url "$TRIAL_DB_URL" --migrations-dir migrations --verify-sum
ptah schema compare --db-url "$TRIAL_DB_URL" --schema-file desired-schema.sql --schemas public --exit-code
ptah migrations status --db-url "$TRIAL_DB_URL" --migrations-dir migrations --verify-sum --exit-code

The comparison exited 0 with no schema differences. Ptah reported two applied migrations and none pending:

Total Migrations: 2
Applied Migrations: 2
Pending Migrations: 0
Out-of-order Migrations: 0
Status: ✅ Database is up to date

The same data query before and after returned:

 invoices | total_cents | open_invoices
----------+-------------+---------------
        4 |       24700 |             2
(1 row)

The recorded row output also shows all four invoice IDs and values. The catalog comparison records the new column and index. The original database remained unchanged.

Finally, we added an unplanned surprise_note column to the copy and ran schema compare --exit-code again. It exited 1 and named public.invoices as modified:

Differences detected (1 category):
  tables_modified (1): public.invoices

Ptah reported the difference; it did not apply its suggested reconciliation. We removed the test column afterward and the comparison passed again.

Decide whether to adopt Ptah

This trial gives the team concrete artifacts: a captured starting schema, a replayed baseline, reviewed migration files, a dry run, a data check, and an exit code for schema drift. That is enough to decide whether Ptah’s schema-driven workflow fits the next project change. The example directory lets you repeat the same evaluation with a copy of your own database.

Before handing production migration ownership to Ptah, choose who owns the existing history, how the application deploys with a schema change, which role can apply it, and how to recover if deployment stops. Teams arriving from another runner can follow the separate Flyway, Liquibase, or Atlas guides for that handoff. The trial itself requires no production history change.

Put Ptah to work

Example files

← All articles