parity-diff 0.1.0__tar.gz

parity_diff-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,149 @@
+# Contributing
+
+The most valuable contribution is **a new dialect**. The architecture exists to
+make that a single file of roughly eighty lines that touches nothing else.
+
+## Adding a dialect
+
+The bisection engine knows nothing about SQL. It talks to two `Dialect` objects
+through a contract, so adding Snowflake or BigQuery means writing one new file
+in `src/parity/dialects/` and registering it in `get_dialect()`. If you find
+yourself editing `engine.py`, the abstraction is wrong — say so in an issue
+rather than working around it.
+
+### What you implement
+
+Nine methods, all abstract:
+
+```python
+class Dialect(ABC):
+    name: str
+    default_schema: str                           # "public", "main", ...
+
+    def connect(self, connection_string: str) -> None: ...
+    def close(self) -> None: ...
+    def query(self, sql: str) -> list[tuple]: ...
+    def quote(self, identifier: str) -> str: ...
+    def normalize(self, column: Column) -> str:   # canonical text, null-safe
+    def hash_expr(self, text_expr: str) -> str:   # -> 60-bit integer
+    def int_div(self, num: str, den: str) -> str: # truncating division
+    def sum_wide(self, expr: str) -> str:         # overflow-safe sum
+    def wide_int(self, expr: str) -> str:         # widen past 64 bits
+```
+
+Everything else is inherited and you should not need to touch it: the base
+class introspects columns from `information_schema` (override `columns` only if
+your engine has no such view), builds the row text, the per-segment checksum
+query and the small-range fetch, and splits `schema.table`. Two optional hooks
+have sensible defaults — `cancel()` for aborting an in-flight query from
+another thread, and `_exists_but_unreadable()` for engines whose catalog hides
+tables the current role lacks privileges on.
+
+That comes to roughly 70–85 lines. Read
+`src/parity/dialects/duckdb_dialect.py` first — it is the shortest complete
+example.
+
+### The six things that will bite you
+
+Each of these cost real time to discover. They are documented at length in
+`CLAUDE.md` §4; the short version:
+
+1. **The hash must be exactly 60 bits.** 15 hex characters of an MD5 digest.
+   That is the widest prefix both PostgreSQL and DuckDB render as the same
+   *positive* signed 64-bit integer. At 64 bits PostgreSQL wraps negative and
+   the engines disagree. Your dialect must produce `648541476951500027` for
+   input `'abc'` — there is a test that checks exactly this.
+
+2. **The sum must be widened.** Row hashes reach 2^60, so summing a few million
+   overflows a 64-bit accumulator. Aggregate in `numeric`, `decimal(38,0)`, or
+   whatever your engine's arbitrary-precision type is. And wrap it in
+   `coalesce(..., 0)`: an empty segment returns SQL `NULL` from `sum()`, and an
+   empty bucket on one side must compare equal to an empty bucket on the other
+   or the walker recurses into nothing.
+
+3. **`NULL` must render as the literal `\N`, never SQL NULL.** An un-coalesced
+   NULL poisons the whole concatenation and silently masks differences. Watch
+   `CASE` expressions especially: `case when c then 'true' else 'false' end`
+   sends NULL down the `else` branch, so a NULL boolean renders `'false'` and
+   compares equal to a real FALSE. Both engines agreed on that wrong answer for
+   a while. Use `case when c then 'true' when not c then 'false' end`.
+
+4. **`/` is not portable.** PostgreSQL truncates on integer operands, DuckDB
+   promotes to double. That is what `int_div` is for. Do not reach for
+   `floor(a/b)` — double precision silently breaks on large key ranges.
+
+5. **Prefer summing to XOR.** `bit_xor` exists in most engines and silently
+   cancels duplicate rows, which is precisely the difference you need to see.
+
+6. **`wide_int` has to widen the key *before* the arithmetic, not after.** The
+   bucket expression computes `(key - lo) * n_segments`, and a key range as
+   wide as bigint overflows in three separate places. `wide_int(k - lo)` looks
+   right and does nothing, because the subtraction already happened in the
+   column's own type. Return something that survives 128 bits — `hugeint`,
+   `numeric`, `NUMERIC(38,0)` — and check `int_div` still truncates on that
+   type rather than producing a scaled or rounded result.
+
+### Proving it works
+
+A dialect is not done until `tests/test_encoding.py` passes against it. That
+file is the correctness contract: it inserts the same literal into your engine
+and into a reference engine and asserts the canonical text is byte-identical.
+
+Add your engine to the fixtures there and run:
+
+```bash
+pytest tests/test_encoding.py -v
+```
+
+**Every test must plant a difference.** A test that only asserts identical
+tables match passes trivially for a completely broken tool — this is the single
+rule the project cares most about. For each positive assertion ("these agree"),
+add the negative control ("and the harness notices when they genuinely don't").
+That discipline is what caught the boolean NULL bug in point 3 above.
+
+## Running the checks
+
+```bash
+pip install -e ".[all]" pytest mypy ruff
+pytest
+ruff check src tests demo
+mypy src/parity --strict --ignore-missing-imports
+```
+
+CI runs the static checks first, because they take seconds where the test
+matrix takes minutes. `mypy --strict` is what turns "type hints everywhere"
+from an aspiration into a fact, and ruff's `ISC`, `BLE` and `S` rules are on
+deliberately: implicit string concatenation inside a collection is the
+missing-comma bug class, a blind `except` has to be justified where it sits,
+and this tool builds SQL by hand so injection rules earn their place. Where a
+rule is knowingly not applicable, the ignore lives in `pyproject.toml` with the
+reason next to it rather than being switched off globally.
+
+PostgreSQL-backed tests read `PARITY_TEST_PG` and skip cleanly when nothing is
+listening, so the suite is useful with only DuckDB installed.
+
+## Scope
+
+Before proposing a feature, check it against the question the tool exists to
+answer: *"can I safely switch off the old system?"* Data quality rules,
+freshness checks, lineage, cataloguing, orchestration, a web UI, and schema
+migration are all deliberately out of scope. The open-source predecessor in
+this category was abandoned because maintaining it grew expensive; a narrow
+scope is the only defence.
+
+Non-integer and composite keys, sampling mode, and a dbt integration are
+planned and welcome.
+
+## Style
+
+- Python 3.10+, `from __future__ import annotations` at the top of every module.
+- Type hints everywhere. Dataclasses for value types. No ORM — emitting dialect
+  SQL deliberately is the product.
+- No network calls, no telemetry. This tool points at production warehouses;
+  trust is the whole distribution strategy.
+- Read-only by construction. The tool issues `SELECT` only and never generates
+  DDL or DML against a user's database.
+- Comments explain *why*, especially for cross-engine workarounds — each one is
+  a landmine for the next person.
+- Errors must name the side and the table. `"table not found"` is useless when
+  two databases are in play.

