clickhouse-orm

library3.0.2jsnpmunverified

A Node.js ORM for ClickHouse that uses the HTTP interface and wraps the TimonKK/clickhouse driver. Version 3.0.2 offers schema-based model definitions, automatic table creation/synchronization, and typed queries with TypeScript support. It differentiates from raw SQL clients by providing a declarative model configuration, built-in data type mapping, and simplified CRUD operations. Release cadence is irregular; the library is maintained but with limited community activity.

database

npm install clickhouse-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CLICKHOUSE-ORM

clickhouse-orm

databasejavascriptv3.0.2

harness data pending

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.

ClickhouseOrm

✓ import { ClickhouseOrm } from 'clickhouse-orm';

✗ const ClickhouseOrm = require('clickhouse-orm');

Default export is a named export. CommonJS require must destructure.

DATA_TYPE

✓ import { DATA_TYPE } from 'clickhouse-orm';

✗ const DATA_TYPE = require('clickhouse-orm').DATA_TYPE;

Enum object for column data types.

ModelSyncTableConfig

✓ import type { ModelSyncTableConfig } from 'clickhouse-orm';

✗ import { ModelSyncTableConfig } from 'clickhouse-orm';

Type import for schema configuration, not a runtime value.

Initialize ClickHouse ORM, define a model with schema, auto-create table, and insert a row.

import { ClickhouseOrm, DATA_TYPE, ModelSyncTableConfig } from 'clickhouse-orm'; const chOrm = ClickhouseOrm({ db: { name: 'test_db' }, debug: true, client: { url: 'localhost', port: '8123', basicAuth: { username: 'default', password: '' }, isUseGzip: true, format: 'json', }, }); const tableSchema: ModelSyncTableConfig<{ event: string; timestamp: Date }> = { tableName: 'events', schema: { event: { type: DATA_TYPE.String }, timestamp: { type: DATA_TYPE.DateTime, default: Date }, }, options: 'ENGINE = MergeTree PARTITION BY toYYYYMM(timestamp) ORDER BY timestamp', autoCreate: true, autoSync: true, }; (async () => { await chOrm.createDatabase(); const EventsModel = await chOrm.model(tableSchema); const res = await EventsModel.create({ event: 'click', timestamp: new Date() }); console.log('Created:', res); })();

Debug

Known issues

breakingv3 changed from CommonJS to ESM-only exports. require() will not work without destructuring.

fix

Use dynamic import or destructured require: const { ClickhouseOrm } = require('clickhouse-orm');

affects: >=3.0.0

deprecatedThe 'autoSync' option is deprecated in v3.0.0. Use 'autoCreate' instead.

fix

Remove autoSync from schema config.

affects: >=3.0.0

gotchaTable names are case-insensitive in ClickHouse by default; schema definitions may not enforce case.

fix

Explicitly quote table names in options if needed.

affects: >=1.0.0

gotchaThe 'create' method does not validate required fields if no default is provided; missing columns can cause silent insert of empty values.

fix

Always provide defaults or validate before calling create.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'clickhouse-orm'

Package not installed or imported incorrectly.

fix

Run 'npm install clickhouse-orm' and use destructured import: const { ClickhouseOrm } = require('clickhouse-orm');

TypeError: chOrm.createDatabase is not a function

ClickhouseOrm() returned undefined due to missing or invalid arguments.

fix

Ensure db.name is provided and client config is valid.

Error: Connection refused: connect ECONNREFUSED 127.0.0.1:8123

ClickHouse server not running or incorrect host/port.

fix

Verify ClickHouse is running on localhost:8123 and start if needed: 'sudo systemctl start clickhouse-server'.

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

clickhouserequiredNative ClickHouse driver for HTTP interface used internally for query execution

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/zimv/node-clickhouse-orm ↗

packageclickhouse-orm ↗

homepagehttps://github.com/zimv/node-clickhouse-orm#readme ↗