Know who breaks before a schema change ships.

• Directional, not just “changed”

  Every finding says whether old data still reads under the new schema, and whether new data still reads under the old one. Unknown stays unknown.

• Plans, not just warnings

  Changes become expand, migrate and contract steps. Backfill values are never invented; you get a commented template.

• Policy decides the verdict

  Findings never change. Your policy sets severity, so one report can gate a deploy strictly and a review loosely.

• JSON Schema

  Properties, requiredness, types, nullability, enums, bounds, patterns, $ref and composition, with local $ref resolved.

• PostgreSQL DDL

  Tables, columns, constraints, indexes and enums. SQL is generated for PostgreSQL only; other dialects are rejected, not guessed.

• Built for CI

  Stable rule IDs, deterministic JSON and exit codes 0, 1 and 2. Same inputs and policy always give the same report.

Plans are suggestions for review. They can’t know your data volume, lock contention or deployment order. Read the limitations →

1. 1

   Compare two files

   The format is inferred from the extension. Exit codes tell your pipeline what happened.

   sh

   # JSON Schema, inferred from .json
   schemabridge compare schema-v1.json schema-v2.json
   
   # PostgreSQL DDL, requiring both directions to hold
   schemabridge compare schema-v1.sql schema-v2.sql --compat full
   
   # For CI: structured output and a gating exit code
   schemabridge compare old.json new.json --json > report.json
   echo $?   # 0 passed · 1 policy violated · 2 input error

2. 2

   Or call the API

   Pass paths, raw text or parsed values. The report is plain data you can filter and test.

   ts

   import { compareSchemas, formatReport, exitCodeFor } from "schemabridge-diff";
   
   const report = await compareSchemas({
     previous: "./schema-v1.json",
     current: "./schema-v2.json",
     policy: { compatibility: "backward", destructiveChanges: "error" },
     renames: { properties: { "$.user.name": "fullName" } },
   });
   
   console.log(formatReport(report));
   process.exitCode = exitCodeFor(report);
   
   for (const f of report.findings) {
     console.log(f.ruleId, f.severity, f.path, f.backward, f.forward);
   }

3. 3

   Gate the pull request

   Check out the previous schema, compare, and let the exit code decide.

   yaml

   - name: Check schema compatibility
     run: |
       git show origin/main:schema/users.sql > /tmp/previous.sql
       npx schemabridge compare /tmp/previous.sql schema/users.sql \
         --config schemabridge.config.json

   json

   {
     "format": "postgres-ddl",
     "policy": {
       "compatibility": "backward",
       "destructiveChanges": "error",
       "failOn": "error",
       "rules": { "SB-S019": "off" }
     },
     "renames": {
       "columns": { "users.fullname": "full_name" }
     }
   }

• --compat backwardOld data must stay valid. The default.
• --compat forwardNew data must be readable by old consumers.
• --compat fullBoth directions. Almost any real change fails.
• --compat strictAssert two schemas are equivalent.
• --compat noneList changes without ever failing a build.

See every policy option →