Skip to main content

Managing Schema Changes in ClickHouse Clusters

Managing schema changes in ClickHouse clusters with Atlas requires understanding several key concepts. While Atlas works seamlessly with both single-node and cluster deployments, cluster mode introduces specific considerations that must be addressed to ensure reliable schema management.

This guide covers essential topics and best practices for managing schema changes across your ClickHouse cluster with Atlas, ensuring consistency and reliability in distributed environments.

Dev Database Requirements for Cluster Mode​

Atlas relies on a dev database to normalize and validate schema changes before applying them to your production cluster.

Important

When working with ClickHouse clusters, your dev database must also be configured as a cluster. This requirement ensures proper handling of cluster-specific features, including the ON CLUSTER clause, replicated engines, and distributed tables.

While Atlas can automatically spin up ephemeral single-node ClickHouse containers using the docker:// protocol, this approach is not compatible with cluster environments. Instead, you must manually configure a multi-node dev environment that mirrors your production topology.

ClickHouse provides official Docker Compose recipes for quickly setting up local clusters. Select a recipe that closely matches your production topology to ensure schema changes are validated correctly before deployment.

Enabling Cluster Mode​

To enable cluster mode, add the mode=cluster query parameter to your ClickHouse connection URLs:

env "production" {
  url = "clickhouse://user:password@prod-host:9000/default?mode=cluster"
  dev = "clickhouse://user:password@dev-host:9000/default?mode=cluster"
}
info

Both your production database URL and dev database URL must include the mode=cluster parameter for Atlas to function correctly in cluster environments.

When cluster mode is enabled, Atlas automatically adjusts its behavior to accommodate cluster-specific features:

  • Migration Planning: Generated migrations automatically include ON CLUSTER '{cluster}' clauses to propagate changes across all cluster nodes.
  • Version Tracking: In the versioned workflow, Atlas automatically creates the atlas_schema_revisions table using a replicated engine, ensuring consistent read and write operations for version tracking across the entire cluster.

Additional Resources​