Bind null query params as SQL NULL (\N), matching @clickhouse/client

[dfrankland]

What

formatParamValue (the {name:Type} server-side param serializer) now emits the
TSV null marker \N for a top-level null/undefined, instead of throwing
ChdbBindError. This makes null params bind as SQL NULL for Nullable
placeholders — the same behavior as @clickhouse/client-common's
formatQueryParams.

Nested nulls (inside an Array/Map param) were already rendered as the NULL
keyword by serializeValue, which also matches the reference client, so the only
change is the top-level branch.

Why

chdb-node is a byte-compatible @clickhouse/client façade (#49, #52). The
reference client serializes null as \N (or the NULL keyword when nested);
the server accepts that for Nullable columns. Throwing on null was a
divergence, not an engine limitation.

Fixes #67.

Behavior change

• queryBind('SELECT {v:Nullable(String)}', { v: null }) → binds SQL NULL
  (was: ChdbBindError).
• null against a non-Nullable placeholder is now rejected by the engine
  (a CHDB_* query error), exactly as the HTTP client + server behave — instead
  of a client-side ChdbBindError.
• The literal string "NULL" is still bound as the string "NULL", not coerced
  to null (only \N is the marker).

This is the intended compatibility semantics, but it does change the error type
for the non-Nullable case (bind-time → query-time), so calling it out.

Verification

\N binding confirmed end-to-end against the native chdb_query_with_params
path:

param	placeholder	result
\N	Nullable(String)	null (IS NULL=1)
\N	Nullable(Int64)	null (IS NULL=1)
[1,NULL,3]	Array(Nullable(Int64))	[1, null, 3]
"NULL"	Nullable(String)	"NULL" (not coerced)
\N	Int64	engine error

The diff

 export function formatParamValue(value: unknown): string {
-  if (value === null || value === undefined) {
-    throw new ChdbBindError(
-      'null/undefined parameter values are not supported; omit the parameter or use a typed NULL in SQL',
-    )
-  }
+  if (value === null || value === undefined) return '\\N'
   if (typeof value === 'string') return tsvEscape(value)
   ...

Parity suite

This removes the two NULL-binding entries from tests/clickhouse-js/skip_list.json
and they now pass. Verified with the parity runner against @clickhouse/client
1.23.0 (ChdbConnection injected, :memory:):

✓ … select with query binding > NULL parameter binding > should work with nulls
✓ … select with query binding > NULL parameter binding > should with an explicit undefined
  Test Files  1 passed (1)
       Tests  20 passed | 9 skipped (0 failed)

(The remaining 9 skips in that spec are the unrelated Tuple/Map/nested-boolean
compound-type divergences — see Scope below.)

Tests

• test/v3/serialize.test.ts: formatParamValue unit block — null/undefined
  → \N, nested null → NULL keyword, TSV escaping, and non-finite/unsafe/
  unserializable values still throw.
• test/v3/querybind.test.ts: split the old "rejects null" case into
  (a) a Nullable placeholder binds null as SQL NULL end-to-end, and
  (b) the engine rejects null against a non-Nullable placeholder.

All affected test/v3 suites pass (serialize.test.ts + querybind.test.ts: 26/26).

Scope / non-goals

This PR only covers a top-level scalar null/undefined. It does NOT touch
the adjacent compound-type parameter-serialization divergences still tracked in
skip_list.json, which have a different root cause (the engine parser rejecting
chdb-node's composite param form):

• Map(K, Nullable(V)) — nested null already serialized as the NULL keyword
  before this PR; the Map param form itself is what the engine rejects.
• Tuple params — chdb-node emits {'field':value}, the engine wants positional
  (v1, v2, …) (also affects Array(Tuple), Map(K, Tuple), and booleans
  nested inside tuples).

Explicitly out of scope as intentional design (see
docs/design/layer1-native-binding.md §3.3): rejecting NaN/Infinity,
unsafe integers, and invalid Dates is a deliberate "never silently lose
precision" choice, not a divergence to fix.

🤖 Generated with Claude Code

Note

Bind null/undefined query params as SQL NULL (\N) matching @clickhouse/client

• formatParamValue in serialize.ts now returns '\N' for top-level null/undefined instead of throwing ChdbBindError, matching the behavior of the official @clickhouse/client.
• The engine treats \N as SQL NULL for Nullable placeholders and rejects it for non-Nullable ones, surfacing an engine-level error rather than a client-side error.
• Two null-binding tests are removed from the clickhouse-js skip list in skip_list.json as they now pass.
• Behavioral Change: code that previously caught ChdbBindError on null params will no longer receive that error; binding null to a non-Nullable column now yields a CHDB_* engine error instead.

^{Macroscope summarized caf4f69.}

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[ShawnChen-Sirius]

@dfrankland thanks for this PR. Pls fix the ci unexception, then we will merge it~

[dfrankland]

@ShawnChen-Sirius thanks for reviewing. Just pushed a fix