# ClickHouse Migrations - golang-migrate

This directory contains ClickHouse migrations in the [golang-migrate](https://github.com/golang-migrate/migrate) format.

## Why golang-migrate?

We provide golang-migrate as an alternative migration engine to [Atlas](https://atlasgo.io/) because Atlas requires an Atlas Pro account and login to apply migrations. golang-migrate runs completely locally without any external authentication.

## How It Works

Both migration formats are maintained in parallel:

- **Atlas migrations**: Located in `../migrations/` (parent directory)
- **golang-migrate migrations**: Located in this directory

When you create a new migration using `mise clickhouse:diff <name>`, both formats are automatically generated by the diff script.

## Configuration

The migration engine is controlled by the `CLICKHOUSE_MIGRATION_ENGINE` environment variable, which can be set in `mise.local.toml`:

```toml
[env]
CLICKHOUSE_MIGRATION_ENGINE = "golang-migrate"  # or "atlas"
```

If you don't have this variable set, the `mise zero:migrations` task will automatically detect whether you have Atlas installed and logged in, and configure the appropriate engine for you.

## Running Migrations

Use the standard mise task:

```bash
mise clickhouse:migrate
```

The script will automatically use the configured migration engine.

## URL Format Differences

Note that golang-migrate requires a different URL format than Atlas:

- **Atlas**: `clickhouse://user:password@host:port/database?params`
- **golang-migrate**: `clickhouse://host:port/database?username=user&password=pass&params`

This is handled automatically by using the `GRAM_CLICKHOUSE_GOMIGRATE_URL` environment variable for golang-migrate.
