createClickHouseDB

createClickHouseDB(...) is the entry point of the library. It supports two things:

• a plain TypeScript DB shape
• an optional @clickhouse/client instance

You can keep that DB shape entirely plain, or add type-only wrappers such as TypedView<Row> and ColumnType<Select, Insert, Where> when you want more precision. See DB typing helpers.

Plain mode

import { createClient } from "@clickhouse/client";
import { createClickHouseDB } from "@oorestisime/quarry";

interface DB {
  users: {
    id: number;
    email: string;
  };
}

const db = createClickHouseDB<DB>({
  client: createClient({ url: "http://localhost:8123" }),
});

Retries

Pass retries to retry failed select query execution from this DB handle:

const db = createClickHouseDB<DB>({
  client: createClient({ url: "https://example.clickhouse.cloud:8443" }),
  retries: {
    attempts: 3,
    delayMs: 100,
  },
});

attempts is the total number of attempts, including the first immediate call, and must be a positive integer. delayMs is the fixed delay between failed attempts, and must be a non-negative finite number.

Retries only apply to likely transient select execution failures such as socket errors, request timeouts, and temporary HTTP responses like 503. Quarry does not retry inserts or commands because retrying writes can duplicate data unless the write path is idempotent.

Introspection output uses named row interfaces plus TypedTable<...> / TypedView<...> wrappers, but handwritten schemas can stay as plain objects if you prefer.

Options

The options object is rendered live from the source:

What you get back

db is an instance of ClickHouseDB<...>. The methods you actually use are:

• db.selectFrom(...) — start a SELECT query
• db.insertInto(...) — start an INSERT query
• db.with(name, callback) — add a CTE that the rest of the chain can reference
• db.with(name, queryBuilder) — add a CTE from a pre-built SelectQueryBuilder
• db.table(name) — build an explicit table source (for FINAL, custom aliases, etc.)

See the guides for end-to-end examples of each.