xata-drift-detection

Detect schema drift between a live PostgreSQL database and a pgstream clone.yaml transformation-rules file.

It compares the database's actual tables/columns against the tables and column_transformers declared in clone.yaml, and reports anything that is out of sync in either direction.

This package ships a small, statically-linked Go binary. The correct prebuilt binary for your platform is installed automatically as an optional dependency — no Go toolchain or compilation required.

Install

npm install xata-drift-detection
# or
pnpm add xata-drift-detection

Usage

detect-drift [schemaSnapshotJson] [cloneYaml] [outputReportJson]

| Argument | Default | Description | | --- | --- | --- | | schemaSnapshotJson | ./prod-state.json | JSON array of { "table_name": string, "columns": string[] } describing the database schema | | cloneYaml | ./clone.yaml | The pgstream rules file to compare against | | outputReportJson | ./drift-report.json | Where the JSON drift report is written |

Example:

# Export the current database schema (one row of JSON):
psql "$DATABASE_URL" -t -A -f query.sql -o prod-state.json

# Compare it against clone.yaml:
detect-drift prod-state.json clone.yaml drift-report.json

The query that produces prod-state.json should return a single JSON value shaped like:

[
  { "table_name": "User", "columns": ["id", "email"] },
  { "table_name": "Team", "columns": ["id", "name"] }
]

Exit codes

| Code | Meaning | | --- | --- | | 0 | No drift — the database and clone.yaml match | | 1 | Drift detected, or an error occurred (bad input, unsupported platform, …) |

When drift is detected, a human-readable summary is printed to stderr and a full machine-readable report is written to the output file.

Report format

{
  "generatedAt": "2026-06-29T09:42:33.226Z",
  "jsonFile": "prod-state.json",
  "yamlFile": "clone.yaml",
  "outputFile": "drift-report.json",
  "missingTablesInYaml": ["SentEmail"],
  "missingColumnsInYaml": { "JobAd": ["axaId"] },
  "missingTablesInJson": ["_SimilarJobAdGroupTags"],
  "missingColumnsInJson": { "Team": ["shouldPopulateCompanyInfo"] },
  "hasDrift": true
}

• missingTablesInYaml / missingColumnsInYaml — present in the database but absent from clone.yaml.
• missingTablesInJson / missingColumnsInJson — present in clone.yaml but absent from the database.

Supported platforms

Prebuilt binaries are published for:

• linux-x64, linux-arm64
• darwin-x64, darwin-arm64

The launcher resolves xata-drift-detection-<os>-<cpu> (installed via optionalDependencies) at runtime, so only the binary matching your platform is downloaded.

License

UNLICENSED