Skip to main content

Managing ClickHouse Cloud via Atlas

This guide walks you through managing ClickHouse Cloud databases using Atlas, covering connection setup, development database considerations, and best practices for cloud environments.

Prerequisites​

Before starting, ensure you have:

Getting ClickHouse Cloud Connection URL​

Step 1: Access Your ClickHouse Cloud Service​

Navigate to your ClickHouse Cloud console and locate your service. You'll need to gather the following information: Navigate to the sidebar click "Connect" then a popup will appear with your service endpoint and connection parameters.

ClickHouse Cloud Console

Step 2: Retrieve Connection Details​

From your ClickHouse Cloud service page, copy the connection details:

  • Host: Your service endpoint (e.g., abc123.clickhouse.cloud)
  • Port: Usually 9440 for native protocol
  • Database: Your database name (default is often default)
  • Username: Your ClickHouse Cloud username
  • Password: Your ClickHouse Cloud password

Step 3: Construct the Atlas Connection URL​

To connect to ClickHouse Cloud, we need to use native protocol port 9440 with SSL enabled:

For example:

clickhouse://myuser:mypassword@abc123.clickhouse.cloud:9440/default?secure=true
note

Always use secure=true for ClickHouse Cloud connections as they require SSL/TLS encryption.

Step 4: Verify Connection with Atlas​

Once you have your connection URL, verify that Atlas can connect to your ClickHouse Cloud service by inspecting the schema:

atlas schema inspect \
  --url "clickhouse://myuser:mypassword@abc123.clickhouse.cloud:9440/default?secure=true"

The output should look like this:

schema "default" {
  engine = sql("Shared")
}

Development Database Setup​

When working with ClickHouse Cloud, the recommended approach is to use a separate ClickHouse Cloud instance as your development database. This ensures full compatibility between your development and production environments, eliminating potential differences in engines, features, and behaviors.

Benefits of this approach include:

  • ✅ Full Compatibility: Dev and production environments are completely identical
  • ✅ Zero Configuration Differences: Same engines, features, and settings across environments
  • ✅ Complete Feature Parity: Access to all ClickHouse Cloud features in development

ClickHouse Cloud services automatically idle when not in use:

Cost Savings

ClickHouse Cloud's idle feature means your development database won't incur costs when not actively being used, making it economical to maintain a separate dev service.

Option 2: Use a Local ClickHouse Docker Instance​

Atlas also supports using a local ClickHouse instance (via Docker) for development. This approach can be useful for quick iterations, offline development, or minimizing cloud costs during early development stages.

How It Works​

When using a local ClickHouse instance with ClickHouse Cloud production, Atlas automatically handles engine conversion differences during schema comparisons.

Example: Engine Conversion for Schema Comparison​

If your schema defines a table in your local instance using a standard MergeTree engine:

-- On Your Local Instance
CREATE TABLE my_table (
  id UInt64
) ENGINE = MergeTree
ORDER BY id;

And on ClickHouse Cloud, the equivalent engine is SharedMergeTree:

-- On Your ClickHouse Cloud Instance
CREATE TABLE my_table (
  id UInt64
) ENGINE = SharedMergeTree
ORDER BY id;

Atlas will handle this conversion internally during schema comparison, so no drifts are detected.

Engine Conversion for Schema Comparison​

Atlas performs the following engine conversions internally when comparing schemas between local and cloud environments. This ensures that functionally equivalent engines don't trigger false schema drifts:

Local EngineClickHouse Cloud EquivalentConversion Purpose
MergeTreeSharedMergeTreeSchema comparison only
ReplacingMergeTreeSharedReplacingMergeTreeSchema comparison only
SummingMergeTreeSharedSummingMergeTreeSchema comparison only
CollapsingMergeTreeSharedCollapsingMergeTreeSchema comparison only
VersionedCollapsingMergeTreeSharedVersionedCollapsingMergeTreeSchema comparison only
ReplicatedMergeTreeSharedMergeTreeSchema comparison only
ReplicatedReplacingMergeTreeSharedReplacingMergeTreeSchema comparison only
ReplicatedSummingMergeTreeSharedSummingMergeTreeSchema comparison only
Schema Comparison vs Migration Generation

Atlas only converts engines for schema comparison purposes. Your migration files will contain the original engine definitions from your schema. ClickHouse Cloud automatically handles the actual engine conversion when tables are created.

⚠️ Important Considerations:

  • Engine conversion works for basic scenarios but may not cover complex configurations
  • Some ClickHouse Cloud-specific features are not available in local instances
  • Performance characteristics may differ between local and cloud environments
  • For production applications, we strongly recommend using Option 1 (separate cloud instance)
Development Experience

We are continuously improving the local development experience with engine conversion. If you encounter any issues or need assistance, feel free to reach out to us on Discord Server or open an issue on our GitHub Repo.