From c4dbcdd1b8d45c96ff86dd9549b51f4cfa7cebc5 Mon Sep 17 00:00:00 2001 From: Harshini Rangaswamy Date: Thu, 5 Mar 2026 17:22:53 +0100 Subject: [PATCH 1/2] feat: add multi-version support docs for Aiven for ClickHouse --- .../howto/manage-clickhouse-versions.md | 128 ++++++++++++++++++ sidebars.ts | 1 + 2 files changed, 129 insertions(+) create mode 100644 docs/products/clickhouse/howto/manage-clickhouse-versions.md diff --git a/docs/products/clickhouse/howto/manage-clickhouse-versions.md b/docs/products/clickhouse/howto/manage-clickhouse-versions.md new file mode 100644 index 000000000..99c7018ae --- /dev/null +++ b/docs/products/clickhouse/howto/manage-clickhouse-versions.md @@ -0,0 +1,128 @@ +--- +title: Manage versions in Aiven for ClickHouse® +sidebar_label: Manage versions +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import ConsoleLabel from "@site/src/components/ConsoleIcons"; + +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 creating 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. +- 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 + +You can upgrade a service to a newer supported ClickHouse version using the +Aiven Console, CLI, API, or Terraform. + + + + +1. In the [Aiven Console](https://console.aiven.io), open your Aiven for ClickHouse service. +1. On the page, go to the **Maintenance** section. +1. Click > **Upgrade version**. +1. Select a version to upgrade to, and click **Upgrade**. + + + + +1. Check the available ClickHouse versions: + + ```bash + avn service versions + ``` + +1. Upgrade the service: + + ```bash + 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` + + + + +Use the +[ServiceUpdate](https://api.aiven.io/doc/#tag/Service/operation/ServiceUpdate) +endpoint and set `clickhouse_version`. + +```bash +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` + + + + +1. Update the + [`aiven_clickhouse`](https://registry.terraform.io/providers/aiven/aiven/latest/docs/resources/clickhouse) + resource and set `clickhouse_version`. + + ```hcl + user_config { + clickhouse_version = "CLICKHOUSE_VERSION" + } + ``` + + Set `CLICKHOUSE_VERSION` to the target ClickHouse version, for example `25.8`. + +1. Apply the change: + + ```bash + terraform apply + ``` + + + diff --git a/sidebars.ts b/sidebars.ts index b8db9b047..f41722cca 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1276,6 +1276,7 @@ const sidebars: SidebarsConfig = { 'products/clickhouse/howto/configure-backup', 'products/clickhouse/howto/manage-users-roles', 'products/clickhouse/howto/manage-databases-tables', + 'products/clickhouse/howto/manage-clickhouse-versions', 'products/clickhouse/howto/query-databases', 'products/clickhouse/howto/materialized-views', 'products/clickhouse/howto/monitor-performance', From 91283807b0624806f34223960e28b6a5fe1c08d0 Mon Sep 17 00:00:00 2001 From: Harshini Rangaswamy Date: Wed, 11 Mar 2026 15:22:08 +0100 Subject: [PATCH 2/2] update: feedback - test by forking --- .../clickhouse/howto/manage-clickhouse-versions.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/products/clickhouse/howto/manage-clickhouse-versions.md b/docs/products/clickhouse/howto/manage-clickhouse-versions.md index 99c7018ae..7cd8fb04e 100644 --- a/docs/products/clickhouse/howto/manage-clickhouse-versions.md +++ b/docs/products/clickhouse/howto/manage-clickhouse-versions.md @@ -16,7 +16,7 @@ Aiven for ClickHouse currently supports the following versions: - **25.3** (default) - **25.8** -If you do not specify a version when creating a service, the platform uses the default +If you do not specify a version when you create a service, the platform uses the default version. ## Before you upgrade @@ -24,7 +24,9 @@ version. Before upgrading your service, complete the following checks: - Review the upstream ClickHouse release notes. -- Test the upgrade in a development or staging environment. +- Test the upgrade in a development or staging environment by + [forking the service](/docs/platform/concepts/service-forking) and upgrading the fork + first. - Verify that your applications and clients support the target version. - Ensure recent backups are available. @@ -45,7 +47,7 @@ This process avoids modifying the existing nodes directly during the upgrade. ## Upgrade your service -You can upgrade a service to a newer supported ClickHouse version using the +Upgrade a service to a newer supported ClickHouse version using the Aiven Console, CLI, API, or Terraform.