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.

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.

Downgrading to an earlier ClickHouse version is not supported.

How upgrades work

During a version upgrade, the platform replaces the 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.
• Once 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.

Upgrade your service

Upgrade a 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 \
     -c clickhouse_version="CLICKHOUSE_VERSION"

   Parameters:

   • SERVICE_NAME: Name of the service
   • 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.

1. Apply the change:

   terraform apply