@clickhouse/client 1.18.4 → 1.18.5-head.09b78f0.1

package/skills/clickhouse-js-node-coding/reference/async-insert.md

@@ -0,0 +1,103 @@
+# Async Inserts
+
+> **Applies to:** all client versions; the relevant settings are server-side.
+> See https://clickhouse.com/docs/en/optimize/asynchronous-inserts.
+
+Backing example:
+[`examples/node/coding/async_insert.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/async_insert.ts).
+
+> **When to use async inserts:** when many small inserts arrive concurrently
+> (e.g., one per HTTP request) and you don't want to maintain a client-side
+> batching layer. ClickHouse will batch them server-side. This is also the
+> recommended ingestion pattern for **ClickHouse Cloud**.
+
+> **When _not_ to use async inserts:** when you already build large batches
+> client-side (e.g., from a stream). Plain inserts are simpler and lower
+> latency. For raw throughput tuning of large async-insert workloads, see
+> [`examples/node/performance/`](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node/performance).
+
+## Setup
+
+Enable on the client (or per-request) via `clickhouse_settings`:
+
+```ts
+import { createClient, ClickHouseError } from '@clickhouse/client'
+
+const client = createClient({
+  url: process.env.CLICKHOUSE_URL,
+  password: process.env.CLICKHOUSE_PASSWORD,
+  max_open_connections: 10,
+  clickhouse_settings: {
+    async_insert: 1,
+    wait_for_async_insert: 1, // wait for ack from server
+    async_insert_max_data_size: '1000000',
+    async_insert_busy_timeout_ms: 1000,
+  },
+})
+```
+
+## Concurrent small inserts
+
+Each call still uses the client's normal `insert()` API — the server merges
+the batches.
+
+```ts
+const promises = [...new Array(10)].map(async () => {
+  const values = [...new Array(1000).keys()].map(() => ({
+    id: Math.floor(Math.random() * 100_000) + 1,
+    data: Math.random().toString(36).slice(2),
+  }))
+
+  await client
+    .insert({ table: 'async_insert_example', values, format: 'JSONEachRow' })
+    .catch((err) => {
+      if (err instanceof ClickHouseError) {
+        // err.code matches a row in system.errors
+        console.error(`ClickHouse error ${err.code}:`, err)
+        return
+      }
+      console.error('Insert failed:', err)
+    })
+})
+
+await Promise.all(promises)
+```
+
+## `wait_for_async_insert` — fire-and-forget vs ack
+
+| `wait_for_async_insert` | Promise resolves when…                            | Trade-off                                                           |
+| ----------------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
+| `1` (default)           | Server has flushed the batch to the table         | Slower per call; insert errors surface to the client                |
+| `0`                     | Server accepted the row into its in-memory buffer | Faster; flush errors won't surface — only validation/parsing errors |
+
+With `wait_for_async_insert: 1`, expect each insert call to take roughly
+`async_insert_busy_timeout_ms` to resolve when traffic is light, because the
+server waits for more rows or for the timer to fire before flushing.
+
+## Combining DDL with async inserts
+
+When creating tables in scripts that immediately insert, ack the DDL with
+`wait_end_of_query: 1` so the table is ready before the first insert:
+
+```ts
+await client.command({
+  query: `
+    CREATE OR REPLACE TABLE async_insert_example (id Int32, data String)
+    ENGINE MergeTree ORDER BY id
+  `,
+  clickhouse_settings: { wait_end_of_query: 1 },
+})
+```
+
+## Common pitfalls
+
+- **Setting `async_insert` per call but expecting client-side batching.**
+  The client still issues each `insert()` as a separate HTTP request — the
+  batching happens on the server.
+- **Confusing `wait_for_async_insert` (async-insert ack) with
+  `wait_end_of_query` (DDL ack).** They are unrelated.
+- **Treating a resolved insert under `wait_for_async_insert: 0` as
+  durably written.** It only means the server accepted the bytes; flush
+  failures will not surface to the client.
+- **Not handling `ClickHouseError`.** It exposes `err.code`, which maps to
+  rows in the `system.errors` table — use it to decide whether to retry.

package/skills/clickhouse-js-node-coding/reference/client-configuration.md

@@ -0,0 +1,159 @@
+# Client Configuration
+
+> **Applies to:** all versions, with these notable additions:
+>
+> - `pathname` config option: client `>= 1.0.0`.
+> - `clickhouse_setting_*` / `ch_*` URL parameters: client `>= 1.0.0`.
+> - `keep_alive.idle_socket_ttl` (Node-only): client `>= 1.0.0`.
+
+Backing examples:
+[`examples/node/coding/url_configuration.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/url_configuration.ts),
+[`examples/node/coding/clickhouse_settings.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/clickhouse_settings.ts),
+[`examples/node/coding/default_format_setting.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/default_format_setting.ts).
+
+## Answer checklist
+
+When answering configuration questions, include the relevant points:
+
+- Show `createClient` from `@clickhouse/client` with explicit fields when the
+  user is writing code; this is easier to read and review than encoding
+  everything into a URL string.
+- When mentioning the URL form for environment variables / DSNs: show a **Bash**
+  `export` with the literal URL value, and `createClient({ url: process.env.CLICKHOUSE_URL })`
+  in the Node code. **Never construct a URL in application code** — no string
+  concatenation, no template literals, no query-string builders.
+- If URL parameters and object fields both set the same option, URL parameters
+  override the rest of the configuration object.
+- If `clickhouse_settings` appear on `createClient`, explain that they are
+  defaults for every request and can be overridden on individual `query()`,
+  `insert()`, `command()`, or `exec()` calls.
+- Remind long-running services to close the client during graceful shutdown.
+- The `application` field sets the name that appears in `system.query_log`.
+  Do **not** mention any specific HTTP header name — the client handles header
+  mapping internally and the header names are an implementation detail.
+
+## Minimal client
+
+```ts
+import { createClient } from '@clickhouse/client'
+
+const client = createClient({
+  url: process.env.CLICKHOUSE_URL, // defaults to 'http://localhost:8123'
+  username: process.env.CLICKHOUSE_USER, // defaults to 'default'
+  password: process.env.CLICKHOUSE_PASSWORD, // defaults to ''
+  database: 'analytics', // defaults to 'default'
+})
+// ... your queries ...
+await client.close()
+```
+
+`url` accepts a string or a `URL` object. The accepted string format is:
+
+```
+http[s]://[username:password@]hostname:port[/database][?param1=value1&param2=value2]
+```
+
+## Configuration via URL parameters
+
+A fixed allowlist of config fields can be set as URL query parameters
+(plus any key prefixed with `clickhouse_setting_` / `ch_` / `http_header_`).
+**Supported URL parameters override the corresponding values in the rest of
+the configuration object** — when they do, the client logs a warning.
+Unknown URL parameters cause `createClient` to throw
+`Unknown URL parameters: ...`
+(see [`packages/client-common/src/config.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/packages/client-common/src/config.ts) for the shared allowlist, and [`packages/client-node/src/config.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/packages/client-node/src/config.ts) for Node-specific URL parameters).
+
+Supported non-prefixed keys parsed by `client-common`: `application`,
+`session_id`, `pathname`, `access_token`, `request_timeout`,
+`max_open_connections`, `compression_request`, `compression_response`,
+`log_level`, `keep_alive_enabled`. Additionally, Node supports
+`keep_alive_idle_socket_ttl` via the Node-specific config implementation.
+Anything else must be passed via the config object on `createClient`.
+
+Prefer explicit object fields in application code. Use the URL form when the
+application receives one connection string from an environment variable, secret
+manager, or config file. The URL value belongs in the environment, not in the
+source code — show it as a shell export and read it in Node:
+
+```bash
+# In your shell environment / deployment config (e.g. .env, Kubernetes secret):
+export CLICKHOUSE_URL='https://bob:secret@my.host:8124/analytics?application=my_analytics_app&ch_async_insert=1&ch_wait_for_async_insert=0'
+```
+
+```ts
+// In your Node.js code — no URL construction needed:
+const client = createClient({ url: process.env.CLICKHOUSE_URL })
+```
+
+The same connection can also be expressed as an explicit config object (useful when you want to document each field individually):
+
+```ts
+import { createClient } from '@clickhouse/client'
+
+createClient({
+  url: 'https://my.host:8124',
+  username: 'bob',
+  password: 'secret',
+  database: 'analytics',
+  application: 'my_analytics_app',
+  clickhouse_settings: { async_insert: 1, wait_for_async_insert: 0 },
+})
+```
+
+## Per-client vs per-request `clickhouse_settings` ⭐
+
+> **Always mention this when discussing `clickhouse_settings`:** settings set
+> on `createClient` are defaults; any individual call can override them.
+
+Settings on `createClient` apply to every request. Settings on a single
+operation (`query`, `insert`, `command`, `exec`) override the client defaults
+for **that call only**.
+
+```ts
+const client = createClient({
+  clickhouse_settings: {
+    date_time_input_format: 'best_effort', // applied to every request
+  },
+})
+
+const rows = await client.query({
+  query: 'SELECT number FROM system.numbers LIMIT 2',
+  format: 'JSONEachRow',
+  clickhouse_settings: {
+    output_format_json_quote_64bit_integers: 1, // overrides client default for this call
+  },
+})
+```
+
+## `default_format` for `exec()`
+
+`client.exec()` runs an arbitrary statement and returns a stream. If your
+query has no trailing `FORMAT …` clause, set `default_format` so the server
+knows what to send back, then wrap the response in a `ResultSet`:
+
+```ts
+import { createClient, ResultSet } from '@clickhouse/client'
+
+const client = createClient()
+const format = 'JSONCompactEachRowWithNamesAndTypes'
+const { stream, query_id } = await client.exec({
+  query: 'SELECT database, name, engine FROM system.tables LIMIT 5',
+  clickhouse_settings: { default_format: format },
+})
+const rs = new ResultSet(stream, format, query_id)
+console.log(await rs.json())
+await client.close()
+```
+
+For ordinary `SELECT`s prefer `client.query({ format })` — `default_format` is
+only needed for raw `exec()`.
+
+## Common pitfalls
+
+- **Don't put a path in `url` and expect it to be the database name when
+  you're behind a proxy.** Use `pathname` for the proxy path and `database`
+  for the DB. (Symptom: "wrong database selected.") See the
+  troubleshooting skill for diagnosis.
+- **Don't create a client per request.** `createClient` opens a connection
+  pool; share one client across the process and `close()` on shutdown.
+- **`max_open_connections` must be `>= 1`** when set explicitly.

