diffScenarios
diffScenarios(before, after, probes)
Runs identical query probes against both isolated PGlite instances and reports exactly what differs.
Does your migration refactor change anything it shouldn't?
PGlite made spinning up a real Postgres in a test fast enough to do per-test. When you refactor a migration history, the risky question isn't does the new migration run -- it's does it produce exactly the same query-visible results as what it replaced?
pglite-diff answers one question: does this refactored migration path produce the same query results as the one it replaces?
Same probes, two isolated Postgres instances
diffScenarios runs each query probe against both isolated PGlite instances and returns a report distinguishing setupError (one side failed to even build) from per-probe beforeError/afterError.
src/diff.ts
import { diffScenarios } from "pglite-diff";
const report = await diffScenarios(
{ setup: originalMigrationSql },
{ setup: refactoredMigrationSql },
[{ name: "subscription pricing",
sql: "select plan, monthly_price from subscriptions order by id" }]
);
if (!report.ok) console.error(JSON.stringify(report, null, 2));One function, real Postgres underneath
report.ok
report.ok: boolean
False if any probe's results differ between before and after.
setupError vs probe error
report.setupError / probe.beforeError / probe.afterError
Distinguishes a broken migration from a broken query.
Why this exists
Existing open-source Postgres migration tools -- Flyway, Liquibase, Atlas, Sqitch, pgroll, graphile-migrate -- all handle applying migrations. None diff two migration paths' resulting data against each other. This closes that gap using real PostgreSQL compiled to WASM, no Docker required.
Also ships as a GitHub Action, published on the GitHub Marketplace, for CI use on migration PRs.
before: migrations 1..N (PGlite, in-process)
after: migrations 1..N+1 (PGlite, in-process)
diffScenarios() → row/shape diff: regression
caught before it touched a real database
What pglite-diff doesn't do
- Doesn't apply migrations for you.You already have a migration runner -- this diffs the results.
- Not a schema-diff tool.It compares query results, not raw DDL.
- Doesn't fix the regression.It tells you exactly what changed; fixing it is your call.