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 |
|---|---|---|
0 | Identical within tolerances | Row counts, values, and tracked columns match |
1 | Snapshot difference detected | Added, removed, or modified records present |
2 | Schema mismatch | Missing primary key or incompatible types under strict mode |
3 | Input parse failure | Malformed 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.
--spill-dir /var/tmp so temporary sort buckets stay off root filesystems.