package/skills/clickhouse-js-node-coding/reference/custom-json.md

@@ -0,0 +1,149 @@
+# Custom JSON `parse` / `stringify`
+
+> **Requires:** client `>= 1.14.0` (configurable `json.parse` and
+> `json.stringify`). Earlier versions cannot swap the JSON implementation.
+
+Backing example:
+[`examples/node/coding/custom_json_handling.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/custom_json_handling.ts).
+
+## Answer checklist
+
+When the user wants `UInt64`/`Int64` values back as `BigInt`:
+
+- State that configurable `json.parse` / `json.stringify` requires
+  `@clickhouse/client >= 1.14.0`.
+- Show the supported `createClient({ json: { parse, stringify } })` option,
+  usually with `json-bigint` and `useNativeBigInt: true`.
+- Combine it with `output_format_json_quote_64bit_integers: 0` so the server
+  emits unquoted 64-bit integers that the parser can turn into `BigInt`.
+- Mention that `output_format_json_quote_64bit_integers: 0` is the default
+  since ClickHouse `25.8`, but setting it explicitly is useful for older
+  servers or portable examples.
+- Warn that casting to JavaScript `Number` / `parseInt` / `parseFloat` loses
+  precision above `Number.MAX_SAFE_INTEGER`.
+
+## Why customize?
+
+The default `JSON.stringify` / `JSON.parse`:
+
+- Throws on `BigInt`.
+- Calls `Date.prototype.toJSON()` (ISO string) — fine for `DateTime` with
+  `date_time_input_format: 'best_effort'`, surprising in some workflows.
+- Loses precision for 64-bit integers returned as numbers (a separate
+  issue — covered in the troubleshooting skill).
+
+A custom `{ parse, stringify }` lets you plug in `JSONBig`,
+`safe-stable-stringify`, your own `BigInt`-aware serializer, etc.
+
+## Recipe: BigInt-safe stringify, custom Date handling
+
+```ts
+import { createClient } from '@clickhouse/client'
+
+const valueSerializer = (value: unknown): unknown => {
+  // Serialize Date as a UNIX millis number (instead of toJSON's ISO string)
+  if (value instanceof Date) {
+    return value.getTime()
+  }
+
+  // Serialize BigInt as a string so JSON.stringify won't throw
+  if (typeof value === 'bigint') {
+    return value.toString()
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(valueSerializer)
+  }
+
+  if (typeof value === 'object' && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).map(([k, v]) => [k, valueSerializer(v)]),
+    )
+  }
+
+  return value
+}
+
+const client = createClient({
+  json: {
+    parse: JSON.parse,
+    stringify: (obj: unknown) => JSON.stringify(valueSerializer(obj)),
+  },
+})
+
+await client.command({
+  query: `
+    CREATE OR REPLACE TABLE inserts_custom_json_handling
+    (id UInt64, dt DateTime64(3, 'UTC'))
+    ENGINE MergeTree
+    ORDER BY id
+  `,
+})
+
+await client.insert({
+  table: 'inserts_custom_json_handling',
+  format: 'JSONEachRow',
+  values: [
+    {
+      id: BigInt(250000000000000200), // serialized as a string
+      dt: new Date(), // serialized as ms since epoch
+    },
+  ],
+})
+
+const rows = await client.query({
+  query: 'SELECT * FROM inserts_custom_json_handling',
+  format: 'JSONEachRow',
+})
+console.info(await rows.json())
+await client.close()
+```
+
+> The custom `valueSerializer` runs **before** `JSON.stringify`, so values
+> are transformed before the standard hooks (`Date.prototype.toJSON`,
+> object `toJSON()` methods, etc.) ever run.
+
+## Recipe: BigInt-safe parsing for 64-bit integer columns
+
+If you want `UInt64`/`Int64` to come back as `BigInt`s (instead of strings
+or precision-lossy numbers), plug in a `BigInt`-aware parser such as
+[`json-bigint`](https://www.npmjs.com/package/json-bigint):
+
+```ts
+import { createClient } from '@clickhouse/client'
+import JSONBig from 'json-bigint'
+
+const bigJson = JSONBig({ useNativeBigInt: true })
+
+const client = createClient({
+  json: {
+    parse: bigJson.parse,
+    stringify: bigJson.stringify,
+  },
+  clickhouse_settings: {
+    output_format_json_quote_64bit_integers: 0,
+  },
+})
+```
+
+This applies to **both** outgoing JSON bodies and incoming JSON-format
+responses. Combine with `output_format_json_quote_64bit_integers: 0` (the
+default since CH 25.8) so the server emits unquoted 64-bit integers that
+`json-bigint` can parse to `BigInt`.
+
+## Common pitfalls
+
+- **Setting `json.parse` only.** That only affects reading JSON responses;
+  outgoing JSON bodies use `json.stringify`. If you want consistent custom
+  handling in both directions, generally provide a matching `stringify` too.
+- **Forgetting `bigint` handling in `stringify`.** Default `JSON.stringify`
+  throws on `BigInt`; if your data ever contains one, the insert will fail
+  with `TypeError: Do not know how to serialize a BigInt`.
+- **Targeting client `< 1.14.0`.** The `json` option doesn't exist; you'll
+  need to convert values manually before calling `insert()` / `query()` (or
+  upgrade).
+- **Casting 64-bit integers to `Number`.** JavaScript's `number` type has
+  only 53 bits of mantissa — values above `Number.MAX_SAFE_INTEGER` (2^53 − 1)
+  are silently rounded. Do **not** try to fix precision loss by calling
+  `Number()`, `parseInt()`, or `parseFloat()` on the value. The correct fix
+  is a `BigInt`-aware parser (shown above), not a lossy cast.

package/skills/clickhouse-js-node-coding/reference/data-types.md

@@ -0,0 +1,169 @@
+# Modern Data Types: Dynamic, Variant, JSON, Time, Time64
+
+> **Applies to** (server side):
+>
+> - `Variant`: ClickHouse `>= 24.1`.
+> - `Dynamic`: ClickHouse `>= 24.5`.
+> - New `JSON` (object) type: ClickHouse `>= 24.8`.
+> - All three are **no longer experimental since `25.3`**; on older servers,
+>   you must enable the corresponding `allow_experimental_*_type` setting.
+> - `Time` / `Time64`: ClickHouse `>= 25.6` and require
+>   `enable_time_time64_type: 1`.
+
+Backing examples:
+[`examples/node/coding/dynamic_variant_json.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/dynamic_variant_json.ts),
+[`examples/node/coding/time_time64.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/time_time64.ts).
+
+## Answer checklist
+
+When answering about storing and reading JSON objects:
+
+- Use the new `JSON` column type, introduced in ClickHouse `>= 24.8`.
+- Say `JSON` is no longer experimental since ClickHouse `25.3`; on older
+  supported versions, enable `allow_experimental_json_type`.
+- Insert real JS objects with `format: 'JSONEachRow'`; do not
+  `JSON.stringify()` the column value.
+- Read with a JSON output format such as `JSONEachRow` and `resultSet.json()`;
+  `JSON` column values come back as parsed JS objects.
+
+## `Dynamic`, `Variant(...)`, `JSON`
+
+```ts
+import { createClient } from '@clickhouse/client'
+
+const client = createClient({
+  // Required only on ClickHouse < 25.3 — harmless to leave on
+  clickhouse_settings: {
+    allow_experimental_variant_type: 1,
+    allow_experimental_dynamic_type: 1,
+    allow_experimental_json_type: 1,
+  },
+})
+
+await client.command({
+  query: `
+    CREATE OR REPLACE TABLE chjs_dynamic_variant_json
+    (
+      id      UInt64,
+      var     Variant(Int64, String),
+      dynamic Dynamic,
+      json    JSON
+    )
+    ENGINE MergeTree
+    ORDER BY id
+  `,
+})
+
+await client.insert({
+  table: 'chjs_dynamic_variant_json',
+  format: 'JSONEachRow',
+  values: [
+    { id: 1, var: 42, dynamic: 'foo', json: { foo: 'x' } },
+    { id: 2, var: 'str', dynamic: 144, json: { bar: 10 } },
+  ],
+})
+
+const rs = await client.query({
+  query: `
+    SELECT *,
+           variantType(var),
+           dynamicType(dynamic),
+           dynamicType(json.foo),
+           dynamicType(json.bar)
+    FROM chjs_dynamic_variant_json
+  `,
+  format: 'JSONEachRow',
+})
+console.log(await rs.json())
+```
+
+### Notes
+
+- The `JSON` column type accepts a real JS object on insert and returns one
+  on select — no need for `JSON.stringify` / `JSON.parse` in your app code.
+- A JS number written into a `Dynamic` or `Variant` column defaults to
+  `Int64` on the server. In JSON formats, `output_format_json_quote_64bit_integers`
+  controls how 64-bit integers are returned: `1` returns them as JSON strings,
+  while `0` returns them as JSON numbers (and `0` is the default since CH `25.8`).
+  In JS, large 64-bit integers returned as numbers can lose precision, so use
+  quoted output if you need exact integer values in application code.
+- Use `variantType(...)`, `dynamicType(...)` to introspect what the server
+  ended up storing.
+
+## `Time` and `Time64(p)`
+
+`Time` is signed seconds (`-999:59:59` … `999:59:59`). `Time64(p)` adds
+sub-second precision (`p` digits, up to `9` for nanoseconds). Both require
+`enable_time_time64_type: 1` on `>= 25.6`.
+
+```ts
+const client = createClient({
+  clickhouse_settings: { enable_time_time64_type: 1 },
+})
+
+await client.command({
+  query: `
+    CREATE OR REPLACE TABLE chjs_time_time64
+    (
+      id    UInt64,
+      t     Time,
+      t64_0 Time64(0),
+      t64_3 Time64(3),
+      t64_6 Time64(6),
+      t64_9 Time64(9),
+    )
+    ENGINE MergeTree
+    ORDER BY id
+  `,
+})
+
+await client.insert({
+  table: 'chjs_time_time64',
+  format: 'JSONEachRow',
+  values: [
+    {
+      id: 1,
+      t: '12:34:56',
+      t64_0: '12:34:56',
+      t64_3: '12:34:56.123',
+      t64_6: '12:34:56.123456',
+      t64_9: '12:34:56.123456789',
+    },
+    {
+      id: 2,
+      t: '999:59:59',
+      t64_0: '999:59:59',
+      t64_3: '999:59:59.999',
+      t64_6: '999:59:59.999999',
+      t64_9: '999:59:59.999999999',
+    },
+    {
+      id: 3,
+      t: '-999:59:59',
+      t64_0: '-999:59:59',
+      t64_3: '-999:59:59.999',
+      t64_6: '-999:59:59.999999',
+      t64_9: '-999:59:59.999999999',
+    },
+  ],
+})
+```
+
+### Notes
+
+- Pass values as **strings** in the `HH:MM:SS[.fraction]` format. Negatives
+  are supported; the magnitude can exceed 24 hours.
+- For `Time64(p)` with `p > 3`, do not use JS `Date` — it tops out at
+  millisecond precision and will silently truncate.
+
+## Common pitfalls
+
+- **Targeting old ClickHouse servers without the `allow_experimental_*`
+  setting.** On `< 25.3`, `CREATE TABLE` will fail without them.
+- **Expecting `JSON`-column reads to be raw strings.** They come back as
+  parsed objects in JSON formats.
+- **Inserting `Time64(9)` from JS `Date` and losing precision.** Use a
+  string instead.
+- **Reading a `Variant`/`Dynamic` value of type `Int64` and being surprised
+  it's a string.** That's the standard 64-bit-integers-in-JSON behavior;
+  see the troubleshooting skill if you need to change it.

package/skills/clickhouse-js-node-coding/reference/insert-columns.md

@@ -0,0 +1,113 @@
+# Insert into Specific Columns / Other Databases
+
+> **Applies to:** all versions. The `columns` option (both forms) and the
+> `database` config field are universally supported.
+
+Backing examples:
+[`examples/node/coding/insert_specific_columns.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_specific_columns.ts),
+[`examples/node/coding/insert_exclude_columns.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_exclude_columns.ts),
+[`examples/node/coding/insert_ephemeral_columns.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_ephemeral_columns.ts),
+[`examples/node/coding/insert_into_different_db.ts`](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_into_different_db.ts).
+
+## Answer checklist
+
+When explaining partial-column inserts:
+
+- Show `columns: ['col_a', 'col_b']` for the allowlist form.
+- Also mention the inverse `columns: { except: ['col_to_skip'] }` form so the
+  user knows both supported shapes.
+- Explain that omitted columns receive their server-side defaults
+  (`DEFAULT`, `MATERIALIZED`, `ALIAS`, nullable/type defaults) and inserts can
+  still fail or produce surprising zero/empty values if the table definition
+  has no appropriate defaults.
+
+## Insert into specific columns
+
+Pass `columns: string[]` to limit the `INSERT` to a subset. Omitted columns
+get their declared default.
+
+```ts
+await client.insert({
+  table: 'events',
+  format: 'JSONEachRow',
+  values: [{ message: 'foo' }],
+  columns: ['message'], // `id` will get its default (0 for UInt32)
+})
+```
+
+## Insert excluding columns
+
+Use `columns: { except: string[] }` for the inverse. Useful when most columns
+should default but you want to name only the few to skip.
+
+```ts
+await client.insert({
+  table: 'events',
+  format: 'JSONEachRow',
+  values: [{ message: 'bar' }],
+  columns: { except: ['id'] },
+})
+```
+
+## Tables with EPHEMERAL columns
+
+[Ephemeral columns](https://clickhouse.com/docs/en/sql-reference/statements/create/table#ephemeral)
+are not stored — they only exist to drive `DEFAULT` expressions of other
+columns. To trigger that default logic, **the ephemeral column must be in the
+`columns` list**, even though no value will be persisted for it.
+
+```ts
+await client.command({
+  query: `
+    CREATE OR REPLACE TABLE events
+    (
+      id              UInt64,
+      message         String DEFAULT message_default,
+      message_default String EPHEMERAL
+    )
+    ENGINE MergeTree
+    ORDER BY id
+  `,
+})
+
+await client.insert({
+  table: 'events',
+  format: 'JSONEachRow',
+  values: [
+    { id: '42', message_default: 'foo' },
+    { id: '144', message_default: 'bar' },
+  ],
+  // Including the ephemeral column name triggers the DEFAULT expression
+  columns: ['id', 'message_default'],
+})
+```
+
+## Insert into a different database
+
+If the client's default `database` is not the target, qualify the table name
+with `db.table`:
+
+```ts
+const client = createClient({ database: 'system' })
+
+await client.command({ query: 'CREATE DATABASE IF NOT EXISTS analytics' })
+
+await client.insert({
+  table: 'analytics.events', // fully qualified
+  format: 'JSONEachRow',
+  values: [{ id: 42, message: 'foo' }],
+})
+```
+
+There is no per-call `database` override on `insert()` / `query()` — qualify
+the identifier, or create a second client with the desired `database`.
+
+## Common pitfalls
+
+- **Forgetting the ephemeral column in `columns`.** If you list only the
+  non-ephemeral columns, the `DEFAULT` expression that depends on the
+  ephemeral value won't fire and you'll get empty/zero defaults instead.
+- **Hoping `client.insert({ database: '…' })` works.** It doesn't — qualify
+  the `table` instead.
+- **Mixing the two `columns` forms.** Use either `string[]` _or_
+  `{ except: string[] }`, not both.