parity-diff 0.1.0__tar.gz → 0.2.0__tar.gz

{parity_diff-0.1.0 → parity_diff-0.2.0}/CONTRIBUTING.md

@@ -43,7 +43,7 @@ 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
+### The 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:
@@ -83,6 +83,20 @@ Each of these cost real time to discover. They are documented at length in
    `numeric`, `NUMERIC(38,0)` — and check `int_div` still truncates on that
    type rather than producing a scaled or rounded result.
 
+MySQL, added after v0.1.0, turned up two more that a warehouse dialect may hit:
+
+7. **Not every engine has `chr`, and `char(n)` may be binary.** MySQL spells
+   the separator `char(31)`, not `chr(31)`, and a bare `char(31)` is a *binary*
+   string that coerces the whole `concat_ws` to bytes - which then comes back
+   from `fetch_range` as `bytes`, not `str`, and every row reads as different.
+   The separator and the NULL sentinel are dialect hooks (`separator_sql`,
+   `null_sentinel_sql`) for exactly this reason.
+
+8. **Backslash in a string literal is not portable.** MySQL processes a
+   backslash as an escape inside `'...'`, toggled by `sql_mode`, so the `\N`
+   sentinel silently became `N`. Build such bytes from `CHAR`/hex, not a
+   literal, and verify by hashing rather than by reading the SQL.
+
 ### Proving it works
 
 A dialect is not done until `tests/test_encoding.py` passes against it. That