parity_diff-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alessio Sorio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

parity_diff-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+# The sdist shipped `test_*.py` but not `conftest.py` or `fakes.py`, so the
+# tests it carried could not actually run. For a tool whose whole pitch is
+# trustworthiness, a downstream packager has to be able to verify it - so ship
+# a suite that works, or none at all.
+include LICENSE
+include README.md
+include CONTRIBUTING.md
+recursive-include tests *.py
+prune demo/data
+global-exclude __pycache__ *.py[cod]

parity_diff-0.1.0/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: parity-diff
+Version: 0.1.0
+Summary: Prove two tables in two different database engines hold the same data - without moving the data out of either engine.
+Author: Alessio Sorio
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Aleixiou/parity
+Project-URL: Repository, https://github.com/Aleixiou/parity
+Project-URL: Issues, https://github.com/Aleixiou/parity/issues
+Keywords: data-diff,migration,postgres,duckdb,data-quality,cutover,warehouse,parity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=1.0; extra == "duckdb"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
+Provides-Extra: all
+Requires-Dist: duckdb>=1.0; extra == "all"
+Requires-Dist: psycopg[binary]>=3.1; extra == "all"
+Dynamic: license-file
+
+# parity
+
+[![tests](https://github.com/Aleixiou/parity/actions/workflows/tests.yml/badge.svg)](https://github.com/Aleixiou/parity/actions/workflows/tests.yml)
+
+**Prove two tables in two different database engines hold the same data —
+without moving the data out of either engine.**
+
+Migrations don't fail on translation. They fail at cutover, because nobody can
+prove the new pipeline produces the same data as the old one — so the legacy
+system runs in parallel "just to be safe", forever, at double the cost.
+`parity` is the proof.
+
+```bash
+parity diff \
+  --a "postgres://user:pw@legacy-host/warehouse" --a-table public.orders \
+  --b "duckdb:///./new.duckdb"                   --b-table main.orders \
+  --key order_id
+```
+
+```
+✗ 5 differences in 10,000,000 rows
+  28 queries · 7,628 rows downloaded (0.04% of both tables) · 54.2s
+  1 only in A · 1 only in B · 3 different
+
+  only in A   key 999999999
+  only in B   key 4000
+  different   key 13             columns: note
+      note   A ''   B NULL
+  different   key 6010000        columns: amount
+      amount   A 700.010000   B 700.000000
+  different   key 8700000        columns: is_refunded
+      is_refunded   A NULL   B false
+
+  comparing floats and decimals at 6 decimal places
+```
+
+Exit code `1`. Put it in CI and the build fails until the data agrees.
+
+## How it works
+
+`parity` pushes hash aggregation **down into both engines**. It asks each side
+for one checksum per bucket of the key range, compares a handful of integers,
+recurses only into the buckets that disagree, and downloads rows only from
+ranges already proven to differ.
+
+On identical tables it downloads **zero rows** and issues **four queries**,
+whether the table has ten thousand rows or ten million.
+
+## Measured
+
+10,000,000 rows per side, PostgreSQL 18.4 ↔ DuckDB 1.5.5, median of five runs
+on one developer laptop (`demo/benchmark.py`):
+
+| Scenario | Queries | Rows downloaded | Wall time |
+|---|---|---|---|
+| identical tables | 4 | **0** (0.0000%) | 26.9s |
+| 5 planted differences | 28 | 7,628 (0.0381%) | 54.2s |
+
+The query count and the rows-downloaded figures are **exact and
+hardware-independent** — they are properties of the algorithm, and the test
+suite pins them. The wall times are one machine under sustained load; treat
+them as an order of magnitude, not a specification.
+
+The five planted differences — a changed decimal, a deleted row, an inserted
+row at key 999,999,999, a `NULL` turned into `''`, and a `FALSE` turned into
+`NULL` — are all found exactly, with no false positives.
+
+Cost is roughly **one full hash pass per side**. It is CPU-bound on MD5, not
+IO-bound on key lookup, which is why **an index on the key column makes no
+measurable difference** (measured at 10M: 38.8s without, 37.3s with).
+Raising
+`--bisection-factor` does not speed up the dominant first pass; it only reduces
+round trips on later levels.
+
+## Install
+
+```bash
+pip install "parity-diff[all]"        # both engines
+pip install "parity-diff[duckdb]"     # DuckDB only — no PostgreSQL driver pulled in
+pip install "parity-diff[postgres]"   # PostgreSQL only
+```
+
+> The PyPI distribution is `parity-diff` — plain `parity` is squatted by an
+> empty project. The command you run and the module you import are both
+> `parity`.
+
+Python 3.10+. The core has no dependencies; drivers are optional extras and are
+imported lazily, so a DuckDB-only user is never made to install `psycopg`.
+
+## Usage
+
+```
+parity diff --a CONN --a-table TABLE --b CONN --b-table TABLE --key COL
+            [--columns a,b,c] [--exclude x,y]
+            [--bisection-factor 32] [--threshold 10000] [--float-scale 6]
+            [--max-diffs 100] [--json] [--quiet]
+```
+
+**Exit codes** — this is what makes it a CI check:
+
+| Code | Meaning |
+|---|---|
+| `0` | identical |
+| `1` | differences found |
+| `2` | error (bad connection string, missing table, unusable key) |
+
+An error is never `1`. A CI job can always tell "the tables differ" from "the
+tool could not run".
+
+Connection strings:
+
+```
+postgres://user:password@host:port/database     (also postgresql://)
+duckdb:///relative/path.duckdb                  (three slashes = relative)
+duckdb:////var/lib/warehouse.duckdb             (four slashes = absolute)
+duckdb:///C:/data/warehouse.duckdb              (absolute, Windows)
+duckdb:///:memory:
+```
+
+Table names may be schema-qualified. Unqualified names default to `public` on
+PostgreSQL and `main` on DuckDB.
+
+`--json` emits the same content as a machine-readable object, including
+`identical`, `truncated`, per-difference values, and the full stats block.
+
+### In CI
+
+```yaml
+- name: prove the migration is complete
+  run: |
+    parity diff \
+      --a "$LEGACY_URL"     --a-table public.orders \
+      --b "$WAREHOUSE_URL"  --b-table analytics.orders \
+      --key order_id --quiet
+```
+
+## Limitations — read these before trusting a result
+
+A parity tool that reports a false match is worse than useless, so these are
+stated plainly rather than buried.
+
+- **Integer keys only.** The bisection arithmetic divides the key range. A
+  `varchar` or `uuid` key is rejected with a clear message, not guessed at.
+  Composite and hashed keys are a planned extension.
+- **Floats and decimals are compared at 6 decimal places** by default. Two
+  values differing only in the 7th place are reported as *equal*. This is a
+  deliberate cross-engine rounding contract — the two engines do not otherwise
+  agree on float text. Change it with `--float-scale`; it always applies to
+  both sides, and the scale in force is printed on every run.
+- **Keys must be unique.** A non-unique key is detected up front and rejected.
+  Silently collapsing duplicate rows would hide real differences.
+- **`Infinity` and `NaN`** in float columns are compared as those literal
+  tokens on both sides. A double whose magnitude reaches 1e32 is not supported
+  and fails loudly on DuckDB.
+- **Wide tables are fine.** PostgreSQL caps a function call at 100 arguments,
+  so the row concatenation is built as a nested tree; tested to 500 columns.
+- **Supported types:** integer, decimal, float, boolean, string, date,
+  timestamp. Anything else is compared as raw text and reported as a warning —
+  two engines may render the same JSON or array differently for reasons that
+  have nothing to do with the data.
+- **At most 10,000 differences are reported by default.** Each one costs about
+  715 bytes, so two tables that share nothing would need gigabytes rather than
+  producing an answer - and pointing the tool at the wrong table or the wrong
+  environment is exactly what it exists to catch. Past the limit the run is
+  flagged `truncated`, `identical` is never true, and the output says "at
+  least N". It does not mean the rest matched. `--max-diffs 0` lifts the limit.
+- **Timezone-aware timestamps are compared as instants, in UTC.** Both
+  sessions are pinned to UTC on connect, so the same instant matches whatever
+  the two servers' default timezones are. Without that pin, two sides in
+  different zones render every `timestamptz` differently and the tool reports
+  the entire table as changed.
+- Columns present on only one side are skipped with a warning, not treated as
+  differences.
+
+## Supported engines
+
+| Engine | Status |
+|---|---|
+| PostgreSQL | supported (tested against 16 and 18) |
+| DuckDB | supported (tested against 1.5) |
+| Snowflake, BigQuery | not yet — see `CONTRIBUTING.md`, a dialect is ~80 lines |
+
+## Scope
+
+In scope: proving two tables match, finding exactly which rows and columns
+don't, doing it cheaply on large tables, running in CI.
+
+Deliberately out of scope: data quality rules, freshness checks, anomaly
+detection, lineage, cataloguing, orchestration, transformation, a web UI, a
+server, schema migration. If a feature does not help someone answer *"can I
+safely switch off the old system?"*, it does not belong here.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/Activate.ps1        # Windows;  source .venv/bin/activate elsewhere
+pip install -e ".[all]" pytest
+pytest
+```
+
+Tests that need PostgreSQL read `PARITY_TEST_PG` (default
+`postgres://parity:parity@127.0.0.1:5432/parity`) and **skip cleanly** when no
+server is reachable — the DuckDB and pure-Python suites still run.
+
+A disposable PostgreSQL:
+
+```bash
+docker run -d --name parity-pg -p 55432:5432 \
+  -e POSTGRES_USER=parity -e POSTGRES_PASSWORD=parity -e POSTGRES_DB=parity \
+  postgres:16-alpine
+export PARITY_TEST_PG="postgres://parity:parity@127.0.0.1:55432/parity"
+```
+
+Reproduce the benchmark:
+
+```bash
+python demo/generate.py --rows 10000000
+python demo/benchmark.py --expect-clean
+python demo/generate.py --rows 10000000 --plant
+python demo/benchmark.py --expect-planted
+```
+
+`CLAUDE.md` holds the verified cross-engine SQL and why each expression is the
+way it is. `BUILD_SPEC.md` is the build plan.
+
+## Changelog
+
+See `CHANGELOG.md`.
+
+## License
+
+MIT — see `LICENSE`.

parity_diff-0.1.0/README.md

@@ -0,0 +1,233 @@
+# parity
+
+[![tests](https://github.com/Aleixiou/parity/actions/workflows/tests.yml/badge.svg)](https://github.com/Aleixiou/parity/actions/workflows/tests.yml)
+
+**Prove two tables in two different database engines hold the same data —
+without moving the data out of either engine.**
+
+Migrations don't fail on translation. They fail at cutover, because nobody can
+prove the new pipeline produces the same data as the old one — so the legacy
+system runs in parallel "just to be safe", forever, at double the cost.
+`parity` is the proof.
+
+```bash
+parity diff \
+  --a "postgres://user:pw@legacy-host/warehouse" --a-table public.orders \
+  --b "duckdb:///./new.duckdb"                   --b-table main.orders \
+  --key order_id
+```
+
+```
+✗ 5 differences in 10,000,000 rows
+  28 queries · 7,628 rows downloaded (0.04% of both tables) · 54.2s
+  1 only in A · 1 only in B · 3 different
+
+  only in A   key 999999999
+  only in B   key 4000
+  different   key 13             columns: note
+      note   A ''   B NULL
+  different   key 6010000        columns: amount
+      amount   A 700.010000   B 700.000000
+  different   key 8700000        columns: is_refunded
+      is_refunded   A NULL   B false
+
+  comparing floats and decimals at 6 decimal places
+```
+
+Exit code `1`. Put it in CI and the build fails until the data agrees.
+
+## How it works
+
+`parity` pushes hash aggregation **down into both engines**. It asks each side
+for one checksum per bucket of the key range, compares a handful of integers,
+recurses only into the buckets that disagree, and downloads rows only from
+ranges already proven to differ.
+
+On identical tables it downloads **zero rows** and issues **four queries**,
+whether the table has ten thousand rows or ten million.
+
+## Measured
+
+10,000,000 rows per side, PostgreSQL 18.4 ↔ DuckDB 1.5.5, median of five runs
+on one developer laptop (`demo/benchmark.py`):
+
+| Scenario | Queries | Rows downloaded | Wall time |
+|---|---|---|---|
+| identical tables | 4 | **0** (0.0000%) | 26.9s |
+| 5 planted differences | 28 | 7,628 (0.0381%) | 54.2s |
+
+The query count and the rows-downloaded figures are **exact and
+hardware-independent** — they are properties of the algorithm, and the test
+suite pins them. The wall times are one machine under sustained load; treat
+them as an order of magnitude, not a specification.
+
+The five planted differences — a changed decimal, a deleted row, an inserted
+row at key 999,999,999, a `NULL` turned into `''`, and a `FALSE` turned into
+`NULL` — are all found exactly, with no false positives.
+
+Cost is roughly **one full hash pass per side**. It is CPU-bound on MD5, not
+IO-bound on key lookup, which is why **an index on the key column makes no
+measurable difference** (measured at 10M: 38.8s without, 37.3s with).
+Raising
+`--bisection-factor` does not speed up the dominant first pass; it only reduces
+round trips on later levels.
+
+## Install
+
+```bash
+pip install "parity-diff[all]"        # both engines
+pip install "parity-diff[duckdb]"     # DuckDB only — no PostgreSQL driver pulled in
+pip install "parity-diff[postgres]"   # PostgreSQL only
+```
+
+> The PyPI distribution is `parity-diff` — plain `parity` is squatted by an
+> empty project. The command you run and the module you import are both
+> `parity`.
+
+Python 3.10+. The core has no dependencies; drivers are optional extras and are
+imported lazily, so a DuckDB-only user is never made to install `psycopg`.
+
+## Usage
+
+```
+parity diff --a CONN --a-table TABLE --b CONN --b-table TABLE --key COL
+            [--columns a,b,c] [--exclude x,y]
+            [--bisection-factor 32] [--threshold 10000] [--float-scale 6]
+            [--max-diffs 100] [--json] [--quiet]
+```
+
+**Exit codes** — this is what makes it a CI check:
+
+| Code | Meaning |
+|---|---|
+| `0` | identical |
+| `1` | differences found |
+| `2` | error (bad connection string, missing table, unusable key) |
+
+An error is never `1`. A CI job can always tell "the tables differ" from "the
+tool could not run".
+
+Connection strings:
+
+```
+postgres://user:password@host:port/database     (also postgresql://)
+duckdb:///relative/path.duckdb                  (three slashes = relative)
+duckdb:////var/lib/warehouse.duckdb             (four slashes = absolute)
+duckdb:///C:/data/warehouse.duckdb              (absolute, Windows)
+duckdb:///:memory:
+```
+
+Table names may be schema-qualified. Unqualified names default to `public` on
+PostgreSQL and `main` on DuckDB.
+
+`--json` emits the same content as a machine-readable object, including
+`identical`, `truncated`, per-difference values, and the full stats block.
+
+### In CI
+
+```yaml
+- name: prove the migration is complete
+  run: |
+    parity diff \
+      --a "$LEGACY_URL"     --a-table public.orders \
+      --b "$WAREHOUSE_URL"  --b-table analytics.orders \
+      --key order_id --quiet
+```
+
+## Limitations — read these before trusting a result
+
+A parity tool that reports a false match is worse than useless, so these are
+stated plainly rather than buried.
+
+- **Integer keys only.** The bisection arithmetic divides the key range. A
+  `varchar` or `uuid` key is rejected with a clear message, not guessed at.
+  Composite and hashed keys are a planned extension.
+- **Floats and decimals are compared at 6 decimal places** by default. Two
+  values differing only in the 7th place are reported as *equal*. This is a
+  deliberate cross-engine rounding contract — the two engines do not otherwise
+  agree on float text. Change it with `--float-scale`; it always applies to
+  both sides, and the scale in force is printed on every run.
+- **Keys must be unique.** A non-unique key is detected up front and rejected.
+  Silently collapsing duplicate rows would hide real differences.
+- **`Infinity` and `NaN`** in float columns are compared as those literal
+  tokens on both sides. A double whose magnitude reaches 1e32 is not supported
+  and fails loudly on DuckDB.
+- **Wide tables are fine.** PostgreSQL caps a function call at 100 arguments,
+  so the row concatenation is built as a nested tree; tested to 500 columns.
+- **Supported types:** integer, decimal, float, boolean, string, date,
+  timestamp. Anything else is compared as raw text and reported as a warning —
+  two engines may render the same JSON or array differently for reasons that
+  have nothing to do with the data.
+- **At most 10,000 differences are reported by default.** Each one costs about
+  715 bytes, so two tables that share nothing would need gigabytes rather than
+  producing an answer - and pointing the tool at the wrong table or the wrong
+  environment is exactly what it exists to catch. Past the limit the run is
+  flagged `truncated`, `identical` is never true, and the output says "at
+  least N". It does not mean the rest matched. `--max-diffs 0` lifts the limit.
+- **Timezone-aware timestamps are compared as instants, in UTC.** Both
+  sessions are pinned to UTC on connect, so the same instant matches whatever
+  the two servers' default timezones are. Without that pin, two sides in
+  different zones render every `timestamptz` differently and the tool reports
+  the entire table as changed.
+- Columns present on only one side are skipped with a warning, not treated as
+  differences.
+
+## Supported engines
+
+| Engine | Status |
+|---|---|
+| PostgreSQL | supported (tested against 16 and 18) |
+| DuckDB | supported (tested against 1.5) |
+| Snowflake, BigQuery | not yet — see `CONTRIBUTING.md`, a dialect is ~80 lines |
+
+## Scope
+
+In scope: proving two tables match, finding exactly which rows and columns
+don't, doing it cheaply on large tables, running in CI.
+
+Deliberately out of scope: data quality rules, freshness checks, anomaly
+detection, lineage, cataloguing, orchestration, transformation, a web UI, a
+server, schema migration. If a feature does not help someone answer *"can I
+safely switch off the old system?"*, it does not belong here.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/Activate.ps1        # Windows;  source .venv/bin/activate elsewhere
+pip install -e ".[all]" pytest
+pytest
+```
+
+Tests that need PostgreSQL read `PARITY_TEST_PG` (default
+`postgres://parity:parity@127.0.0.1:5432/parity`) and **skip cleanly** when no
+server is reachable — the DuckDB and pure-Python suites still run.
+
+A disposable PostgreSQL:
+
+```bash
+docker run -d --name parity-pg -p 55432:5432 \
+  -e POSTGRES_USER=parity -e POSTGRES_PASSWORD=parity -e POSTGRES_DB=parity \
+  postgres:16-alpine
+export PARITY_TEST_PG="postgres://parity:parity@127.0.0.1:55432/parity"
+```
+
+Reproduce the benchmark:
+
+```bash
+python demo/generate.py --rows 10000000
+python demo/benchmark.py --expect-clean
+python demo/generate.py --rows 10000000 --plant
+python demo/benchmark.py --expect-planted
+```
+
+`CLAUDE.md` holds the verified cross-engine SQL and why each expression is the
+way it is. `BUILD_SPEC.md` is the build plan.
+
+## Changelog
+
+See `CHANGELOG.md`.
+
+## License
+
+MIT — see `LICENSE`.