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/database 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.