chtypes 0.3.2__tar.gz → 0.5.0__tar.gz

{chtypes-0.3.2 → chtypes-0.5.0}/CHANGELOG.md

@@ -6,6 +6,44 @@ The four bindings in this repository are released together and give one answer,
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-10-01
+
+**Upgrade together if you share a lock: 0.4.x and earlier refuse a schema-2 lock, and this release writes one.** Schema-1 locks are still read and are converted the next time the lock is written. A server's exact ClickHouse patch now loads when it is installed, or published and autofetch is on; otherwise the newest installed patch of the same line loads, flagged as not exact and warned once per pair, and no request ever crosses to another line. Several patches of one line coexist: the patch a line request selects installs flat as before, and every other patch installs under `patches/<minor>/<version>/`, where an older flat patch is moved rather than deleted. `--frozen` now installs exactly the pinned file, even while a newer one is served. Same ABI revision as 0.4.0 (6), so the artifacts 0.4.0 loads are the ones this release loads. An older Python SDK's refusal reads `ValueError: chtypes: <lock> is not a chtypes lock file (schema 1)`, before any download.
+
+### Added
+
+- **`fetch --lock` now records the artifact's ABI revision** in each lock entry (`abi_revision`, optional and additive); `--frozen` checks it FIRST, before the file/sha256 pin: a lock that names a different revision raises `ArtifactPinnedError`, naming both numbers and the `python -m chtypes fetch` remedy, instead of surfacing as a bare drifted pin or `ArtifactUnpublishedError`. A lock entry with no recorded revision (written by an SDK before this change) keeps today's behavior, with one sentence appended when it ends in one of those two errors. `offline=True, frozen=True` is unaffected (docs/guides/fetch.md §5, closes #253).
+- **Exact-patch resolution (SDK#284).** `Registry.resolve(v)` returns a `Resolution(library, requested, version, exact)`: a minor-line request (`"25.8"`) is always `exact=True`, pinned to the newest reachable patch for as long as the registry stays open; an exact-patch request (`"25.8.28.1-lts"`) loads that patch when it is installed or — with `autofetch` on — published, and otherwise falls back to the newest patch of the same line with `exact=False` and a `PatchFallbackWarning` (new, exported), raised once per (requested, actual) pair per process. Never crosses to another line — that failure is still `ArtifactMissingError`. `for_version` / `registry[v]` run the same resolution and hand back `.library`. A fallen-back patch is re-checked against the search path at most once every 60 seconds per (destination, requested patch), so a patch installed later — by fetch or by hand — is picked up with no restart and no directory read on every call.
+- **`fetch.installed_patches(registry)`** — every installed PATCH under a registry directory (the flat line slot and every other patch under `patches/`), as `InstalledPatch(minor, version, directory, manifest, flat)`. Supersedes `fetch.installed_lines` as the fetch-level listing, which stays, unlisted, as "the one patch a line request loads."
+
+### Changed
+
+- **Several patches of one ClickHouse line now coexist in the cache**, so fetching a second patch no longer overwrites the first. The patch a LINE request selects (`fetch 25.8`) still installs FLAT at `<registry>/<minor>/`, exactly as before; any OTHER exact patch installs at `<registry>/patches/<minor>/<clickhouse_version>/`. When a line fetch changes which patch occupies the flat slot, the outgoing install is DEMOTED — renamed atomically, same filesystem, into `patches/<minor>/<its version>/` — never deleted, before the incoming patch takes the flat slot. Every reader (`Registry`, `list`, `verify`, `installed_patches`) reads both locations; a released (0.4.x and earlier) reader never touches or lists `patches/`, so the two coexist safely in one cache.
+- **Lock schema 2** (`LOCK_SCHEMA = 2`), keyed `<os>-<arch>/<clickhouse_version>` — the exact patch, not the line, so two patches of one line each get their own pin and nothing is silently dropped when a second is fetched. Schema 1 is still read: a `<os-arch>/<minor>` entry converts to its schema-2 key by recovering the exact version from the entry's own pinned `file` name. The first write through an existing schema-1 file rewrites it as schema 2 wholesale — schema is a property of the file, not of one entry. `--frozen` now selects entirely from the lock (never from the release's other rows) and installs exactly the pinned file, even while a newer patch — or a higher build of the same patch — is served: the old "pins X but the release offers Y" refusal is gone. `--all --frozen` installs the newest patch EACH pinned line's lock entries name; a line the release has that the lock does not pin is simply not installed, not a refusal.
+- **fetch.md Decision 7 (a channel-free spelling matches that patch on any channel) now applies to `ensure`'s offline path too** — the request that lands here whenever a live server answers `SELECT version()` with no channel suffix.
+- **Docs: plain `CSV`/`TSV` input also honors `input_format_csv_detect_header` / `input_format_tsv_detect_header`, exactly as a real server does**, because the body is read by ClickHouse's own vendored row readers. The behavior arrived with 0.3.0's switch to those readers; it is now documented (#299).
+
+### Fixed
+
+- **`fetch --lock` without `--frozen` re-pins, as in the other three bindings.** It used to enforce an existing lock entry anyway and refuse a differing one with `CHTYPES_ARTIFACT_PINNED`. That meant the re-lock command the refusal itself names (`--lock` without `--frozen`) was refused too, and the only way out was deleting the lock. Only `--frozen` enforces a pin now (`docs/guides/fetch.md` §5).
+- **An offline exact-patch request without a channel now matches an installed patch that has one** (Decision 7) — `ensure("25.8.28.1", offline=True)` used to raise `CHTYPES_SOURCE_UNREACHABLE` against an installed `25.8.28.1-lts`, because only the REQUESTED spelling had its channel stripped for comparison, never the installed manifest's own version.
+- **An autofetched patch the release does not publish now falls back within its line** instead of raising `ArtifactUnpublishedError` — `Registry`'s lazy fetch used to hand the caller's own patch spelling straight to `ensure`, so it failed hard on an unpublished patch where Go, TypeScript and Rust would quietly serve the line's newest.
+
+## [0.4.0] — 2026-09-30
+
+Speaks ABI revision 6 and refuses revision-5 artifacts. Revision 6 adds the error-code table and the partition key; revision-6 artifacts are published for every ClickHouse line this SDK supports, beside the revision-5 builds that 0.3.x keeps loading.
+
+### Added
+
+- **`Library.error_codes()`** — THIS build's own ClickHouse error-code table (`chs_error_codes`), as an `ErrorCodeTable`: `name(code) -> str | None`, `code(name) -> int | None`, `all()` (ascending) and iteration, over `ErrorCodeEntry(code, name)`. Per `Library` and never package-level, because the table moves between lines — one number names two different errors on 25.8 and 26.2. An unknown or negative code and an unknown name are `None`, never synthesized; names match exactly. Built on the first call and kept on success only: a `NULL` answer raises `ChtypesError` and is never cached; an artifact that predates the symbol raises `UnsupportedError`.
+- **`Schema.set_partition_by(expr)`** — declare the table's partition key; `""` removes it. It follows `set_engine`'s sign rule, not `set_ttl`'s: `SchemaError` for the server's own CREATE-path refusal (e.g. 36 BAD_ARGUMENTS for a non-deterministic key, 549), `UnsupportedError` for a decline (-2 is a key the server accepts but this build will not evaluate).
+- **`RowResult.partition_id`** and **`BatchResult.partition_count`**, both `None` unless the schema declared a key. A batch over `max_partitions_per_insert_block` is an ordinary `Outcome.REJECTED` with `err_code` 252.
+
+### Changed
+
+- **Speaks ABI revision 6, and refuses revision-5 artifacts** — and a revision-5 binding refuses revision-6 ones. Revision 6 only ADDS `chs_error_codes` and `chs_schema_partition_by`; no existing declaration changed. It is still a new number, so a fetch after upgrading downloads revision-6 artifacts into their own `abi6` cache directory, and a directory holding only revision-5 artifacts is refused at load, naming both revisions. Revision-6 artifacts are published by the artifact producer; until they are, this binding has nothing to load.
+- **A TTL on a schema with a `CHECK` constraint is now evaluated.** `Schema.set_ttl` on such a schema used to answer `UnsupportedError`; against revision-6 artifacts it answers as on any other schema, accepting the TTL or giving the server's own refusal. That matches a server, whose TTL validation does not read constraints. The change is in the artifacts, so it arrives with them.
+
 ## [0.3.2] — 2026-09-28
 
 Speaks ABI revision 5, unchanged from 0.3.1: every artifact 0.3.1 loads, this release loads.

{chtypes-0.3.2 → chtypes-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chtypes
-Version: 0.3.2
+Version: 0.5.0
 Summary: Python binding for the chtypes artifacts: ClickHouse's own type system, per version, behind the frozen chs_* C ABI
 Project-URL: Homepage, https://github.com/wave-rf/chtypes
 Project-URL: Repository, https://github.com/wave-rf/chtypes
@@ -84,7 +84,7 @@ A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTE
 
 **`ctypes` releases the GIL for the whole duration of a foreign call**, so the GIL is not the exclusion. The package uses a writer-preferring readers-writer lock per loaded image plus one plain lock per `Schema`; `set_default_settings` and `close` take it exclusively, as the ABI requires. Measured under contention: 27,770 batch reads across 8 threads against 566 concurrent settings swaps, every answer byte-identical to the uncontended one.
 
-**The INSERT column list (ABI revision 5) is a keyword-only `columns` on the same calls** — `schema.row(fmt, raw, columns=["id", "e"])`, and the same argument on `Schema.rows` and `Schema.parse_block`. `None` or an empty sequence is the no-list behavior of every earlier revision; a list makes the data supply exactly those columns, with a listed `EPHEMERAL` value read and in scope for the DEFAULTs that reference it but never stored. This release requires a revision-5 artifact — a revision-4 one is refused at load, naming both revisions.
+**The INSERT column list (ABI revision 5) is a keyword-only `columns` on the same calls** — `schema.row(fmt, raw, columns=["id", "e"])`, and the same argument on `Schema.rows` and `Schema.parse_block`. `None` or an empty sequence is the no-list behavior of every earlier revision; a list makes the data supply exactly those columns, with a listed `EPHEMERAL` value read and in scope for the DEFAULTs that reference it but never stored. The column list needs an artifact of revision 5 or later, and this binding loads only artifacts at its own `chtypes.ABI_REVISION` — any other is refused at load, naming both revisions.
 
 ## Tests
 

{chtypes-0.3.2 → chtypes-0.5.0}/README.md

@@ -66,7 +66,7 @@ A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTE
 
 **`ctypes` releases the GIL for the whole duration of a foreign call**, so the GIL is not the exclusion. The package uses a writer-preferring readers-writer lock per loaded image plus one plain lock per `Schema`; `set_default_settings` and `close` take it exclusively, as the ABI requires. Measured under contention: 27,770 batch reads across 8 threads against 566 concurrent settings swaps, every answer byte-identical to the uncontended one.
 
-**The INSERT column list (ABI revision 5) is a keyword-only `columns` on the same calls** — `schema.row(fmt, raw, columns=["id", "e"])`, and the same argument on `Schema.rows` and `Schema.parse_block`. `None` or an empty sequence is the no-list behavior of every earlier revision; a list makes the data supply exactly those columns, with a listed `EPHEMERAL` value read and in scope for the DEFAULTs that reference it but never stored. This release requires a revision-5 artifact — a revision-4 one is refused at load, naming both revisions.
+**The INSERT column list (ABI revision 5) is a keyword-only `columns` on the same calls** — `schema.row(fmt, raw, columns=["id", "e"])`, and the same argument on `Schema.rows` and `Schema.parse_block`. `None` or an empty sequence is the no-list behavior of every earlier revision; a list makes the data supply exactly those columns, with a listed `EPHEMERAL` value read and in scope for the DEFAULTs that reference it but never stored. The column list needs an artifact of revision 5 or later, and this binding loads only artifacts at its own `chtypes.ABI_REVISION` — any other is refused at load, naming both revisions.
 
 ## Tests
 

{chtypes-0.3.2 → chtypes-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chtypes"
-version = "0.3.2"
+version = "0.5.0"
 description = "Python binding for the chtypes artifacts: ClickHouse's own type system, per version, behind the frozen chs_* C ABI"
 readme = "README.md"
 license = "Apache-2.0"

{chtypes-0.3.2 → chtypes-0.5.0}/src/chtypes/__init__.py

@@ -43,6 +43,7 @@ from __future__ import annotations
 from importlib.metadata import PackageNotFoundError as _PackageNotFound
 from importlib.metadata import version as _package_version
 
+from ._error_codes import ErrorCodeEntry, ErrorCodeTable
 from ._native import ABI_REVISION
 from ._rawjson import RawNumber, quote_bare_denormals
 from .discover import (
@@ -71,6 +72,7 @@ from .errors import (
     ArtifactUnpublishedError,
     ArtifactUntrustedError,
     ChtypesError,
+    PatchFallbackWarning,
     RegistryError,
     SchemaError,
     SourceUnreachableError,
@@ -93,6 +95,7 @@ from .registry import (
     Library,
     Manifest,
     Registry,
+    Resolution,
     Schema,
     default_registry_dir,
     host_platform,
@@ -165,6 +168,8 @@ __all__ = [
     "Computed",
     "DefaultKind",
     "DiscoveredColumn",
+    "ErrorCodeEntry",
+    "ErrorCodeTable",
     "Filter",
     "FilterOutcome",
     "FilterResult",
@@ -173,10 +178,12 @@ __all__ = [
     "Library",
     "Manifest",
     "Outcome",
+    "PatchFallbackWarning",
     "RawNumber",
     "Reason",
     "Registry",
     "RegistryError",
+    "Resolution",
     "RowResult",
     "Schema",
     "SchemaError",

{chtypes-0.3.2 → chtypes-0.5.0}/src/chtypes/__main__.py

@@ -20,7 +20,6 @@ import warnings
 from collections.abc import Sequence
 from pathlib import Path
 
-from ._manifest import Manifest
 from .errors import (
     CODE_ARTIFACT_UNPUBLISHED,
     CODE_SOURCE_UNREACHABLE,
@@ -28,7 +27,7 @@ from .errors import (
     ChtypesError,
     UnsignedArtifactWarning,
 )
-from .fetch import DEFAULT_ARTIFACTS_URL, DEFAULT_TAG, PLATFORMS, ReleaseEntry
+from .fetch import DEFAULT_ARTIFACTS_URL, DEFAULT_TAG, PLATFORMS
 
 __all__ = ["main"]
 
@@ -202,17 +201,20 @@ def _cmd_list(args: argparse.Namespace) -> int:
         _not_shown,
         fetch_destination,
         host_platform,
-        installed_lines,
+        installed_patches,
     )
 
     platform = args.platform or host_platform()
     registry = fetch_destination(args.dest, platform=platform)
-    have = installed_lines(registry)
+    have = installed_patches(registry)
     sys.stdout.write(f"installed ({registry}):\n")
     if not have:
         sys.stdout.write("  (nothing)\n")
-    for minor, (directory, manifest) in have.items():
-        sys.stdout.write(f"  {minor:<8} {manifest.clickhouse_version:<18} {directory}\n")
+    for patch in have:
+        # SDK#284: the flat slot (the patch a LINE request selects) and every
+        # other patch under patches/<minor>/<version>/ both report.
+        tag = "" if patch.flat else "  (patches/)"
+        sys.stdout.write(f"  {patch.minor:<8} {patch.version:<18} {patch.directory}{tag}\n")
     sys.stdout.flush()
 
     fetcher = Fetcher(dest=registry, platform=platform, url=args.url, tag=args.tag, progress=_say)
@@ -222,8 +224,9 @@ def _cmd_list(args: argparse.Namespace) -> int:
     sys.stdout.write(f"release ({release.source}, {signed}) offers for {platform}:\n")
     if not offered:
         sys.stdout.write("  (nothing)\n")
+    installed_versions = {patch.version for patch in have}
     for entry in offered:
-        state = "installed" if _installed(have, entry) else "not installed"
+        state = "installed" if entry.clickhouse_version in installed_versions else "not installed"
         sys.stdout.write(
             f"  {entry.minor:<8} {entry.clickhouse_version:<18} b{entry.build_number:<3} "
             f"{entry.file}  [{state}]\n"
@@ -237,11 +240,6 @@ def _cmd_list(args: argparse.Namespace) -> int:
     return EXIT_OK
 
 
-def _installed(have: dict[str, tuple[object, Manifest]], entry: ReleaseEntry) -> bool:
-    got = have.get(entry.minor)
-    return got is not None and got[1].clickhouse_version == entry.clickhouse_version
-
-
 def _goldens_line(registry: Path) -> None:
     """The served golden set sits beside the artifacts, so "where is my registry"
     and "is my registry sound" are both moments someone wants to know whether it

{chtypes-0.3.2 → chtypes-0.5.0}/src/chtypes/_document.py

@@ -196,6 +196,10 @@ def _row_result(doc: RawObject) -> RowResult:
     verdict_code = _count(doc, "verdict_code")
     verdict_err = _text(doc, "verdict_err")
 
+    # `partition_id` (revision 6) is present exactly when the schema declared
+    # a partition key and this row would be stored; absent is None.
+    partition_id = doc.get("partition_id")
+
     return RowResult(
         outcome=outcome,
         err_code=_count(doc, "code"),
@@ -209,6 +213,7 @@ def _row_result(doc: RawObject) -> RowResult:
         verdict=verdict,
         verdict_code=verdict_code,
         verdict_err=verdict_err,
+        partition_id=partition_id if isinstance(partition_id, str) else None,
     )
 
 
@@ -244,6 +249,7 @@ def parse_batch_document(raw: bytes, payload: bytes | None = None) -> BatchResul
                 verdict=row.verdict,
                 verdict_code=row.verdict_code,
                 verdict_err=row.verdict_err,
+                partition_id=row.partition_id,
             )
         )
         transformed.extend(indexed)
@@ -297,6 +303,11 @@ def parse_batch_document(raw: bytes, payload: bytes | None = None) -> BatchResul
         export_declined=_text(doc, "export_declined"),
         rows_passed=_count(doc, "rows_passed"),
         rows_cut=_count(doc, "rows_cut"),
+        # Revision 6: present exactly when the schema declared a partition
+        # key; absent is None, never a guessed 0.
+        partition_count=_count(doc, "partition_count")
+        if isinstance(doc.get("partition_count"), RawNumber)
+        else None,
     )
 
 

chtypes-0.5.0/src/chtypes/_error_codes.py

@@ -0,0 +1,153 @@
+"""The error-code table (revision 6): one loaded build's own code -> name map.
+
+There is no table in this package, and there must never be one. The table is a
+property of the BUILD: codes join and leave between ClickHouse lines, and one
+number can name two different errors on two lines (903 is LICENSE_EXPIRED on
+25.3 and 25.8, absent on 25.10, and DISTRIBUTED_CACHE_REGISTRY_SHUTDOWN on 26.2
+through 26.9). Every answer
+therefore comes from `Library.error_codes()`, i.e. from `chs_error_codes` of
+the library being asked, and `scripts/check-no-error-code-table.py` fails the
+build if a literal code -> name table appears in any binding.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+
+from .errors import ChtypesError
+
+__all__ = ["ErrorCodeEntry", "ErrorCodeTable"]
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorCodeEntry:
+    """One row of a build's error-code table: a ClickHouse error code and the
+    name THAT BUILD gives it."""
+
+    code: int
+    name: str
+
+
+class ErrorCodeTable:
+    """One loaded library's own error-code table, from `chs_error_codes` —
+    obtained from `Library.error_codes()` and valid for that library's
+    ClickHouse line only. Immutable, so safe to share between threads.
+
+    Lookups answer only what the build's own table holds: an unknown code, a
+    negative code (the ABI's -1 and -2 sentinels included — they are not
+    ClickHouse codes) or an unknown name is `None`, never a synthesized
+    spelling. Names match exactly and case-sensitively, as the server prints
+    them. Iterating yields the entries in ascending code order, as `all()`
+    returns them.
+    """
+
+    __slots__ = ("_by_code", "_by_name", "_entries")
+
+    def __init__(self, entries: tuple[ErrorCodeEntry, ...]) -> None:
+        by_code: dict[int, str] = {}
+        by_name: dict[str, int] = {}
+        kept: list[ErrorCodeEntry] = []
+        for e in entries:
+            # Not a name, not a ClickHouse code, or a repeat: the first entry
+            # for a code or a name wins, and nothing else is invented.
+            if not e.name or e.code < 0 or e.code in by_code or e.name in by_name:
+                continue
+            by_code[e.code] = e.name
+            by_name[e.name] = e.code
+            kept.append(e)
+        self._entries = tuple(sorted(kept, key=lambda e: e.code))
+        self._by_code = by_code
+        self._by_name = by_name
+
+    def name(self, code: int) -> str | None:
+        """The name this build gives `code`, or None."""
+        if code < 0:
+            return None
+        return self._by_code.get(code)
+
+    def code(self, name: str) -> int | None:
+        """The code this build gives `name` — an exact, case-sensitive match —
+        or None."""
+        return self._by_name.get(name)
+
+    def all(self) -> tuple[ErrorCodeEntry, ...]:
+        """Every entry, in ascending code order."""
+        return self._entries
+
+    def __iter__(self) -> Iterator[ErrorCodeEntry]:
+        return iter(self._entries)
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def __repr__(self) -> str:
+        return f"<chtypes.ErrorCodeTable {len(self._entries)} codes>"
+
+
+def parse_error_codes_document(raw: bytes) -> ErrorCodeTable:
+    """Build a table from a `chs_error_codes` document,
+    `{"error_codes":[{"code":N,"name":"…"}, …]}`.
+
+    Unknown keys are ignored and an absent (or null) key is its default, like
+    every document this ABI hands back. A value of the wrong type is a bad
+    document, never a guess.
+    """
+    try:
+        doc = json.loads(raw)
+    except ValueError as exc:
+        raise ChtypesError(f"chtypes: bad chs_error_codes document: {exc}") from exc
+    if not isinstance(doc, dict):
+        raise ChtypesError("chtypes: bad chs_error_codes document: not a JSON object")
+    rows = doc.get("error_codes")
+    if rows is None:
+        rows = []
+    if not isinstance(rows, list):
+        raise ChtypesError("chtypes: bad chs_error_codes document: error_codes is not an array")
+    entries: list[ErrorCodeEntry] = []
+    for row in rows:
+        if not isinstance(row, dict):
+            raise ChtypesError("chtypes: bad chs_error_codes document: an entry is not an object")
+        code = row.get("code")
+        name = row.get("name")
+        if code is None:
+            code = 0
+        if name is None:
+            name = ""
+        if isinstance(code, bool) or not isinstance(code, int) or not isinstance(name, str):
+            raise ChtypesError(f"chtypes: bad chs_error_codes document: entry {row!r}")
+        entries.append(ErrorCodeEntry(code=code, name=name))
+    return ErrorCodeTable(tuple(entries))
+
+
+class _ErrorCodeCache:
+    """One library's table once it has been built, and only then.
+
+    A NULL answer from `chs_error_codes` is a guarded exception inside the
+    library — transient by definition — so it raises `ChtypesError` and is NOT
+    remembered: the next call asks again. A missing symbol raises the decline
+    type and is not remembered either. Only a table that was actually built is
+    kept.
+    """
+
+    __slots__ = ("_mu", "_table")
+
+    def __init__(self) -> None:
+        self._mu = threading.Lock()
+        self._table: ErrorCodeTable | None = None
+
+    def get(self, fetch: Callable[[], bytes | None]) -> ErrorCodeTable:
+        with self._mu:
+            if self._table is not None:
+                return self._table
+            raw = fetch()
+            if raw is None:
+                raise ChtypesError(
+                    "chtypes: chs_error_codes returned no document (a guarded exception "
+                    "inside the library); nothing was cached, so the next call asks again"
+                )
+            table = parse_error_codes_document(raw)
+            self._table = table
+            return table

{chtypes-0.3.2 → chtypes-0.5.0}/src/chtypes/_native.py

@@ -78,6 +78,11 @@ _SIGNATURES: Final[dict[str, tuple[object, list[object]]]] = {
     ),
     "chs_registered_families": (ctypes.c_void_p, []),
     "chs_function_flags": (ctypes.c_void_p, []),
+    # Revision 6: the build's own error-code table, an owned JSON document.
+    # Optional: an artifact that predates it degrades to UnsupportedError at
+    # call time. NULL from a PRESENT symbol is a guarded exception, which is a
+    # different answer — see `error_codes`.
+    "chs_error_codes": (ctypes.c_void_p, []),
     # settings_json + mode compile a column list under a DECLARED settings
     # profile; NULL/"{}" settings_json and mode 0 answer identically to the
     # pre-consolidation, settings-less compile — structurally, not just by
@@ -94,6 +99,9 @@ _SIGNATURES: Final[dict[str, tuple[object, list[object]]]] = {
         [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_char_p, _c_owned_p],
     ),
     "chs_schema_ttl": (ctypes.c_int, [ctypes.c_void_p, ctypes.c_char_p, _c_owned_p]),
+    # Revision 6: the partition key — chs_schema_ttl's exact C shape. The SIGN
+    # rule its return follows is chs_schema_engine's (see Schema.set_partition_by).
+    "chs_schema_partition_by": (ctypes.c_int, [ctypes.c_void_p, ctypes.c_char_p, _c_owned_p]),
     "chs_schema_column_count": (ctypes.c_int, [ctypes.c_void_p]),
     "chs_schema_column_name": (ctypes.c_char_p, [ctypes.c_void_p, ctypes.c_int]),
     "chs_schema_column_type": (ctypes.c_char_p, [ctypes.c_void_p, ctypes.c_int]),
@@ -189,7 +197,10 @@ _SIGNATURES: Final[dict[str, tuple[object, list[object]]]] = {
 # (chs_block_parse / chs_block_free / chs_filter_eval).
 # 5 = the explicit INSERT column list, 2026-09-15: chs_row, chs_rows and
 # chs_block_parse each gained a trailing columns_json.
-ABI_REVISION: Final = 5
+# 6 = the error-code table and the partition key: chs_error_codes and
+# chs_schema_partition_by joined the surface. Purely additive, and still a
+# new number: a revision-6 binding refuses a revision-5 artifact.
+ABI_REVISION: Final = 6
 
 _MANDATORY: Final = (
     "chs_clickhouse_version",
@@ -217,7 +228,8 @@ class _RWLock:
 
     **Readers** are every call that reaches `chs_row`, `chs_rows`,
     `chs_schema_compile`, `chs_schema_engine`, `chs_schema_ttl`,
-    `chs_validate_type` and the column accessors. The C ABI contract
+    `chs_schema_partition_by`, `chs_validate_type`, `chs_error_codes` and the
+    column accessors. The C ABI contract
     §Thread-safety declares those safe together **on distinct handles**, so
     per-handle serialization is `Schema`'s own lock and not this one.
 
@@ -507,6 +519,16 @@ class NativeLibrary:
             raw = self._take(fn())
         return (raw or b"").decode("utf-8", "surrogateescape")
 
+    def error_codes(self) -> bytes | None:
+        """The build's own error-code table as the raw JSON document, or None
+        when the library could not build it (a guarded exception — transient,
+        so the caller must not remember it). A missing symbol raises
+        `UnsupportedError`, which is a different answer: the artifact predates
+        revision 6."""
+        fn = self._need("chs_error_codes", "this artifact predates chs_error_codes (rebuild it)")
+        with self._lock.read():
+            return self._take(fn())
+
     def function_flags(self) -> str:
         """The function-volatility TSV audit, verbatim. Requires chs_init."""
         fn = self._need(
@@ -576,6 +598,17 @@ class NativeLibrary:
             rc = int(fn(ctypes.c_void_p(handle), ttl_sql.encode(), ctypes.byref(err)))
             return rc, self._take_err(err)
 
+    def schema_partition_by(self, handle: int, partition_by: str) -> tuple[int, str]:
+        """(rc, err) from chs_schema_partition_by. The caller maps rc by the
+        SIGN rule chs_schema_engine uses, not chs_schema_ttl's."""
+        fn = self._need(
+            "chs_schema_partition_by", "this artifact predates chs_schema_partition_by (rebuild it)"
+        )
+        err = ctypes.c_void_p()
+        with self._lock.read():
+            rc = int(fn(ctypes.c_void_p(handle), partition_by.encode(), ctypes.byref(err)))
+            return rc, self._take_err(err)
+
     def schema_columns(self, handle: int) -> list[tuple[str, str, str, str, bool]]:
         """(name, type, default_kind, default_expr, default_is_literal) per column."""
         if not self.has_columns:

{chtypes-0.3.2 → chtypes-0.5.0}/src/chtypes/errors.py

@@ -22,6 +22,7 @@ __all__ = [
     "ArtifactUnpublishedError",
     "ArtifactUntrustedError",
     "ChtypesError",
+    "PatchFallbackWarning",
     "RegistryError",
     "SchemaError",
     "SourceUnreachableError",
@@ -181,6 +182,21 @@ class UnsignedArtifactWarning(UserWarning):
     signature check — the one loud warning docs/guides/fetch.md §4 requires."""
 
 
+class PatchFallbackWarning(UserWarning):
+    """Emitted once per (requested, actual) pair per process when a request for
+    an exact ClickHouse patch falls back to the newest installed or published
+    patch of the same line (SDK#284, docs/guides/fetch.md "Version selection").
+
+    Behavior can differ between patches of one line — the reason this change
+    exists at all — so this is a loud, once-per-pair signal, not a debug log
+    line. The pair is recorded BEFORE the warning is emitted, so a caller's
+    own `warnings.filterwarnings("error", category=PatchFallbackWarning)`
+    turning this into an exception does not cause a retry to warn again
+    (design risk R-h): the library has already loaded by the time the warning
+    fires, and the fallback is not undone.
+    """
+
+
 class SchemaError(ChtypesError):
     """ClickHouse itself REFUSED a type expression, a DDL, an engine or a TTL.