Key-Aware Snapshot Diff for CSV & JSONL

Drift compares structured exports by stable primary key rather than raw line order, surfacing schema changes, modified fields, and numeric tolerance breaches in plain terminal output or JSON patch reports.

Why Key-Aware Comparison

Line-oriented diff tools produce unreadable noise whenever upstream databases reorder exported rows, format timestamps differently, or append an optional column. Drift streams both snapshots into an indexed key store, aligns columns by header name, and emits a deterministic summary suitable for automated CI gates and manual batch verification.

Quickstart Example

$ drift compare baseline.csv candidate.csv --key account_id --ignore updated_at
SCHEMA  + currency_code (column 8)
ADDED   14 rows
REMOVED 2 rows
CHANGED 7 rows (max numeric delta: balance = 0.04)

row key="acc_00419":
  status: "trial" -> "active"
  seat_limit: 5 -> 10

Exit Status Contract

CI scripts and Makefiles can rely on stable process exit codes to separate harmless clean runs from data divergence or schema errors:

Code Meaning Typical Trigger
0Identical within tolerancesRow counts, values, and tracked columns match
1Snapshot difference detectedAdded, removed, or modified records present
2Schema mismatchMissing primary key or incompatible types under strict mode
3Input parse failureMalformed UTF-8 byte sequence, unclosed quote, or truncated JSON line

Design Constraints

Drift processes files completely offline using bounded memory buffers, streaming hashes, and deterministic sort orders. No network calls or background daemons are started during execution. Review CLI Subcommands for tolerance flags or Input Formats & Keys for delimiter and nested key rules.

When working with multi-gigabyte tables, supply --spill-dir /var/tmp so temporary sort buckets stay off root filesystems.