{parity_diff-0.1.0/src/parity_diff.egg-info → parity_diff-0.2.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: parity-diff
-Version: 0.1.0
+Version: 0.2.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
+Project-URL: Homepage, https://github.com/Aleixiou/parity-diff
+Project-URL: Repository, https://github.com/Aleixiou/parity-diff
+Project-URL: Issues, https://github.com/Aleixiou/parity-diff/issues
 Keywords: data-diff,migration,postgres,duckdb,data-quality,cutover,warehouse,parity
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
@@ -28,14 +28,17 @@ Provides-Extra: duckdb
 Requires-Dist: duckdb>=1.0; extra == "duckdb"
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
+Provides-Extra: mysql
+Requires-Dist: mysql-connector-python>=8.0; extra == "mysql"
 Provides-Extra: all
 Requires-Dist: duckdb>=1.0; extra == "all"
 Requires-Dist: psycopg[binary]>=3.1; extra == "all"
+Requires-Dist: mysql-connector-python>=8.0; 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)
+[![tests](https://github.com/Aleixiou/parity-diff/actions/workflows/tests.yml/badge.svg)](https://github.com/Aleixiou/parity-diff/actions/workflows/tests.yml)
 
 **Prove two tables in two different database engines hold the same data —
 without moving the data out of either engine.**
@@ -54,7 +57,7 @@ parity diff \
 
 ```
 ✗ 5 differences in 10,000,000 rows
-  28 queries · 7,628 rows downloaded (0.04% of both tables) · 54.2s
+  28 queries · 7,628 rows downloaded (0.04% of both tables) · 47.9s
   1 only in A · 1 only in B · 3 different
 
   only in A   key 999999999
@@ -88,8 +91,16 @@ 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 |
+| identical tables | **4** | **0** (0.0000%) | 25–31s |
+| 5 planted differences | **28** | **7,628** (0.0381%) | 48–55s |
+
+**The query counts and row counts are exact and hardware-independent** — they
+are properties of the algorithm, and the test suite pins them. Reproduce them
+and you should get the same integers.
+
+The wall times are a range across six runs on one developer laptop, and they
+vary by about 25% with whatever else that laptop is doing. Treat them as an
+order of magnitude, not a specification.
 
 The query count and the rows-downloaded figures are **exact and
 hardware-independent** — they are properties of the algorithm, and the test
@@ -110,9 +121,10 @@ 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[all]"        # every engine
+pip install "parity-diff[duckdb]"     # DuckDB only — no other driver pulled in
 pip install "parity-diff[postgres]"   # PostgreSQL only
+pip install "parity-diff[mysql]"      # MySQL only
 ```
 
 > The PyPI distribution is `parity-diff` — plain `parity` is squatted by an
@@ -125,7 +137,7 @@ 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
+parity diff --a CONN --a-table TABLE --b CONN --b-table TABLE --key COL[,COL...]
             [--columns a,b,c] [--exclude x,y]
             [--bisection-factor 32] [--threshold 10000] [--float-scale 6]
             [--max-diffs 100] [--json] [--quiet]
@@ -146,6 +158,7 @@ Connection strings:
 
 ```
 postgres://user:password@host:port/database     (also postgresql://)
+mysql://user:password@host:port/database
 duckdb:///relative/path.duckdb                  (three slashes = relative)
 duckdb:////var/lib/warehouse.duckdb             (four slashes = absolute)
 duckdb:///C:/data/warehouse.duckdb              (absolute, Windows)
@@ -169,14 +182,73 @@ PostgreSQL and `main` on DuckDB.
       --key order_id --quiet
 ```
 
+## Using it from Python
+
+The CLI is a thin wrapper. `diff` returns the whole result, so you can act on
+it rather than parse output. Importing `parity` pulls in no database driver —
+they load when `get_dialect` needs one.
+
+```python
+from parity import diff, get_dialect
+
+a = get_dialect("duckdb:///old.duckdb", side="A")
+b = get_dialect("duckdb:///new.duckdb", side="B")
+try:
+    result = diff(a, b, "main.orders", "main.orders", key="id")
+finally:
+    a.close()
+    b.close()
+
+if result.identical:
+    print("the tables match")
+else:
+    for d in result.diffs:
+        print(d.kind, d.key, d.columns, d.values_a, d.values_b)
+
+print(f"{result.stats.rows_downloaded} rows crossed the network")
+print(f"truncated: {result.truncated}")
+```
+
+```
+different 2 ['status'] {'status': 'ok'} {'status': 'CHANGED'}
+2 rows crossed the network
+truncated: False
+```
+
+`diff` takes the same options as the CLI: `columns`, `exclude`,
+`bisection_factor`, `threshold`, `max_diffs`. Pass `max_diffs=None` to lift the
+10,000 default, and `float_scale` to `get_dialect` — both sides must agree or
+the comparison is refused before it runs.
+
+### What you get back
+
+`DiffResult` carries:
+
+| Attribute | |
+|---|---|
+| `identical` | `True` only if nothing differed **and** the whole key space was walked. False whenever `truncated` is set. |
+| `truncated` | The walk stopped early, so this is a partial answer. Never read a truncated result as "the rest matched". |
+| `diffs` | `RowDiff` objects in key order, each with `key`, `kind` (`only_in_a`, `only_in_b`, `different`), the `columns` that moved, and `values_a` / `values_b` as raw canonical text. |
+| `columns` | The columns actually compared, after `columns` and `exclude`. |
+| `warnings` | Everything the comparison decided on your behalf: columns skipped, types that differ between sides, timezone-awareness mismatches. Worth surfacing. |
+| `float_scale` | The rounding in force, so a caller can state it alongside the verdict. |
+| `stats` | `queries`, `rows_downloaded`, `rows_compared_a`, `rows_compared_b`, `segments_checked`, `seconds`. |
+
+`diff` raises `ValueError` for anything it refuses — a non-integer key, a
+non-unique or NULL key, a missing table, mismatched float scales. The message
+always names which side.
+
 ## 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.
+- **Any key type, but non-integer keys are bucketed by a hash.** A single
+  integer column is bisected directly. A `uuid`, a natural string key, or
+  several columns together are hashed to 60 bits so the key space can be
+  divided — and the run says so. Rows are still matched and reported by their
+  real key, so a hash collision can only put two rows in the same bucket; it
+  can never merge them.
 - **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
@@ -213,7 +285,8 @@ stated plainly rather than buried.
 |---|---|
 | 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 |
+| MySQL | supported (tested against 8.0) |
+| Snowflake, BigQuery, Redshift | not yet — see `CONTRIBUTING.md`, a dialect is ~80 lines |
 
 ## Scope
 
@@ -257,7 +330,7 @@ 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.
+way it is. `ROADMAP.md` is what is done and what comes next.
 
 ## Changelog
 

{parity_diff-0.1.0 → parity_diff-0.2.0}/README.md

@@ -1,6 +1,6 @@
 # parity
 
-[![tests](https://github.com/Aleixiou/parity/actions/workflows/tests.yml/badge.svg)](https://github.com/Aleixiou/parity/actions/workflows/tests.yml)
+[![tests](https://github.com/Aleixiou/parity-diff/actions/workflows/tests.yml/badge.svg)](https://github.com/Aleixiou/parity-diff/actions/workflows/tests.yml)
 
 **Prove two tables in two different database engines hold the same data —
 without moving the data out of either engine.**
@@ -19,7 +19,7 @@ parity diff \
 
 ```
 ✗ 5 differences in 10,000,000 rows
-  28 queries · 7,628 rows downloaded (0.04% of both tables) · 54.2s
+  28 queries · 7,628 rows downloaded (0.04% of both tables) · 47.9s
   1 only in A · 1 only in B · 3 different
 
   only in A   key 999999999
@@ -53,8 +53,16 @@ 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 |
+| identical tables | **4** | **0** (0.0000%) | 25–31s |
+| 5 planted differences | **28** | **7,628** (0.0381%) | 48–55s |
+
+**The query counts and row counts are exact and hardware-independent** — they
+are properties of the algorithm, and the test suite pins them. Reproduce them
+and you should get the same integers.
+
+The wall times are a range across six runs on one developer laptop, and they
+vary by about 25% with whatever else that laptop is doing. Treat them as an
+order of magnitude, not a specification.
 
 The query count and the rows-downloaded figures are **exact and
 hardware-independent** — they are properties of the algorithm, and the test
@@ -75,9 +83,10 @@ 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[all]"        # every engine
+pip install "parity-diff[duckdb]"     # DuckDB only — no other driver pulled in
 pip install "parity-diff[postgres]"   # PostgreSQL only
+pip install "parity-diff[mysql]"      # MySQL only
 ```
 
 > The PyPI distribution is `parity-diff` — plain `parity` is squatted by an
@@ -90,7 +99,7 @@ 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
+parity diff --a CONN --a-table TABLE --b CONN --b-table TABLE --key COL[,COL...]
             [--columns a,b,c] [--exclude x,y]
             [--bisection-factor 32] [--threshold 10000] [--float-scale 6]
             [--max-diffs 100] [--json] [--quiet]
@@ -111,6 +120,7 @@ Connection strings:
 
 ```
 postgres://user:password@host:port/database     (also postgresql://)
+mysql://user:password@host:port/database
 duckdb:///relative/path.duckdb                  (three slashes = relative)
 duckdb:////var/lib/warehouse.duckdb             (four slashes = absolute)
 duckdb:///C:/data/warehouse.duckdb              (absolute, Windows)
@@ -134,14 +144,73 @@ PostgreSQL and `main` on DuckDB.
       --key order_id --quiet
 ```
 
+## Using it from Python
+
+The CLI is a thin wrapper. `diff` returns the whole result, so you can act on
+it rather than parse output. Importing `parity` pulls in no database driver —
+they load when `get_dialect` needs one.
+
+```python
+from parity import diff, get_dialect
+
+a = get_dialect("duckdb:///old.duckdb", side="A")
+b = get_dialect("duckdb:///new.duckdb", side="B")
+try:
+    result = diff(a, b, "main.orders", "main.orders", key="id")
+finally:
+    a.close()
+    b.close()
+
+if result.identical:
+    print("the tables match")
+else:
+    for d in result.diffs:
+        print(d.kind, d.key, d.columns, d.values_a, d.values_b)
+
+print(f"{result.stats.rows_downloaded} rows crossed the network")
+print(f"truncated: {result.truncated}")
+```
+
+```
+different 2 ['status'] {'status': 'ok'} {'status': 'CHANGED'}
+2 rows crossed the network
+truncated: False
+```
+
+`diff` takes the same options as the CLI: `columns`, `exclude`,
+`bisection_factor`, `threshold`, `max_diffs`. Pass `max_diffs=None` to lift the
+10,000 default, and `float_scale` to `get_dialect` — both sides must agree or
+the comparison is refused before it runs.
+
+### What you get back
+
+`DiffResult` carries:
+
+| Attribute | |
+|---|---|
+| `identical` | `True` only if nothing differed **and** the whole key space was walked. False whenever `truncated` is set. |
+| `truncated` | The walk stopped early, so this is a partial answer. Never read a truncated result as "the rest matched". |
+| `diffs` | `RowDiff` objects in key order, each with `key`, `kind` (`only_in_a`, `only_in_b`, `different`), the `columns` that moved, and `values_a` / `values_b` as raw canonical text. |
+| `columns` | The columns actually compared, after `columns` and `exclude`. |
+| `warnings` | Everything the comparison decided on your behalf: columns skipped, types that differ between sides, timezone-awareness mismatches. Worth surfacing. |
+| `float_scale` | The rounding in force, so a caller can state it alongside the verdict. |
+| `stats` | `queries`, `rows_downloaded`, `rows_compared_a`, `rows_compared_b`, `segments_checked`, `seconds`. |
+
+`diff` raises `ValueError` for anything it refuses — a non-integer key, a
+non-unique or NULL key, a missing table, mismatched float scales. The message
+always names which side.
+
 ## 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.
+- **Any key type, but non-integer keys are bucketed by a hash.** A single
+  integer column is bisected directly. A `uuid`, a natural string key, or
+  several columns together are hashed to 60 bits so the key space can be
+  divided — and the run says so. Rows are still matched and reported by their
+  real key, so a hash collision can only put two rows in the same bucket; it
+  can never merge them.
 - **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
@@ -178,7 +247,8 @@ stated plainly rather than buried.
 |---|---|
 | 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 |
+| MySQL | supported (tested against 8.0) |
+| Snowflake, BigQuery, Redshift | not yet — see `CONTRIBUTING.md`, a dialect is ~80 lines |
 
 ## Scope
 
@@ -222,7 +292,7 @@ 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.
+way it is. `ROADMAP.md` is what is done and what comes next.
 
 ## Changelog
 

{parity_diff-0.1.0 → parity_diff-0.2.0}/pyproject.toml

@@ -3,7 +3,7 @@
 # PyPI by an empty project. The import name, the CLI command and the repo are
 # all still `parity`: `pip install parity-diff` gives you `parity ...`.
 name = "parity-diff"
-version = "0.1.0"
+version = "0.2.0"
 description = "Prove two tables in two different database engines hold the same data - without moving the data out of either engine."
 readme = "README.md"
 license = "MIT"
@@ -36,12 +36,13 @@ dependencies = []
 [project.optional-dependencies]
 duckdb = ["duckdb>=1.0"]
 postgres = ["psycopg[binary]>=3.1"]
-all = ["duckdb>=1.0", "psycopg[binary]>=3.1"]
+mysql = ["mysql-connector-python>=8.0"]
+all = ["duckdb>=1.0", "psycopg[binary]>=3.1", "mysql-connector-python>=8.0"]
 
 [project.urls]
-Homepage = "https://github.com/Aleixiou/parity"
-Repository = "https://github.com/Aleixiou/parity"
-Issues = "https://github.com/Aleixiou/parity/issues"
+Homepage = "https://github.com/Aleixiou/parity-diff"
+Repository = "https://github.com/Aleixiou/parity-diff"
+Issues = "https://github.com/Aleixiou/parity-diff/issues"
 
 [project.scripts]
 parity = "parity.cli:main"
@@ -58,6 +59,7 @@ testpaths = ["tests"]
 addopts = "-q --strict-markers"
 markers = [
     "postgres: requires a reachable PostgreSQL server",
+    "mysql: requires a reachable MySQL server",
     "duckdb: requires the duckdb driver",
 ]
 
@@ -99,6 +101,7 @@ ignore = [
 # have their own injection tests in tests/test_encoding.py.
 "src/parity/dialects/base.py" = ["S608"]
 "src/parity/dialects/postgres_dialect.py" = ["S608"]
+"src/parity/dialects/mysql_dialect.py" = ["S608"]
 # proof.py is kept close to the original author's script so it stays readable
 # next to the findings it produced; its terse one-line style is deliberate.
 "demo/proof.py" = ["E401", "E402", "E701", "E702", "B007", "S311", "S608"]

{parity_diff-0.1.0 → parity_diff-0.2.0}/src/parity/__init__.py

@@ -13,12 +13,17 @@ from __future__ import annotations
 
 from typing import Any
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = ["__version__", "diff", "get_dialect"]
 
 
 def __getattr__(name: str) -> Any:
+    """Resolve `parity.diff` and `parity.get_dialect` on first use.
+
+    Deferring the import is what keeps `import parity` free of database
+    drivers, so a DuckDB-only user is never made to install psycopg.
+    """
     # Lazy re-export: keeps `import parity` free of driver imports.
     if name == "get_dialect":
         from parity.dialects.base import get_dialect

{parity_diff-0.1.0 → parity_diff-0.2.0}/src/parity/cli.py

@@ -37,6 +37,11 @@ KIND_LABELS = {
 
 
 def build_parser() -> argparse.ArgumentParser:
+    """Build the whole command line surface.
+
+    Split out from `main` so `--help` can be rendered, and the flags asserted,
+    without running anything or importing a database driver.
+    """
     parser = argparse.ArgumentParser(
         prog="parity",
         description=(
@@ -61,7 +66,13 @@ def build_parser() -> argparse.ArgumentParser:
     d.add_argument("--a-table", required=True, metavar="TABLE", help="side A table")
     d.add_argument("--b", required=True, metavar="CONN", help="side B connection string")
     d.add_argument("--b-table", required=True, metavar="TABLE", help="side B table")
-    d.add_argument("--key", required=True, metavar="COL", help="integer key column")
+    d.add_argument(
+        "--key", required=True, metavar="COL[,COL...]",
+        help="the column(s) that identify a row. One integer column is used "
+             "directly; a uuid, a text key or several columns together are "
+             "hashed so the key space can be bisected, and rows are still "
+             "reported by their real key.",
+    )
     d.add_argument(
         "--columns", metavar="a,b,c",
         help="compare only these columns (default: every column both sides share)",
@@ -98,6 +109,11 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def _split(value: str | None) -> list[str]:
+    """Turn a comma-separated flag value into a list, ignoring blanks.
+
+    So `--exclude "a, b,"` gives ["a", "b"] rather than an empty column name
+    that would later fail to match anything.
+    """
     if not value:
         return []
     return [part.strip() for part in value.split(",") if part.strip()]
@@ -109,6 +125,7 @@ def _split(value: str | None) -> list[str]:
 
 
 def _plural(n: int, word: str) -> str:
+    """Format a count with its noun, pluralised and thousands-separated."""
     return f"{n:,} {word}{'' if n == 1 else 's'}"
 
 
@@ -138,6 +155,19 @@ def _symbols(out: TextIO) -> dict[str, str]:
     return {"bad": "✗", "ok": "✓", "dot": "·", "partial": "!"}
 
 
+def _display_key(key: int | str) -> str:
+    """Render a row key for a human.
+
+    A composite key's canonical text is joined by ASCII Unit Separator, which
+    is exactly right for hashing and unreadable on a terminal. Show the parts
+    separated visibly instead. JSON keeps the raw text, so a machine still sees
+    what was actually compared.
+    """
+    if isinstance(key, str) and "" in key:
+        return " | ".join(_display(part) for part in key.split(""))
+    return _display(key) if isinstance(key, str) else str(key)
+
+
 def _display(value: str) -> str:
     """Make canonical text readable without misrepresenting it.
 
@@ -154,6 +184,12 @@ def _display(value: str) -> str:
 
 
 def render_human(result: DiffResult, out: TextIO) -> None:
+    """Write the report a person reads: verdict first, then the evidence.
+
+    The rows-downloaded percentage is always printed - it is the proof that
+    the tool pushed the work into the engines, and a figure that suddenly
+    reads 100% is how someone finds out their key column is wrong.
+    """
     sym = _symbols(out)
     stats = result.stats
     total = max(stats.rows_compared_a, stats.rows_compared_b)
@@ -220,12 +256,19 @@ def render_human(result: DiffResult, out: TextIO) -> None:
 
 
 def _render_diff(d: RowDiff, out: TextIO) -> None:
+    """Write one difference.
+
+    A changed row shows both values side by side, which is far easier to scan
+    for the character that moved - until the values are too long to share a
+    line, at which point they stack.
+    """
     label = KIND_LABELS[d.kind]
     if d.kind != "different":
-        print(f"  {label:<11} key {d.key}", file=out)
+        print(f"  {label:<11} key {_display_key(d.key)}", file=out)
         return
 
-    print(f"  {label:<11} key {d.key:<14} columns: {', '.join(d.columns)}", file=out)
+    shown_key = _display_key(d.key)
+    print(f"  {label:<11} key {shown_key:<14} columns: {', '.join(d.columns)}", file=out)
     name_w = max((len(c) for c in d.columns), default=0)
     a_vals = {c: _display(d.values_a.get(c, "")) for c in d.columns}
     b_vals = {c: _display(d.values_b.get(c, "")) for c in d.columns}
@@ -246,6 +289,13 @@ def _render_diff(d: RowDiff, out: TextIO) -> None:
 
 
 def to_dict(result: DiffResult) -> dict[str, Any]:
+    """Shape the result for `--json`.
+
+    Carries the raw canonical text rather than the human-friendly rendering,
+    so a machine sees exactly what was compared. `identical` is false whenever
+    the walk was cut short, so a consumer reading only that field cannot be
+    misled by a partial run.
+    """
     stats = result.stats
     moveable = stats.rows_compared_a + stats.rows_compared_b
     return {
@@ -289,6 +339,11 @@ def to_dict(result: DiffResult) -> dict[str, Any]:
 
 
 def _run_diff(args: argparse.Namespace, out: TextIO) -> int:
+    """Open both sides, run the comparison, render it, and return the exit code.
+
+    Both connections are closed even when the diff raises, and each is opened
+    separately so a failure can name which side it was.
+    """
     # Imported here, not at module scope, so `parity --help` works with no
     # database driver installed at all.
     from parity.dialects.base import get_dialect
@@ -303,7 +358,9 @@ def _run_diff(args: argparse.Namespace, out: TextIO) -> int:
             a, b,
             a_table=args.a_table,
             b_table=args.b_table,
-            key=args.key,
+            # Comma-separated for composite keys; a single name is just a
+            # one-element list.
+            key=_split(args.key) or args.key,
             columns=_split(args.columns) or None,
             exclude=_split(args.exclude),
             bisection_factor=args.bisection_factor,
@@ -336,6 +393,13 @@ def main(
     out: TextIO | None = None,
     err: TextIO | None = None,
 ) -> int:
+    """Entry point. Returns the exit code rather than calling sys.exit.
+
+    `out` and `err` are injectable so the tests can drive the real CLI and
+    read what it wrote. Anything that is not a clean verdict returns 2, never
+    1 - a CI job has to be able to tell "the tables differ" from "the tool
+    broke".
+    """
     out = out if out is not None else sys.stdout
     err = err if err is not None else sys.stderr