Manage versions in Aiven for ClickHouse®

Aiven for ClickHouse® supports multiple ClickHouse versions. You can select a version when creating a service and upgrade the service to a newer supported version later.

Supported ClickHouse versions

Aiven for ClickHouse currently supports the following versions:

• 25.3 (default)
• 25.8

If you do not specify a version when you create a service, the platform uses the default version.

For supported versions and end-of-life timelines, see Aiven for ClickHouse end-of-life policy.

Before you upgrade

Before upgrading your service, complete the following checks:

• Review the upstream ClickHouse release notes.
• Test the upgrade in a development or staging environment by forking the service and upgrading the fork first.
• Verify that your applications and clients support the target version.
• Ensure recent backups are available.
• Avoid running long-running queries or heavy ingestion during the upgrade.

Downgrading to an earlier ClickHouse version is not supported.

How upgrades work

During an upgrade, the platform replaces service nodes with new nodes running the selected version.

• New service nodes are created with the selected ClickHouse version.
• The new nodes start alongside the existing nodes.
• Data is streamed from the existing nodes to the new nodes.
• After the migration completes, the service switches to the upgraded nodes.
• The previous nodes are removed.

This process avoids modifying the existing nodes directly during the upgrade.

During this process:

• Queries connected to nodes being replaced can fail and require retries.
• New connections are routed to upgraded nodes.

Service availability during upgrades

The service remains available during the upgrade.

• New nodes are added and receive data before old nodes are removed, which helps keep the service reachable while the upgrade runs.
• Short interruptions can occur.
• Latency can increase and throughput can decrease during the upgrade.

Upgrade your service

Upgrade the service to a newer supported ClickHouse version using the Aiven Console, CLI, API, or Terraform.

Console

1. In the Aiven Console, open your Aiven for ClickHouse service.
2. On the Overview page, go to the Maintenance section.
3. Click Actions > Upgrade version.
4. Select a version to upgrade to, and click Upgrade.

CLI

1. Check the available ClickHouse versions:

   avn service versions

2. Upgrade the service:

   avn service update SERVICE_NAME \
     --project PROJECT_NAME \
     -c clickhouse_version="CLICKHOUSE_VERSION"

   Parameters:

   • SERVICE_NAME: Name of the service
   • PROJECT_NAME: Name of the project
   • CLICKHOUSE_VERSION: Target ClickHouse version, for example 25.8

API

Use the ServiceUpdate endpoint and set clickhouse_version.

curl --request PUT \
  --url "https://api.aiven.io/v1/project/PROJECT_NAME/service/SERVICE_NAME" \
  --header "Authorization: Bearer API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "user_config": {
      "clickhouse_version": "CLICKHOUSE_VERSION"
    }
  }'

Parameters:

• PROJECT_NAME: Name of the project
• SERVICE_NAME: Name of the service
• API_TOKEN: API authentication token
• CLICKHOUSE_VERSION: Target ClickHouse version, for example 25.8

Terraform

1. Update the aiven_clickhouse resource and set clickhouse_version.

   user_config {
     clickhouse_version = "CLICKHOUSE_VERSION"
   }

   Set CLICKHOUSE_VERSION to the target ClickHouse version, for example 25.8.

2. Apply the change:

   terraform apply