> ## Documentation Index
> Fetch the complete documentation index at: https://clisma.poorquality.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Answers to common questions about clisma migrations

## Custom table name

You can override the table name in config:

```hcl theme={null}
env "local" {
  url = "http://default:password@localhost:8123/mydb"

  migrations {
    dir = "migrations"

    table {
      name = "custom_schema_migrations"
    }
  }
}
```

## Custom replication path

In clustered setups you can override the migrations table replication path used by `ReplicatedReplacingMergeTree(...)`:

```hcl theme={null}
env "production" {
  url = env("CLICKHOUSE_PROD_URL")

  migrations {
    dir = "migrations"

    table {
      name = "custom_schema_migrations"

      is_replicated = true

      # Optional: force a specific cluster for ON CLUSTER.
      cluster_name = "prod-cluster"

      # If replication_path is set, is_replicated can be omitted.
      replication_path = "/clickhouse/foo/bar/custom_schema_migrations"
    }
  }
}
```

Default replication path:

```text theme={null}
/clickhouse/tables/cluster-{cluster}/shard-{shard}/{database}/${migrations.table.name}
```

### Summary

If `migrations.table.is_replicated` is `true`, clisma treats the environment as clustered and creates the migrations table using `ReplicatedReplacingMergeTree(...)` with `ON CLUSTER "<detected_cluster>"`.

If `migrations.table.is_replicated` is not set (or `false`), it uses `ReplacingMergeTree()` in standalone mode.

If `migrations.table.replication_path` is set, clisma also enables replicated mode even when `migrations.table.is_replicated` is omitted.

If your ClickHouse has multiple non-default clusters, set `migrations.table.cluster_name` to choose which cluster should be used in `ON CLUSTER`.

## How config affects migrations table DDL

### 1) Standalone (default)

Config:

```hcl theme={null}
migrations {
  dir = "migrations"
}
```

DDL shape:

```sql theme={null}
CREATE TABLE IF NOT EXISTS schema_migrations (
  ...
) ENGINE = ReplacingMergeTree()
ORDER BY version;
```

### 2) Replicated (auto cluster detection)

Config:

```hcl theme={null}
migrations {
  dir = "migrations"
  table {
    is_replicated = true
  }
}
```

DDL shape:

```sql theme={null}
CREATE TABLE IF NOT EXISTS schema_migrations ON CLUSTER "<detected_cluster>" (
  ...
) ENGINE = ReplicatedReplacingMergeTree(
  '/clickhouse/tables/cluster-{cluster}/shard-{shard}/{database}/schema_migrations',
  '{replica}'
)
ORDER BY version;
```

### 3) Replicated with explicit cluster and path

Config:

```hcl theme={null}
migrations {
  dir = "migrations"
  table {
    name = "custom_schema_migrations"
    cluster_name = "prod-cluster"
    replication_path = "/clickhouse/foo/bar/custom_schema_migrations"
  }
}
```

DDL shape:

```sql theme={null}
CREATE TABLE IF NOT EXISTS custom_schema_migrations ON CLUSTER "prod-cluster" (
  ...
) ENGINE = ReplicatedReplacingMergeTree(
  '/clickhouse/foo/bar/custom_schema_migrations',
  '{replica}'
)
ORDER BY version;
```

## Does clisma support down migrations?

No. This is intentional. ClickHouse DDL and data changes are often non-transactional and may be irreversible. Reliable rollbacks are hard to guarantee and can introduce more risk than they remove. The expected workflow is to apply new forward migrations that correct or compensate for previous changes.

## Does clisma support multi-statement migrations?

Yes. You can include multiple SQL statements in one file. Separate statements with semicolons; clisma splits them outside of strings and comments.

## Checksum mismatch

If a migration file changes after being applied, clisma will fail with a checksum mismatch. You have two options:

* Revert the migration file back to the applied version and create a new forward migration.
* If you really need to override the checksum, update the stored checksum in the migrations table (use `clisma checksum <migration path>`). This is risky and should only be done if you fully understand the consequences.