@viplance/clickhouse-migrations

Standalone ClickHouse migration tool.

Installation

npm install -g @viplance/clickhouse-migrations

Usage

clickhouse-migrations migrate <options>
clickhouse-migrations status <options>
clickhouse-migrations rollback <options>

Using npx

npx @viplance/clickhouse-migrations@latest migrate <options>
npx @viplance/clickhouse-migrations@latest status <options>
npx @viplance/clickhouse-migrations@latest rollback <options>

Required options

• --host=<name>: Clickhouse hostname (ex. https://clickhouse:8123)
• --user=<name>: Username
• --password=<password>: Password
• --db=<name>: Database name
• --migrations-home=<dir>: Migrations' directory

Optional options

• --db-engine=<value>: ON CLUSTER and/or ENGINE for DB (default: 'ENGINE=Atomic')
• --timeout=<value>: Client request timeout (milliseconds, default: 30000)
• --ca-cert=<path>: CA certificate file path
• --cert=<path>: Client certificate file path
• --key=<path>: Client key file path
• --migrations-table=<name>: Migrations table name (default: '_migrations')
• --cluster=<name>: Clickhouse cluster name
• --state-separator=<value>: State separator (default: '+migration')

Environment variables

Instead of options, environment variables can be used.

| Option | Env Variable | Default | | -------------------- | ---------------------------------------------------- | ----------------------- | | --host | CH_MIGRATIONS_HOST or CLICKHOUSE_URL | http://localhost:8123 | | --user | CH_MIGRATIONS_USER or CLICKHOUSE_USER | default | | --password | CH_MIGRATIONS_PASSWORD or CLICKHOUSE_PASSWORD | | | --db | CH_MIGRATIONS_DB or CLICKHOUSE_DATABASE | default | | --migrations-home | CH_MIGRATIONS_HOME or CLICKHOUSE_MIGRATIONS_PATH | ./migrations | | --db-engine | CH_MIGRATIONS_DB_ENGINE | ENGINE=Atomic | | --timeout | CH_MIGRATIONS_TIMEOUT | 30000 | | --ca-cert | CH_MIGRATIONS_CA_CERT | | | --cert | CH_MIGRATIONS_CERT | | | --key | CH_MIGRATIONS_KEY | | | --migrations-table | CLICKHOUSE_MIGRATIONS_TABLE | _migrations | | --cluster | CLICKHOUSE_CLUSTER | | | --state-separator | CLICKHOUSE_STATE_SEPARATOR | +migration |

Migration File Format

Migration files should be named like 001_initial.sql. They use SQL comments to separate "Up" and "Down" migrations and statements.

Example:

-- +migration Up
-- +migration StatementBegin
CREATE TABLE users (...) ENGINE = MergeTree() ORDER BY id;
-- +migration StatementEnd

-- +migration Down
-- +migration StatementBegin
DROP TABLE users;
-- +migration StatementEnd