chtypes 0.2.2__tar.gz → 0.3.1__tar.gz

chtypes-0.3.1/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog — `chtypes`
+
+All notable changes to the python binding. The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The four bindings in this repository are released together and give one answer, so an entry here has a counterpart in the other three.
+
+## [Unreleased]
+
+## [0.3.1] — 2026-09-26
+
+Speaks ABI revision 5, unchanged from 0.3.0: every artifact 0.3.0 loads, this release loads.
+
+### Changed
+
+- **The publish-window retry (`docs/guides/fetch.md` §3a) now also covers a release-level file whose hash disagrees with its `SHA256SUMS` row** — `sdk-goldens.json`, checked after the requested artifact has already installed, since it is best-effort and never blocks that install — and the retry budget widened from 3 attempts ~10s apart to 5 attempts with delays doubling from 4s (4/8/16/32s, ~60s of sleep, ~70s of wall time with network latency). The artifacts host's edge cache can hold a stale pairing of `SHA256SUMS`, its signature, `index.json` or `sdk-goldens.json` for up to its measured 60-second `Cache-Control: max-age`, wider than the original ~10s budget covered. Every retry now re-reads the WHOLE consistent set fresh — never one freshly re-fetched object checked against another attempt's stale one. A release-level file mismatch that never heals still leaves the golden tests skipping loudly, exactly as before, and never fails the fetch that asked for the artifact (issue #223).
+
+## [0.3.0] — 2026-09-22
+
+### Added
+
+- **Identifier and literal quoting now come from ClickHouse itself: `QuoteIdentifier`, `QuoteIdentifierIfNeeded` and `QuoteLiteral` on a loaded library** (issue #52; each binding spells the three in its own idiom — the parity contract's `library.quote-*` rows carry the four spellings). Each is a passthrough over `chs_quote_identifier`, `chs_quote_identifier_if_needed` or `chs_quote_literal` — the vendored `backQuote`, `backQuoteIfNeed` and `quoteString` that the server's own formatter runs — and nothing else. **`QuoteLiteral` is new surface**: a string value as a ClickHouse string literal, quotes and escapes included, which is exactly what a caller splicing a value into DDL text needed (the value-injection recipe in `docs/guides/transformations.md` told the caller to do it themselves, because no binding exported it). Inputs are **counted**, not NUL-terminated, so a value carrying a NUL byte is quoted correctly; the answer is escaped and therefore NUL-free. They hang off a loaded library rather than off the package because the answers are the LOADED BUILD's own, and `QuoteIdentifierIfNeeded`'s differ between ClickHouse lines — `all`, `distinct`, `table` and `null` are back-quoted on every line this release was tested against, `select` from 26.3, `from` and `values` from 26.5, and `where` stays bare throughout. That is the server's own list of names it treats as problematic unquoted, not a keyword class: do not read it as one. The three symbols joined ABI revision 5 without a revision bump, so an artifact built from a revision-5 header that predates them still reports revision 5 and does not export them; all four bindings degrade to their own "this artifact predates the symbol" decline rather than failing to load. **The per-line answers are not pinned by any test in this repository yet** — they need a revision-5 artifact, none of which is fetchable, and are deferred (#119).
+- **This binding now speaks ABI revision 5.** `Schema.row`, `Schema.rows` and `Schema.parse_block` gain a keyword-only `columns` argument (a sequence of column names) — the INSERT column list: the data supplies exactly those columns, in list order for the positional formats, and the server computes the rest with the listed values in scope for their DEFAULT expressions. `None` or an empty sequence is the no-list behavior of every earlier revision and is marshaled to NULL, never to `"[]"` (an empty column list renders as `INSERT INTO t () FORMAT X`, which is code 62 `SYNTAX_ERROR` on every served ClickHouse line — measured 2026-09-15). A listed `EPHEMERAL` column's value is read and is in scope for the DEFAULTs that reference it, and is still never stored and never exported. This binding does not validate column names locally: an unknown column, an `ALIAS` column, and a repeated name are all refused by the server, with its own codes (16, 16 and 15 respectively), surfaced exactly as they come back.
+- This release **requires revision-5 artifacts**. A revision-4 artifact (or any artifact reporting a `chs_abi_revision()` other than 5 or 0) is refused at load, naming both the binding's revision and the artifact's.
+- **`Source.EPHEMERAL_INPUT` / `Source.MATERIALIZED_INPUT`** name `columns_json`'s two new `Value.source` provenances (revision 5, issue #53): a listed `EPHEMERAL` column's read value (`"ephemeral_input"`) and a listed `MATERIALIZED` column's supplied value under `insert_allow_materialized_columns=1` (`"materialized_input"` — stored, replacing the expression). `Source` is a plain class of `Final` strings, not an `Enum`, the same shape as `Reason` — for the same reason: an unrecognized `src` from a newer artifact must pass through, not raise. **The two get opposite treatment in `RowResult.values`**: `"ephemeral_input"` is never stored, so it is excluded from `values` exactly as `"skipped"` already is — reported only through the per-column result document, never through `values`. `"materialized_input"` IS stored, so it stays IN `values`. The artifact-backed behavior tests (a listed EPHEMERAL/MATERIALIZED column actually producing these values end to end) need a revision-5 artifact, none of which is fetchable yet, and are deferred; the `values` membership rule itself was decidable without one, since "never stored" is definitional rather than something an artifact reveals.
+- **`Source.SKIPPED`** names the `Value.source` provenance the `"skipped"` string has always carried (`MATERIALIZED`/`ALIAS`/`EPHEMERAL`, never read from an input row). The exclusion it names from `RowResult.values` predates revision 5 and was already correct — `_row_result` has special-cased it from the start — it simply had no named constant, only the bare string literal `"skipped"` at the one call site that checks it. Added to the `Source` class alongside `EPHEMERAL_INPUT` / `MATERIALIZED_INPUT`, in the same idiom, so the parity manifest's `results.skipped-excluded-from-values` rule can be keyed on a real symbol instead of four bindings agreeing on a bare literal by coincidence (issue #90). No behavior change: `_row_result` compares against the same string either way.
+- **`Source.DEFAULT_SUBSTITUTED`** names the `Value.source` provenance the `"default_substituted"` string has always carried: a VOLATILE DEFAULT this library resolved locally, which the caller MUST echo as an explicit column on any later INSERT. `_row_result` has populated `RowResult.substituted` for exactly this src value from the start; like `Source.SKIPPED` before it, it simply had no named constant, only the bare string literal `"default_substituted"` at the one call site that checks it. Added to the `Source` class in the same idiom, so the parity manifest's `results.default-substituted-populates-substituted` rule can be keyed on a real symbol instead of four bindings agreeing on a bare literal by coincidence (issue #122). No behavior change: `_row_result` compares against the same string either way.
+- **`Schema.rows` gains `row_filter=`** (revision 5, second half — issue #54, `docs/guides/filters.md` §Exporting only the rows a filter admits): attach a compiled `Filter` to the export channel and get ONE `chs_rows` parse that answers both a per-row filter verdict (`RowResult.verdict`, the same `Verdict` `Filter.rows` already answers) and, for `Verdict.TRUE` rows, the export bytes. `Verdict.ERROR` (the predicate threw) and `Verdict.DECLINE` (declined — including a row whose own `outcome` was not `Outcome.ACCEPTED`) are NEVER exported and NEVER collapsed into `Verdict.FALSE`: collapsing either inverts fail-closed into fail-open, the leak class this vocabulary exists to prevent. `BatchResult.rows_passed`/`rows_cut` join the result. A filter compiled over a different `Schema` of the same loaded library rejects the whole call, loudly (code 1002); one from a different loaded library raises `ChtypesError` before any C call. The lifetime mechanism is the one `compile_filter` already established — reused, not duplicated. The artifact-backed behavior tests need a revision-5 artifact, none of which is fetchable yet, and are deferred; the decode rule and the cross-library refusal were both decidable without one, and are unit-tested against hand-built documents and fake handles.
+- **`CSVWithNames` = 10 and `TSVWithNames` = 11 join the `chs_format` set** (issue #55; ClickHouse's own format names, which each binding spells in its own idiom). **Both numbers are frozen from the day they ship**, like every other `chs_format` value: they are what crosses the C boundary, and they are never renumbered. Each is CSV / TSV whose first row is a header naming the columns, so the data is addressed by name rather than by position. With an INSERT column list as well, the list decides the block and the header decides the layout: a listed column the header omits takes its `DEFAULT` under `input_format_defaults_for_omitted_fields=1` and the reader's zero under `0`, an unlisted column the header names is an unknown field, and an unlisted column takes its `DEFAULT` whatever that setting says. **Header-name matching differs by ClickHouse line: exact through 26.4, case-insensitive from 26.5**, exactly as those servers do, so the same header can bind differently on either side of that boundary. As an export format both are the existing loud decline. They joined the set inside ABI revision 5 without a revision bump, so an artifact built from a revision-5 header that predates them still reports revision 5 and does not know them: **probe the artifact before declaring either format** (`docs/reference/bindings.md` §Values a binding must accept and reject). The round trip through a real artifact needs a revision-5 artifact that supports them, none of which is fetchable yet, and is deferred (#119).
+
+### Changed
+
+- **BREAKING: `QuoteIdentifier` ALWAYS quotes**, and it is a call into the loaded library rather than a function of this binding (issue #52). It used to quote only where it decided quoting was needed, from a hand-written copy of ClickHouse's rule living in the binding; that copy is deleted, not kept as a fallback, because two implementations of one rule is how it came to disagree with the server in the first place. **This changes the bytes a caller gets back** — a name that used to come back bare now comes back quoted — so it can move a cached key, a golden file or a stored test expectation even where the SQL means the same thing. **The one-line migration for a caller who genuinely wanted the old shape is `QuoteIdentifierIfNeeded`**, which is that behavior under a name that says so; read the next two entries before assuming it is byte-for-byte what you had.
+
+- **`QuoteIdentifierIfNeeded` returns `` `all` ``, `` `distinct` ``, `` `table` `` and `` `null` `` back-quoted**, where the hand-written copy returned all four bare. The server back-quotes them on every ClickHouse line this release was tested against, so the copy was simply wrong, and a bare `null` is exactly the shape that parses as something else. This is a behavior change **on top of** the breaking one above: a caller who migrates from `QuoteIdentifier` to `QuoteIdentifierIfNeeded` to keep the old shape still gets different bytes for these four names. Which further names it quotes is the loaded build's own rule and moves between lines (`select` from 26.3, `from` and `values` from 26.5, while `where` stays bare), so an answer cached across versions was never safe and is now visibly so.
+
+- **`QuoteIdentifier` emits the BACKSLASH spelling for an embedded back-quote** — `` `a\`b` `` — where the deleted copy doubled it (``` `a``b` ```). Both spellings parse, on every line, and both round-trip to the same column name; only one is what the server itself prints. That is how two hand-written quoters can each look correct and still disagree, and it is the same failure that produced the `null` divergence above. A caller comparing quoted text against a stored string, rather than passing it straight into DDL, must expect the new spelling.
+
+- **BREAKING: reconstructing DDL from discovered columns is a method on a loaded library.** It was a free function; it is not one any more, because the single thing it spells — the column NAME — is now spelled by the library's own `QuoteIdentifier` instead of by a rule in the binding. Resolve the artifact first (the server's own version string already decides which one) and call reconstruction on it; the arguments, the return and every refusal are unchanged, and the declaration list it produces differs only in how the names are spelled. This was not in the issue's own scope — it is the unavoidable consequence of deleting the hand-written rule, since nothing else in the binding could spell a name afterwards.
+
+- **BREAKING: loading is lazy by default, and `preload` is the one eager path.** Constructing a `Registry` already read manifests and `dlopen`ed nothing — but `libraries()` did not: it opened every discovered line, roughly 120 MB of artifact each, to answer a question about what the registry knows. **`libraries()` now lists what is OPEN and opens nothing**, which is what Go, TypeScript and Rust have always answered, and which also fixes `__iter__`, whose every use inherited those loads. The rule, now true of every surface here: nothing in this library opens an artifact except a request for a specific version, or an explicit `preload` — not `versions()`, not `libraries()`, not `in`, not `len()`, not `repr()` (#50).
+
+  **What a caller who relied on `libraries()` loading must do:** ask for the lines. `for line in registry.versions(): registry.for_version(line)` opens them, or `Registry(dir, preload=["25.8", "26.7"])` opens a named set in order before the constructor returns. `preload` is deliberately a list rather than "everything in the directory", because a registry directory is whatever a fetch left behind. An entry no directory on the search path holds is `ArtifactMissingError` at construction — the same §7 error the first `for_version` would have raised, raised earlier — and it never fetches, even with `autofetch=True`.
+
+- **BREAKING: two new construction errors, both decidable from manifests alone.** A search path on which no directory holds a readable `<minor>/manifest.json` is now `RegistryError` at construction, naming every directory looked in; this was the one binding where `Registry()` could succeed against a completely empty machine and report the miss three calls later. And a directory the CALLER NAMED that does not exist is now an error too, as it already was in Go and TypeScript, rather than being skipped in silence. Both are suppressed with `autofetch=True`, where the directory is the destination the first fetch creates, and `for_version` still re-scans, so a line installed after construction keeps working (#50).
+
+- **`verify_hashes` is unchanged, and the timing is now stated: a library's checksum is computed immediately before that library is `dlopen`ed, and at no other time** — at construction for the `preload`ed lines, at first use for the rest, never for a line nobody asks for. It is a policy on the registry, not a property of the preload list: a lazily-opened line is hashed too (#50).
+
+- **BREAKING: `library_bytes` is now checked on EVERY load, not only under `verify_hashes`** (issue #82, split out of #50 so the behavior change was not hidden inside a larger one). The size check — the file's actual length against the manifest's `library_bytes` — used to run only when verification was on, bundled inside `verify_library`'s hash comparison; Go and TypeScript agreed with Python on that, and Rust did not, checking bytes unconditionally on every load. It is nearly free (one `stat`, never a re-hash of the library's contents) and it catches the commonest shape of a broken artifact directory — a truncated or partially-written library file — so all four bindings now check it unconditionally, and Python stops being three of the four that didn't. The new standalone `check_library_bytes` carries this half; `verify_library` calls it too, so its own behavior is unchanged for a caller who invokes it directly.
+
+  **What changes for a caller who never asked for verification:** an artifact directory whose manifest carries a `library_bytes` that does not match the file on disk now fails the load (`for_version`, and `preload`, which routes through it) with `chtypes: <path> is <n> bytes, manifest says <m>`, refused before `dlopen` is ever attempted. Before this change the same directory reached `dlopen` regardless — usually failing there too, with a less specific error, though a stale-rather-than-corrupt manifest could pass through unnoticed. A manifest with no `library_bytes` at all (`0`, its default for one that predates the field) is unaffected either way: this was never, and is still not, a reason a load fails for a directory with no size to check against.
+
+  **Timing, read together with `verify_hashes`'s rule above:** the size check runs at the exact same point the hash check does — immediately before `dlopen`, at construction for `preload`ed lines and at first use for the rest — because `_load` is the one place both checks live, whether or not verification is on.
+
+- **CSV and TSV rejection messages are now ClickHouse's own text** (with revision-5 artifacts). The error **codes are unchanged**, and so is every verdict and every stored value; only the human-readable message moved, because CSV and TSV rows are now read by ClickHouse's own readers rather than hand-written splitters. A CSV row the reader rejects now carries an **empty `cols` list**, where the previous path could report a partial one. **Match on the error code, never on the message text** — the message is ClickHouse's to change between releases.
+
+- **An empty CSV field under `input_format_defaults_for_omitted_fields=0` is now reported as an input, and its coercion as a transform** (with revision-5 artifacts). Where the previous reader reported no transform, the detector now reports one, because the field's reference value is the empty string rather than absent. The reason follows the column's type — measured as `enum_coerce` for an `Enum`, `fixedstring_pad` for a `FixedString`, and `uuid_mangle` for a `UUID` (the zero UUID). **Stored values are unchanged** — this changes what is reported, not what is stored. A caller that reads "no transform" as "the value was not changed" should expect these rows to report one. Under the default setting (`1`) an empty field still takes the column's `DEFAULT`, as before. **TSV is not affected:** its reader takes an empty field through the typed parse whether the setting is on or off, exactly as the previous splitter did.
+
+- **An unlisted column now takes its `DEFAULT` regardless of `input_format_defaults_for_omitted_fields` when a column list is present** (with revision-5 artifacts). With an INSERT column list, a column the list does not name is computed from its `DEFAULT` expression under `input_format_defaults_for_omitted_fields=0` as well as under the default `1`. This is a fix in the artifact that rides revision 5, and it applies to **every format**, not only `CSVWithNames` and `TSVWithNames`.
+
+- **The rolling artifacts channel now serves ABI revision 5.** A 0.2.x consumer that fetches from the default channel will download an artifact its bindings **refuse at load** — correct behavior that looks exactly like a broken install. ⚠️ **Pinning an exact ClickHouse version does not avoid this**: a relink republishes the same `clickhouse_version`, and an exact request resolves to the highest-ranked matching row, which is the revision-5 one. The only way to stay on revision 4 is `--url` / `--tag` pointed at a source that still serves revision-4 artifacts, if one is retained. **Upgrading to 0.3.0 is the supported path.**
+
+## [0.2.2] — 2026-09-17
+
+### Changed
+
+- **`Registry(..., verify_hashes=True)` now refuses an artifact whose manifest carries no `library_sha256`, instead of loading it silently.** This is a behavior change in a security posture, not a silent fix: previously, asking for verification against a manifest with the field absent returned as if the bytes had been checked, when they never were — the caller believed the load was verified and it was not. `verify_library` now raises `RegistryError` naming the path and saying the manifest carries no `library_sha256`, the same shape its hash-mismatch path has always raised. `verify_hashes` off is unaffected: the field stays optional for a caller who did not ask. Go, TypeScript and Rust already refused this case; this was the one gap issue #13's item A2 left (#48).
+
+### Notes
+
+- Speaks **ABI revision 4**, unchanged since 0.1.0, so no artifact needs relinking. The golden set this release was tested against is the one core serves, generated on the ClickHouse lines 24.8, 25.3, 25.8, 25.10, 26.2, 26.3, 26.4, 26.5, 26.6, 26.7 and 26.8.
+- Seven facts about the compiled library's behavior that a consumer previously had to discover by experiment are now written down: `CHECK`-constraint batch rejection, binding filter parameters as `String`, single-line compact JSON array loss under `allow_errors`, the JSONCompactEachRow export field separator, the value-injection pattern and its compile-time wrap trap, `Columns` as canonical and in declaration order, and the frozen-signatures promise reworded ahead of the next ABI revision (#56). That promise is now stated once, in `docs/support.md`, and linked from everywhere else rather than restated in nine places (#69).
+
+## [0.2.1] — 2026-09-15
+
+Released in step with the Rust crate, which gains `Registry::open` and `Error::LibraryRead`; this binding's public API is unchanged.
+
+### Notes
+
+- Speaks **ABI revision 4**, unchanged since 0.1.0, so no artifact needs relinking. The golden set this release was tested against is the one core serves, generated on the ClickHouse lines 24.8, 25.3, 25.8, 25.10, 26.2, 26.3, 26.4, 26.5, 26.6, 26.7 and 26.8.
+- **The ABI-revision refusal is now run, not assumed.** This binding's suite points a registry at a generated artifact answering the wrong revision and asserts the load is refused naming both numbers, beside a matching-revision control that must load; CI fails the build if either case did not run (#36).
+
+## [0.2.0] — 2026-09-15
+
+### Changed — BREAKING
+
+- **The TypeScript filter verdicts are the wire characters.** `Verdict.True` / `False` / `Error` / `Decline` are now `'t'` / `'f'` / `'e'` / `'d'`, which Go, Python and Rust have always rendered. TypeScript alone spelled them `'true'` / `'false'` / `'error'` / `'decline'`, so two SDKs could not share a log line, a fixture or a test. The four states and the fail-closed rule are unchanged: `'e'` and `'d'` are NOT answers, and a caller enforcing visibility must hide the row or fail the request on both — collapsing either into `false` inverts fail-closed into fail-open, the measured leak class. Only the rendered characters moved. **The parity suites now ENFORCE the shared value in all four bindings**; until this release two of the four merely declared it.
+
+- **TypeScript `FetchError` now extends `ArtifactError` (and so `RegistryError`), where it previously extended `ChtypesError` directly.** A `try`/`catch` chain that tests `RegistryError` before `FetchError` now takes the `RegistryError` arm for the five fetch verdicts, which it did not before. Ordering a catch chain most-specific-first is unaffected.
+
+### Added
+
+- **Load-time checksum verification in Go and Rust**, matching what Python and TypeScript have always offered: re-hash the library against `manifest.json`'s `library_sha256` **before `dlopen`**, and refuse the load on a mismatch. Off by default in all four. Whether an artifact was re-hashed before being mapped used to depend on which binding a consumer picked, which is a security posture and not an API spelling. A manifest carrying no `library_sha256` is refused by Go, TypeScript and Rust — verification asked for and not possible is not verification — while Python's returns silently, which is what remains of issue #13's item A2.
+- **One catchable artifact error in TypeScript.** `ArtifactError` is a new exported base: all six artifact conditions now extend it, where `ArtifactMissingError` previously sat under `RegistryError` and the other five under `FetchError`, so a caller had to catch two unrelated types. Every existing `code` value and message is unchanged, and `ArtifactMissingError instanceof RegistryError` still holds.
+- **Eight constants that three bindings exported and the fourth did not**, so a caller no longer retypes a literal the other SDKs hand them: `Registry.SearchPath()` (go), `parse_signature_file` and `FETCH_COMMAND` (python), `RELEASE_KEY_ID` and `DEFAULT_LOCK_FILE` (ts), `fetch::LOCK_SCHEMA` (rust), and `CHTYPES_REGISTRY` / `CHTYPES_AUTOFETCH` as `EnvRegistry` / `EnvAutoFetch` (go) and `ENV_REGISTRY` / `ENV_AUTOFETCH` (ts). Each new name replaces the inline literal in its own binding's code path, so there is one definition rather than two.
+
+### Notes
+
+- Speaks **ABI revision 4**, unchanged since 0.1.0, so no artifact needs relinking. The golden set this release was tested against is the one core serves, generated on the ClickHouse lines 24.8, 25.3, 25.8, 25.10, 26.2, 26.3, 26.4, 26.5, 26.6, 26.7 and 26.8.
+- `Library` still has no scope-based release in Python or TypeScript, while `Registry`, `Schema`, `Filter` and `Block` do. That asymmetry is deliberate — a `with library:` or `using library` closes at the end of a block, which is the mid-lifecycle teardown measured to segfault on the next open — and it is now recorded in the parity manifest so no future audit reopens it as a gap.
+
+## [0.1.2] — 2026-09-11
+
+### Changed — BREAKING
+
+- **The transform reason for a materialized DEFAULT is now `default_materialized`** — previously the same word spelled with an `s` — and the exported constant naming it is now `Reason.DEFAULT_MATERIALIZED`. ClickHouse's own keyword is `MATERIALIZED`; its parser rejects the `s` spelling outright with a syntax error, so the reason naming that concept now matches the system it describes. Code comparing against the old string or the old constant name must be updated.
+- This is an SDK-only change and **the ABI is untouched: it remains revision 4, and no artifact needs relinking.** The reason is derived in the binding, not received from the artifact — the library emits `default_substituted`, which each binding translates. That wire value is unchanged.
+
+### Changed
+
+- **The per-language README is now an orientation page, not a manual.** It carries install, a quickstart that runs, the three outcomes and the error model, and then points at `docs/` for the rest — roughly 450 lines of reference prose moved to `docs/guides/` and `docs/reference/` rather than being repeated four times and drifting four ways.
+- **The published packages no longer cite a repository you cannot open.** 148 source comments — in every binding and in `include/chtypes.h`, all of which ship inside the crate, the sdist and the module — attributed the contract they implement to a private repository's specification. They now cite **the C ABI contract**, with `include/chtypes.h` as the public authority for it. Alongside those, 14 dead paths into that repository, the examples' instruction to build an artifact there, and two descriptions of the signing infrastructure are gone. What remains is every place where the two-repository split is itself the subject — describing it in prose is honest and stays legal; naming something a reader cannot open is not, and `scripts/lint-public.sh` is what enforces the difference. (An earlier draft of this entry enumerated three files. That count was never checked and was wrong by eighteen, which is the same mistake the entry above is about: the rule is checkable, a file list is not.)
+- `scripts/lint-public.sh` is new and blocking in CI, because the sweep this replaces reported itself complete while 148 of its targets survived in a different shape. It refuses both the private repository's name and that exact prose pointer, and its `--selftest` proves each rule fires rather than assuming it.
+
+## [0.1.1] — 2026-09-11
+
+- **The golden set is served, not tracked.** `goldens/cases.json` no longer exists in this repository. Core publishes `sdk-goldens.json` in the rolling release as a row in the signed `SHA256SUMS`; `scripts/fetch.sh` installs it at `<registry>/sdk-goldens.json` and the golden test reads it offline from there (`CHTYPES_GOLDENS` overrides). A case runs only against the exact ClickHouse version `generated.exact` names for its line and skips loudly otherwise, so the set shrinks as lines are added rather than recording an answer twice.
+- **Artifact identity gained a wrapper build.** Assets are `chtypes-<version>-<os>-<arch>-b<N>.tar.gz`, where `<N>` is the core commit's UNIX timestamp; an absent suffix means build 0 and stays valid. Line resolution ranks by `(version, build)`, so a rebuild of a line supersedes the older build.
+- Fetching now retries the publish window, so a fetch that races a release no longer fails on sums naming a file the host has not finished serving.
+- README install instructions name the published package rather than a path dependency.
+- Two errors in the published README, both found by running the snippets rather than reading them: Python's `substituted` is on `RowResult`, not `BatchResult`, and TypeScript's `using schema = …` is a syntax error on Node 22, this package's own `engines` floor (`schema.close()` is portable).
+- `docs/support.md` is new: which language versions, platforms and ClickHouse lines are supported, generated from the manifests and the release's own index.
+
+## [0.1.0] — 2026-09-10
+
+First release, published to PyPI from the tag `python/v0.1.0`.
+
+- Speaks **ABI revision 4** of the frozen `chs_*` C ABI (`include/chtypes.h`, 28 functions). The binding `dlopen`s a per-version artifact and reimplements no ClickHouse semantics; `Transformed` is the one derived result.
+- Verified against the public golden set (`goldens/cases.json`, schema 1, 31 cases), whose expectations were generated on ClickHouse 24.8, 25.3, 25.8, 25.10, 26.5, 26.6 and 26.7 — every case answered identically on all seven lines, and any case that did not was refused by the generator.
+- Pre-1.0: the artifact name `libchtypes`, the `chs_` prefix and the `enum chs_format` numbers are frozen. Function signatures freeze at this tag.

{chtypes-0.2.2 → chtypes-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chtypes
-Version: 0.2.2
+Version: 0.3.1
 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
@@ -76,7 +76,7 @@ A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTE
 | [Filters](https://github.com/wave-rf/chtypes/blob/main/docs/guides/filters.md) · [Multi-version](https://github.com/wave-rf/chtypes/blob/main/docs/guides/multi-version.md) | boolean expressions over rows; several ClickHouse versions in one process    |
 | [Support matrix](https://github.com/wave-rf/chtypes/blob/main/docs/support.md) · [Limitations](https://github.com/wave-rf/chtypes/blob/main/docs/limitations.md)            | what works where; what chtypes declines to answer                            |
 
-## Three things specific to this binding
+## Four things specific to this binding
 
 **A settings value must never be a `float`.** `encode_settings` stringifies an `int` exactly and raises `TypeError` on a `float`: a 19-digit `chtypes_now_epoch_nanos` does not survive an IEEE double, and as a JSON number the setting would be silently ignored.
 
@@ -84,6 +84,8 @@ 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.
+
 ## Tests
 
 `uv run pytest -q`. Tests that need an artifact **skip loudly by name** without a registry on the search path, and a suite that ran nothing fails. The fetch suite runs offline against the miniature releases in `tests/fixtures/fetch/` through `file://` sources and the test key.

{chtypes-0.2.2 → chtypes-0.3.1}/README.md

@@ -58,7 +58,7 @@ A bad **row** is a verdict, not an exception: `outcome` becomes `Outcome.REJECTE
 | [Filters](https://github.com/wave-rf/chtypes/blob/main/docs/guides/filters.md) · [Multi-version](https://github.com/wave-rf/chtypes/blob/main/docs/guides/multi-version.md) | boolean expressions over rows; several ClickHouse versions in one process    |
 | [Support matrix](https://github.com/wave-rf/chtypes/blob/main/docs/support.md) · [Limitations](https://github.com/wave-rf/chtypes/blob/main/docs/limitations.md)            | what works where; what chtypes declines to answer                            |
 
-## Three things specific to this binding
+## Four things specific to this binding
 
 **A settings value must never be a `float`.** `encode_settings` stringifies an `int` exactly and raises `TypeError` on a `float`: a 19-digit `chtypes_now_epoch_nanos` does not survive an IEEE double, and as a JSON number the setting would be silently ignored.
 
@@ -66,6 +66,8 @@ 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.
+
 ## Tests
 
 `uv run pytest -q`. Tests that need an artifact **skip loudly by name** without a registry on the search path, and a suite that ran nothing fails. The fetch suite runs offline against the miniature releases in `tests/fixtures/fetch/` through `file://` sources and the test key.

{chtypes-0.2.2 → chtypes-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chtypes"
-version = "0.2.2"
+version = "0.3.1"
 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.2.2 → chtypes-0.3.1}/src/chtypes/__init__.py

@@ -54,7 +54,6 @@ from .discover import (
     parse_changed_settings_result,
     parse_columns_result,
     parse_version_result,
-    reconstruct_ddl,
 )
 from .errors import (
     CODE_ARTIFACT_CORRUPT,
@@ -120,6 +119,7 @@ from .results import (
     Outcome,
     Reason,
     RowResult,
+    Source,
     Span,
     Substitution,
     Transform,
@@ -181,6 +181,7 @@ __all__ = [
     "Schema",
     "SchemaError",
     "ServerProfile",
+    "Source",
     "SourceUnreachableError",
     "Span",
     "Substitution",
@@ -199,7 +200,6 @@ __all__ = [
     "parse_version_result",
     "quote_bare_denormals",
     "read_manifest",
-    "reconstruct_ddl",
     "registry_search_path",
     "verify_library",
 ]

{chtypes-0.2.2 → chtypes-0.3.1}/src/chtypes/_document.py

@@ -20,6 +20,7 @@ from .results import (
     FilterRowError,
     Outcome,
     RowResult,
+    Source,
     Span,
     Substitution,
     Transform,
@@ -153,8 +154,13 @@ def _row_result(doc: RawObject) -> RowResult:
     for entry in cols if isinstance(cols, list) else ():
         col = _col_doc(entry)
         # MATERIALIZED / ALIAS / EPHEMERAL are never read from an input row and
-        # are not part of the stored row a subscriber would SELECT.
-        if col.src == "skipped":
+        # are not part of the stored row a subscriber would SELECT. A listed
+        # EPHEMERAL column's ephemeral_input value IS read but is never
+        # stored either, so it is excluded here too — exactly as Source.SKIPPED
+        # is — never sitting where a caller reads the stored row (issue #53).
+        # materialized_input stays IN: it IS stored, replacing the column's
+        # expression.
+        if col.src in (Source.SKIPPED, Source.EPHEMERAL_INPUT):
             continue
         values.append(
             Value(
@@ -164,7 +170,7 @@ def _row_result(doc: RawObject) -> RowResult:
                 source=col.src,
             )
         )
-        if col.src == "default_substituted":
+        if col.src == Source.DEFAULT_SUBSTITUTED:
             substituted.append(Substitution(column=col.name, expr=col.input, text=col.stored))
         transformed.extend(classify(col))
 
@@ -180,6 +186,16 @@ def _row_result(doc: RawObject) -> RowResult:
             )
         )
 
+    # `verdict` (RowsExportWith's Python spelling: `rows(..., row_filter=)`)
+    # is present exactly when a filter was attached to the call that
+    # produced this document — absent from every Row/Rows document and from
+    # `rows()` with no `row_filter`. `Verdict.of` degrades an unrecognized
+    # character to DECLINE, never to an invented answer.
+    verdict_char = _text(doc, "verdict")
+    verdict = Verdict.of(verdict_char) if verdict_char else None
+    verdict_code = _count(doc, "verdict_code")
+    verdict_err = _text(doc, "verdict_err")
+
     return RowResult(
         outcome=outcome,
         err_code=_count(doc, "code"),
@@ -190,6 +206,9 @@ def _row_result(doc: RawObject) -> RowResult:
         unsupported_settings=unsupported_settings,
         substituted=tuple(substituted),
         computed=tuple(computed),
+        verdict=verdict,
+        verdict_code=verdict_code,
+        verdict_err=verdict_err,
     )
 
 
@@ -222,6 +241,9 @@ def parse_batch_document(raw: bytes, payload: bytes | None = None) -> BatchResul
                 unsupported_settings=row.unsupported_settings,
                 substituted=row.substituted,
                 computed=row.computed,
+                verdict=row.verdict,
+                verdict_code=row.verdict_code,
+                verdict_err=row.verdict_err,
             )
         )
         transformed.extend(indexed)
@@ -273,6 +295,8 @@ def parse_batch_document(raw: bytes, payload: bytes | None = None) -> BatchResul
         payload=payload,
         spans=spans,
         export_declined=_text(doc, "export_declined"),
+        rows_passed=_count(doc, "rows_passed"),
+        rows_cut=_count(doc, "rows_cut"),
     )
 
 

{chtypes-0.2.2 → chtypes-0.3.1}/src/chtypes/_manifest.py

@@ -85,26 +85,56 @@ def read_manifest(version_dir: str | os.PathLike[str]) -> Manifest | None:
         return None
 
 
+def check_library_bytes(
+    version_dir: str | os.PathLike[str], manifest: Manifest | None = None
+) -> None:
+    """Compare the shared library's on-disk size to the manifest's ``library_bytes``.
+
+    Unconditional on the load path, unlike ``verify_library``'s hash check
+    below (issue #82): nearly free (one ``stat``, never a re-hash of the
+    library's contents), and it catches the commonest shape of a broken
+    artifact directory -- a truncated or partially-written library file.
+
+    A manifest with no ``library_bytes`` (0, its default for one that
+    predates the field) is not asked, so this is a no-op for one: a
+    directory with no size to compare against must never become a new
+    reason a load fails.
+    """
+    directory = Path(version_dir)
+    if manifest is None:
+        manifest = read_manifest(directory)
+        if manifest is None:
+            raise RegistryError(f"chtypes: no usable manifest.json in {directory}")
+    if not manifest.library_bytes:
+        return
+    path = directory / manifest.library
+    try:
+        size = path.stat().st_size
+    except OSError as exc:
+        raise RegistryError(f"chtypes: {path}: {exc}") from exc
+    if size != manifest.library_bytes:
+        raise RegistryError(
+            f"chtypes: {path} is {size} bytes, manifest says {manifest.library_bytes}"
+        )
+
+
 def verify_library(version_dir: str | os.PathLike[str]) -> None:
     """Re-hash the shared library and compare it against the manifest.
 
     The artifact carries its own checksum, so this is neither optional nor
     expensive for anything that arrived over a network: a move that reported
     success and truncated a 232 MB library looks identical to one that worked.
+    The size check ahead of the hash, ``check_library_bytes``, ALSO runs
+    unconditionally on the load path outside of verification (issue #82);
+    calling it here too keeps this function's own behavior unchanged for a
+    caller who invokes it directly.
     """
     directory = Path(version_dir)
     manifest = read_manifest(directory)
     if manifest is None:
         raise RegistryError(f"chtypes: no usable manifest.json in {directory}")
+    check_library_bytes(directory, manifest)
     path = directory / manifest.library
-    try:
-        size = path.stat().st_size
-    except OSError as exc:
-        raise RegistryError(f"chtypes: {path}: {exc}") from exc
-    if manifest.library_bytes and size != manifest.library_bytes:
-        raise RegistryError(
-            f"chtypes: {path} is {size} bytes, manifest says {manifest.library_bytes}"
-        )
     if not manifest.library_sha256:
         raise RegistryError(
             f"chtypes: {path} cannot be verified: manifest carries no library_sha256"

{chtypes-0.2.2 → chtypes-0.3.1}/src/chtypes/_native.py

@@ -60,6 +60,22 @@ _SIGNATURES: Final[dict[str, tuple[object, list[object]]]] = {
     "chs_free": (None, [ctypes.c_void_p]),
     "chs_validate_type": (ctypes.c_int, [ctypes.c_char_p, _c_owned_p, _c_int_p, _c_owned_p]),
     "chs_reference_type": (ctypes.c_void_p, [ctypes.c_char_p]),
+    # Revision 5, additive: the quoting trio, straight off the vendored
+    # backQuote / backQuoteIfNeed / quoteString. The input is COUNTED — a
+    # literal may carry a NUL byte, so the length is the contract and
+    # `strlen` is not — and the answer arrives in a `char **` out-param.
+    "chs_quote_identifier": (
+        ctypes.c_int,
+        [ctypes.c_char_p, ctypes.c_size_t, _c_owned_p, _c_owned_p],
+    ),
+    "chs_quote_identifier_if_needed": (
+        ctypes.c_int,
+        [ctypes.c_char_p, ctypes.c_size_t, _c_owned_p, _c_owned_p],
+    ),
+    "chs_quote_literal": (
+        ctypes.c_int,
+        [ctypes.c_char_p, ctypes.c_size_t, _c_owned_p, _c_owned_p],
+    ),
     "chs_registered_families": (ctypes.c_void_p, []),
     "chs_function_flags": (ctypes.c_void_p, []),
     # settings_json + mode compile a column list under a DECLARED settings
@@ -84,14 +100,30 @@ _SIGNATURES: Final[dict[str, tuple[object, list[object]]]] = {
     "chs_schema_column_default_kind": (ctypes.c_char_p, [ctypes.c_void_p, ctypes.c_int]),
     "chs_schema_column_default_expr": (ctypes.c_char_p, [ctypes.c_void_p, ctypes.c_int]),
     "chs_schema_column_default_is_literal": (ctypes.c_int, [ctypes.c_void_p, ctypes.c_int]),
+    # Revision 5: chs_row gains a trailing columns_json (the INSERT column
+    # list). The ABI-revision gate below guarantees this 6-argument
+    # declaration describes the loaded artifact before any call is made
+    # through it: a rev-4 artifact (5-argument shape) is refused at load.
     "chs_row": (
         ctypes.c_void_p,
-        [ctypes.c_void_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_size_t, ctypes.c_char_p],
+        [
+            ctypes.c_void_p,
+            ctypes.c_int,
+            ctypes.c_char_p,
+            ctypes.c_size_t,
+            ctypes.c_char_p,
+            ctypes.c_char_p,
+        ],
     ),
     # Revision 3: chs_rows carries export_format / doc_flags / out_bytes
-    # (the C ABI contract §Rows). The ABI-revision gate below is what guarantees
-    # this 8-argument declaration describes the loaded artifact before any
-    # call is made through it.
+    # (the C ABI contract §Rows). Revision 5 appends columns_json after
+    # out_bytes and then, in the same open window, the attached row filter
+    # LAST. This binding never attaches one and passes NULL — today's
+    # behavior byte for byte — but the parameter is DECLARED, because calling
+    # a ten-parameter symbol through a nine-parameter declaration leaves the
+    # callee reading the filter slot from whatever happened to occupy it. The
+    # ABI-revision gate below is what guarantees this 10-argument declaration
+    # describes the loaded artifact before any call is made through it.
     "chs_rows": (
         ctypes.c_void_p,
         [
@@ -103,6 +135,8 @@ _SIGNATURES: Final[dict[str, tuple[object, list[object]]]] = {
             ctypes.c_int,
             ctypes.c_uint,
             ctypes.POINTER(_ChsBytes),
+            ctypes.c_char_p,
+            ctypes.c_void_p,
         ],
     ),
     # Revision 3: the filter trio (the C ABI contract §Filters). Optional symbols —
@@ -125,6 +159,7 @@ _SIGNATURES: Final[dict[str, tuple[object, list[object]]]] = {
     ),
     # Revision 4: the block twin (the C ABI contract §Blocks) — parse a body once,
     # evaluate K filters against the block. Optional, same degradation rule.
+    # Revision 5 appends columns_json, LAST, after out_err.
     "chs_block_parse": (
         ctypes.c_void_p,
         [
@@ -135,6 +170,7 @@ _SIGNATURES: Final[dict[str, tuple[object, list[object]]]] = {
             ctypes.c_char_p,
             _c_int_p,
             _c_owned_p,
+            ctypes.c_char_p,
         ],
     ),
     "chs_block_free": (None, [ctypes.c_void_p]),
@@ -151,7 +187,9 @@ _SIGNATURES: Final[dict[str, tuple[object, list[object]]]] = {
 # 4 = the filter phase-2 cycle, 2026-08-31: chs_filter_compile gained
 # params_json ({name:Type} query parameters) and the block twin joined
 # (chs_block_parse / chs_block_free / chs_filter_eval).
-ABI_REVISION: Final = 4
+# 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
 
 _MANDATORY: Final = (
     "chs_clickhouse_version",
@@ -434,6 +472,31 @@ class NativeLibrary:
             raw = self._take(fn(type_expr.encode()))
         return (raw or b"").decode("utf-8", "surrogateescape")
 
+    # -- quoting -----------------------------------------------------------
+
+    def quote(self, symbol: str, text: bytes) -> tuple[str, int, str]:
+        """(quoted, code, err) from one of the three `chs_quote_*` symbols.
+
+        The input is COUNTED, so `text` is bytes and its length is passed
+        explicitly: a string literal may legally carry a NUL byte and
+        `strlen` would truncate it. The answer is always NUL-free — every
+        byte the server escapes comes back escaped — so reading it as a C
+        string is exact, not a best effort.
+        """
+        fn = self._need(symbol, f"this artifact predates {symbol} (rebuild it)")
+        quoted = ctypes.c_void_p()
+        err = ctypes.c_void_p()
+        with self._lock.read():
+            rc = int(fn(text, len(text), ctypes.byref(quoted), ctypes.byref(err)))
+            # Both out-params are taken on EVERY path, success or failure:
+            # the library owns whatever it wrote, and an answer left behind
+            # on an error return is a leak nothing else can reach.
+            raw = self._take(quoted.value)
+            message = self._take_err(err)
+        if rc != 0:
+            return "", rc, message
+        return (raw or b"").decode("utf-8", "surrogateescape"), 0, ""
+
     def registered_families(self) -> str:
         """The newline-separated family list, verbatim."""
         fn = self._need(
@@ -538,7 +601,18 @@ class NativeLibrary:
 
     # -- rows --------------------------------------------------------------
 
-    def row(self, handle: int, fmt: int, raw: bytes, settings_json: str) -> bytes:
+    def row(
+        self,
+        handle: int,
+        fmt: int,
+        raw: bytes,
+        settings_json: str,
+        columns_json: str | None = None,
+    ) -> bytes:
+        """`columns_json` (revision 5) is the INSERT column list, already
+        JSON-encoded, or None for "no list" — passed through to the C side as
+        NULL, never as the literal string `"[]"` (the caller-facing rule is
+        `Schema.row`'s; this layer only forwards what it is given)."""
         fn = self._fn.get("chs_row")
         if fn is None:
             raise UnsupportedError("this artifact predates chs_row (rebuild it)")
@@ -546,7 +620,14 @@ class NativeLibrary:
             # NUL bytes are legal inside a RowBinary body, so the length is
             # passed explicitly and `strlen` is never involved.
             out = self._take(
-                fn(ctypes.c_void_p(handle), fmt, raw, len(raw), settings_json.encode())
+                fn(
+                    ctypes.c_void_p(handle),
+                    fmt,
+                    raw,
+                    len(raw),
+                    settings_json.encode(),
+                    columns_json.encode() if columns_json is not None else None,
+                )
             )
         if out is None:
             raise UnsupportedError("this artifact predates chs_row (rebuild it)")
@@ -560,11 +641,20 @@ class NativeLibrary:
         settings_json: str,
         export_format: int,
         doc_flags: int,
+        columns_json: str | None = None,
+        filter_handle: int | None = None,
     ) -> tuple[bytes, bytes | None]:
         """(document, payload). `export_format` is -1 (CHS_EXPORT_NONE — no
         export, payload None) or an `enum chs_format` value; `doc_flags` the
         CHS_DOC_* bitmask. Both ride through UNVALIDATED — an unknown value is
         the library's loud refusal to make, never this binding's guess.
+        `columns_json` (revision 5) is the INSERT column list, already
+        JSON-encoded, or None for "no list" — forwarded as NULL, never `"[]"`.
+
+        `filter_handle` (revision 5, second half) is the attached row filter
+        — None (the default) is "no filter", today's behavior byte for byte.
+        `Schema.rows`'s `row_filter=` is the only caller that ever passes one;
+        every other call site forwards None exactly as before.
 
         Ownership: the export buffer is COPIED into a Python `bytes` and the
         C side's `data` freed with THIS library's `chs_free` before returning
@@ -583,6 +673,8 @@ class NativeLibrary:
                 export_format,
                 doc_flags,
                 ctypes.byref(out_bytes) if out_bytes is not None else None,
+                columns_json.encode() if columns_json is not None else None,
+                ctypes.c_void_p(filter_handle) if filter_handle is not None else None,
             )
             payload: bytes | None = None
             if out_bytes is not None and out_bytes.data:
@@ -641,11 +733,18 @@ class NativeLibrary:
     # -- blocks --------------------------------------------------------------
 
     def block_parse(
-        self, handle: int, fmt: int, body: bytes, settings_json: str
+        self,
+        handle: int,
+        fmt: int,
+        body: bytes,
+        settings_json: str,
+        columns_json: str | None = None,
     ) -> tuple[int | None, int, str]:
         """(block handle, code, err). code/err meaningful only on None — a
         call-level failure (unknown setting 115, framing, a binary decode
         fault) yields no block and no partial answers (the C ABI contract §Blocks).
+        `columns_json` (revision 5) is the INSERT column list, already
+        JSON-encoded, or None for "no list" — forwarded as NULL, never `"[]"`.
         """
         fn = self._need("chs_block_parse", "this artifact predates chs_block_parse (rebuild it)")
         code = ctypes.c_int(0)
@@ -659,6 +758,7 @@ class NativeLibrary:
                 settings_json.encode(),
                 ctypes.byref(code),
                 ctypes.byref(err),
+                columns_json.encode() if columns_json is not None else None,
             )
             if not bhandle:
                 return None, int(code.value), self._take_err(err)