https://github.com/shini4i/clickhouse-migrations
ClickHouse Migrations CLI
https://github.com/shini4i/clickhouse-migrations
automation clickhouse clickhouse-migrations db-migration
Last synced: 8 months ago
JSON representation
ClickHouse Migrations CLI
- Host: GitHub
- URL: https://github.com/shini4i/clickhouse-migrations
- Owner: shini4i
- License: mit
- Created: 2024-06-26T19:34:43.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-28T19:25:00.000Z (almost 2 years ago)
- Last Synced: 2025-04-23T05:51:26.633Z (about 1 year ago)
- Topics: automation, clickhouse, clickhouse-migrations, db-migration
- Language: TypeScript
- Homepage:
- Size: 198 KB
- Stars: 12
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# clickhouse-migrations
## Install
```sh
npm install -g @shini4i/clickhouse-migrations
```
## Usage
Create a directory, where migrations will be stored. It will be used as the value for the `--migrations-home` option (or for environment variable `CH_MIGRATIONS_HOME`).
In the directory, create migration files, which should be named like this: `01_some_text.sql`, `02_other_text.sql`, `10_more_test.sql`. What's important here is that the migration version number should come first, followed by an underscore (`_`), and then any text can follow. The version number should increase for every next migration. Please note that once a migration file has been applied to the database, it cannot be modified or removed.
For migrations' content should be used correct SQL ClickHouse queries. Multiple queries can be used in a single migration file, and each query should be terminated with a semicolon (;). The queries could be idempotent - for example: `CREATE TABLE IF NOT EXISTS table ...;` Clickhouse settings, that can be included at the query level, can be added like `SET allow_experimental_object_type = 1;`. For adding comments should be used `--`, `# `, `#!`.
If the database provided in the `--db` option (or in `CH_MIGRATIONS_DB`) doesn't exist, it will be created automatically.
```
Usage
$ clickhouse-migrations migrate
Required flags
--url= Clickhouse URL (ex. https://clickhouse:8123)
--user= Username
--db= Database name
--migrations-home= Migrations' directory
Optional flags
--password= Password
--engine= The engine to use for DB creation
--request-timeout= Request timeout in milliseconds
Environment variables
Instead of options can be used environment variables.
CH_MIGRATIONS_URL Clickhouse hostname (--url)
CH_MIGRATIONS_USER Username (--user)
CH_MIGRATIONS_PASSWORD Password (--password)
CH_MIGRATIONS_DB Database name (--db)
CH_MIGRATIONS_HOME Migrations' directory (--migrations-home)
CH_MIGRATIONS_ENGINE The engine to use for DB creation (optional)
CH_MIGRATIONS_REQUEST_TIMEOUT Clickhouse client request timeout (optional)
CLI examples
clickhouse-migrations migrate --url=http://localhost:8123
--user=default --db=analytics
--migrations-home=/app/clickhouse/migrations
clickhouse-migrations migrate
```
Migration file example:
```
-- an example of migration file 01_init.sql
SET allow_experimental_object_type = 1;
CREATE TABLE IF NOT EXISTS events (
event JSON
);
```
## Acknowledgements
This project is a fork of [clickhouse-migrations](https://github.com/VVVi/clickhouse-migrations), originally developed by [VVVi](https://github.com/VVVi).
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.