Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ckTable
✓ import { ckTable } from 'ck-orm'
✗ const { ckTable } = require('ck-orm')
ESM-only. CommonJS require() will fail.
ckType
✓ import { ckType } from 'ck-orm'
Used to define ClickHouse column types with optional column name overrides.
CkClient
✓ import { CkClient } from 'ck-orm'
✗ import CkClient from 'ck-orm'
Named export, not default. CkClient is the main client class.
Shows schema definition, client setup, and a typed query with where clause and limit.
import { ckTable, ckType, CkClient, eq } from 'ck-orm';
const probeTelemetry = ckTable('probe_telemetry', {
id: ckType.int32(),
probeId: ckType.string('probe_id'),
status: ckType.int16(),
createdAt: ckType.int32('created_at'),
}, (table) => ({
engine: 'ReplacingMergeTree',
orderBy: [table.probeId, table.createdAt],
}));
const client = new CkClient({
url: process.env.CLICKHOUSE_URL ?? 'http://localhost:8123',
});
async function main() {
const rows = await client
.select(probeTelemetry)
.where(eq(probeTelemetry.probeId, 'probe-1'))
.limit(10);
console.log(rows);
}
main().catch(console.error);
Debug
Known issues
breakingPre-0.1.0 API instability: significant API adjustments expected. Pin exact version.fixPin to exact version in package.json (e.g., "ck-orm": "0.0.23") and test upgrades carefully.
affects: <0.1.0
deprecatedCkClient constructor no longer accepts connection pool options as second argument; use url and options as single config object.fixPass configuration as a single object: new CkClient({ url, poolSize: 5, ... }) affects: >=0.0.10 <0.0.20
gotchaJoin queries produce null for right-side columns when rows don't match (ClickHouse standard). This library does not abstract that away.fixUse COALESCE or nullable type handling in your application code.
affects: >=0.0.1
breakingRenamed 'ckMv' to 'ckMaterializedView' in v0.0.15. Old export removed.fixReplace 'ckMv' with 'ckMaterializedView' in imports.
affects: >=0.0.15
gotchaOpenTelemetry dependency is optional but if installed, version must be ^1.9.1 exactly; mismatched peer dep may cause silent failures.fixVerify @opentelemetry/api is at ^1.9.1 in package.json.
affects: >=0.0.20
Errors
Common errors & fixes
Error: The requested module 'ck-orm' does not provide an export named 'ckTable'
Using CommonJS require() instead of ESM import, or importing from a version that uses a different export name.
fixUse import { ckTable } from 'ck-orm' and ensure your project is ESM (type: module in package.json or .mjs extension). TypeError: (0 , ck_orm_1.ckType) is not a function
Attempting to call ckType as a default import (e.g., import ckType from 'ck-orm').
fixUse named import: import { ckType } from 'ck-orm'. Error: Connect to clickhouse at localhost:8123 failed: connect ECONNREFUSED
ClickHouse server not running or wrong URL/host.
fixVerify ClickHouse is running: clickhouse-client --host localhost --port 8123. Check CLICKHOUSE_URL env var.
Audit
Dependencies
@opentelemetry/apioptionalOptional peer dependency for observability (tracing, metrics). If not installed, observability features are no-ops.