release: chdb 3.2.0 — Layer 3 fluent SDK + agent-tool contract + 3 new integrations

[ShawnChen-Sirius]

What this is

The chdb 3.2.0 release commit — additive minor on top of 3.1.0 (2026-06-24). No breaking changes; existing 3.1.0 APIs continue to work unchanged. libchdb bits are unchanged (chdb-core v26.5.1-rc.1 packaged as @chdb/lib-* 26.5.2 — no republish needed, the subpackage-matrix job will idempotent-skip).

Single-file diff (package.json version 3.1.0 → 3.2.0). The release history / feature list is in this PR body and in the commit message body.

What's new since 3.1.0 (14 PRs, ~13K lines)

Layer 3 fluent query builder SDK (#55, #59)

First-class typed fluent query API — Kysely-/Drizzle-style:

const db = connect({ session })
const rows = await db
  .from('users')
  .where(r => r.age.gt(18))
  .select('id', 'name')
  .execute()

• src/layer3/{builder,execute,compile,dialect,introspection,connect,types,codegen}/
• chdb-gen-types CLI — generates row types from a schema (Drizzle / Prisma / raw SQL sources)
• .stream() terminal with server-side parameter binding
• Arrow C Data Interface support: register JS columnar data as arrowstream() tables
• 12 new test files under test/v3/layer3/

Cross-language agent-tool contract + 2 framework adapters (#61, #66)

• chdb/ai-sdk — Vercel AI SDK tools (generateText / streamText)
• chdb/mastra — Mastra tools + ChDBVector (HNSW RAG store) + ChDBStore
• Both are thin wrappers over ChDBTool.call() from integrations/agents/, which implements the cross-language contract vendored from chdb-io/chdb (chdb/agents/CONTRACT.md, agents: mark beta + accept (database, table) qualification (4.2.0 prep) chdb#597).
• 7 canonical tools: run_select_query / list_databases / list_tables / describe_table / get_sample_data / list_functions / attach_file
• 5 pillars enforced: engine-level readonly=2 (P1), value-vs-identifier separation (P2), truncation flag (P3), error envelope for model self-correction (P4), resource/source controls (P5)
• Behavior verified against the shared conformance/cases.jsonl fixture — same fixture the Python reference (chdb.agents.ChDBTool) passes.

chdb/hypequery DatabaseAdapter (#63, #65)

Lets @hypequery/clickhouse query builder run on embedded chDB instead of a remote ClickHouse server. Uses hypequery's own substituteParameters (imported, not copied) so rendered SQL stays byte-identical to hypequery's built-in HTTP adapter.

chdb/connection stabilization for @clickhouse/client 1.23.0

• peerDependency: "@clickhouse/client: >=1.23.0" (optional) — old client triggers a clear npm warning instead of a runtime TS error
• Parity runner switched to track ClickHouse/clickhouse-js release tag client-1.23.0 (per the sync-policy table; feat(l2): pluggable Connection — chdb/connection for @clickhouse/client #52 shipped the initial hook)
• Runner auto-detects upstream Vitest layout (pre-/post-clickhouse-js#931)
• Runner re-synced when clickhouse-js reorganized into a monorepo (Re-sync parity runner to clickhouse-js monorepo Vitest layout #62)

AI-discovery docs (#60)

• Top-level AGENTS.md + llms-full.txt
• Per-subpath AGENTS.md (src/layer3/, src/connection/, etc.)
• All packaged in files so agents crawling the installed tarball find them

Fixes / infrastructure

• Bind null / undefined query params as SQL \N (contributor @dfrankland, Bind null query params as SQL NULL (\N), matching @clickhouse/client #68) — matches @clickhouse/client behavior
• close()-mid-flight engine abort + ResultSet teardown race (fix(ci): stop close()-mid-flight engine abort (#53) and absorb ResultSet teardown (#54) #56)
• ChDBVector HNSW granularity / filter binding / dimension guard (Add Vercel AI SDK and Mastra tool adapters (chdb/ai-sdk, chdb/mastra) #61)
• Release workflow: publish → unverified dist-tag → clean-install verify matrix → promote to latest (Verify the published package on clean installs before promoting to latest #64). A broken release now never reaches latest users.
• CI: cache deps + harden npm registry fetch against transient resets

User-facing installation matrix

npm install chdb                                    # base + Layer 3 SDK
npm install chdb @clickhouse/client                 # + chdb/connection
npm install chdb @hypequery/clickhouse              # + chdb/hypequery
npm install chdb ai zod                             # + chdb/ai-sdk
npm install chdb @mastra/core zod                   # + chdb/mastra

Release path after merge

Once this PR merges to main, tagging v3.2.0 on the merge commit triggers prebuild-publish.yml:

1. subpackages matrix — 4 platforms build + publish @chdb/lib-* 26.5.2 (idempotent skip, already on npm from 3.1.0)
2. main package publish → unverified dist-tag (NOT latest)
3. verify matrix — every platform × Node 18/20/22 does a clean npm install chdb@3.2.0 and runs test/pack/installed.test.mjs
4. only if all verify legs pass → promote latest to 3.2.0

Native libchdb bits unchanged from 3.1.0: chdb-core v26.5.1-rc.1 packaged as @chdb/lib-* 26.5.2.

Generated with Claude Code
via Happy

Note

Release chdb version 3.2.0

Bumps the package version from 3.1.0 to 3.2.0 in package.json.

^{Macroscope summarized 4aaa868.}