https://github.com/mikeamputer/clickhouse-migrate
ClickHouse migrations docker image (WIP)
https://github.com/mikeamputer/clickhouse-migrate
Last synced: 12 months ago
JSON representation
ClickHouse migrations docker image (WIP)
- Host: GitHub
- URL: https://github.com/mikeamputer/clickhouse-migrate
- Owner: MikeAmputer
- License: mit
- Created: 2025-07-08T14:43:01.000Z (12 months ago)
- Default Branch: master
- Last Pushed: 2025-07-21T14:31:26.000Z (12 months ago)
- Last Synced: 2025-07-21T15:28:21.044Z (12 months ago)
- Language: C#
- Homepage:
- Size: 27.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ch-migrate
[](https://hub.docker.com/r/mikeamputer/ch-migrate)
[](https://github.com/MikeAmputer/clickhouse-migrate/pkgs/container/ch-migrate)
[](https://github.com/MikeAmputer/clickhouse-migrate/blob/master/LICENSE)
Migrations tool for ClickHouse, distributed as a Docker image. Built on top of the [ClickHouse.Facades](https://github.com/MikeAmputer/ClickHouse.Facades) .NET package, using HTTP client under the hood.
> [!NOTE]
> This is an unofficial tool and is not affiliated with or endorsed by ClickHouse Inc.
>
> "ClickHouse" is a registered trademark of ClickHouse Inc. — [clickhouse.com](https://clickhouse.com/)
## Key Features
- Down migrations support
- Optional automatic rollback on migration fail
- HTTPS support
## Usage
Run the tool using Docker, specifying the desired command (`up` or `down`) and configuration options. The directory containing migration files should be mounted into the container as a volume.
### Commands
- `up`: Applies all pending migrations in the specified migrations directory.
- `down `: Reverts migrations to the specified migration index, rolling back all newer migrations.
### Configuration Options
The tool supports configuration via command-line options or environment variables. Command-line options take precedence over environment variables. Boolean command-line arguments can not be used as flags - values should be provided explicitly `--https-enabled=true`.
| Option | Environment Variable | Description | Default |
|-----------------------|--------------------------------|------------------------------------------------|-------------------|
| `--host` | `CH_MIGRATIONS_HOST` | ClickHouse host. | (Required) |
| `--port` | `CH_MIGRATIONS_PORT` | ClickHouse port. | 8123 |
| `--user` | `CH_MIGRATIONS_USER` | ClickHouse user. | (Required) |
| `--password` | `CH_MIGRATIONS_PASSWORD` | ClickHouse password. | (Optional) |
| `--database` | `CH_MIGRATIONS_DATABASE` | ClickHouse database. | (Required) |
| `--migrations-dir` | `CH_MIGRATIONS_DIRECTORY` | Directory containing migration SQL files. | (Required) |
| `--timeout-sec` | `CH_MIGRATIONS_TIMEOUT` | Command timeout in seconds. | 60 |
| `--https-enabled` | `CH_MIGRATIONS_HTTPS_ENABLED` | Use HTTPS connection (`true`/`false`). | `false` |
| `--rollback-on-fail` | `CH_MIGRATIONS_ROLLBACK_ON_FAIL` | Automatically rollback on migration failure. | `false` |
### Migration Files
Migration files must be placed in the directory specified by `--migrations-dir` (or `CH_MIGRATIONS_DIRECTORY`) and follow a naming convention such as:
```
0001_Initial.up.sql
0001_Initial.down.sql
```
Each filename must start with a migration index like `0001_`, followed by migration name (underscores `_` are allowed), suffixed with the migration direction `.up` or `.down`, and ending with the `.sql` file extension. **Down migrations are optional.**
### Quick Setup
bash:
```bash
docker run --rm \
-e CH_MIGRATIONS_HOST="example.clickhouse.host" \
-e CH_MIGRATIONS_PORT="8123" \
-e CH_MIGRATIONS_USER="example_user" \
-e CH_MIGRATIONS_PASSWORD="example_password" \
-e CH_MIGRATIONS_DATABASE="example_db" \
-e CH_MIGRATIONS_DIRECTORY="/scripts" \
-v "$(pwd)/Migrations:/scripts" \
mikeamputer/ch-migrate:latest up
```
PowerShell:
```powershell
docker run --rm `
-e CH_MIGRATIONS_HOST="example.clickhouse.host" `
-e CH_MIGRATIONS_PORT="8123" `
-e CH_MIGRATIONS_USER="example_user" `
-e CH_MIGRATIONS_PASSWORD="example_password" `
-e CH_MIGRATIONS_DATABASE="example_db" `
-e CH_MIGRATIONS_DIRECTORY="/scripts" `
-v "${PWD}\Migrations:/scripts" `
mikeamputer/ch-migrate:latest up
```
Docker Compose:
```yaml
ch-migrate:
image: mikeamputer/ch-migrate:latest
environment:
- CH_MIGRATIONS_HOST=example.clickhouse.host
- CH_MIGRATIONS_PORT=8123
- CH_MIGRATIONS_USER=example_user
- CH_MIGRATIONS_PASSWORD=example_password
- CH_MIGRATIONS_DATABASE=example_db
- CH_MIGRATIONS_DIRECTORY=/scripts
volumes:
- ./Migrations:/scripts
command: up
```
> [!NOTE]
> `docker-compose` does not support `--rm` (auto-remove) as part of the YAML service definition.
>
> For an example using `healthcheck`, see [this docker-compose example](https://github.com/MikeAmputer/clickhouse-migrate/blob/master/examples/Example/docker-compose.yml).