Registry / database / clickhouse-migration-tool

clickhouse-migration-tool

library1.1.1jsnpmunverified

Node.js migration tool for ClickHouse databases, version 1.1.1. Supports creating, running, and managing database migrations with a simple CLI. ESM-only, requires @clickhouse/client as peer dependency. Differentiates with lightweight setup and config-driven approach compared to larger frameworks. Released irregularly; current release stable.

database devops

npm install clickhouse-migration-tool

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CLICKHOUSE-MIGRATI

clickhouse-migration-tool

databasejavascriptv1.1.1

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.

clickhouse-migrate CLI

✓ npx clickhouse-migrate migrate

✗ npm run migrate (without setting up script)

CLI command, not exported as library. Use via npx or global install.

config export

✓ export default { connection: {...}, options: {...} }

✗ module.exports = { ... } (CommonJS not supported)

Config file must be ESM; CommonJS modules not supported.

Programmatic usage

✓ import { runMigrations } from 'clickhouse-migration-tool'

✗ const { runMigrations } = require('clickhouse-migration-tool')

Package exports runMigrations function for programmatic use. ESM only.

Initialize tool, create a migration file, and run pending migrations using CLI commands.

npm install -g clickhouse-migration-tool clickhouse-migrate init # Edit clickhouse-migrate-config.js with your connection details clickhouse-migrate create my_first_migration # SQL in ./migrations/20250301000000-my_first_migration.sql clickhouse-migrate migrate

Debug

Known issues

breakingCommonJS modules not supported; require() will fail.

fix

Use ESM syntax (import/export) in config and programmatic usage.

affects: >=1.0.0

gotchaDo not change the generated migration file name; the tool relies on timestamp ordering.

fix

Keep auto-generated filenames unchanged.

affects: >=1.0.0

deprecatedPeer dependency @clickhouse/client is required but not auto-installed.

fix

Install @clickhouse/client separately via npm install @clickhouse/client.

affects: >=1.0.0

gotchaConfiguration file must be in project root or specified with -c flag.

fix

Place clickhouse-migrate-config.js in root or use -c path/to/config.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module '@clickhouse/client'

Missing peer dependency @clickhouse/client.

fix

npm install @clickhouse/client

SyntaxError: Unexpected token 'export'

Config file using CommonJS module.exports instead of ESM export default.

fix

Change to export default { ... } and ensure package.json has "type": "module" or use .mjs extension.

Error: Migrations directory does not exist

Specified migration path in config doesn't exist.

fix

Create the directory or update config path.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

@clickhouse/clientrequiredPeer dependency: required to connect to ClickHouse server

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/luminoxic/node-clickhouse-migration-tool ↗

packageclickhouse-migration-tool ↗

homepagehttps://github.com/luminoxic/node-clickhouse-migration-tool#readme ↗