Skip to main content

​
Custom table name

You can override the table name in config: 
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(...): 
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: 
/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: 
migrations {
  dir = "migrations"
}
DDL shape: 
CREATE TABLE IF NOT EXISTS schema_migrations (
  ...
) ENGINE = ReplacingMergeTree()
ORDER BY version;

​
2) Replicated (auto cluster detection)

Config: 
migrations {
  dir = "migrations"
  table {
    is_replicated = true
  }
}
DDL shape: 
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: 
migrations {
  dir = "migrations"
  table {
    name = "custom_schema_migrations"
    cluster_name = "prod-cluster"
    replication_path = "/clickhouse/foo/bar/custom_schema_migrations"
  }
}
DDL shape: 
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.