ClickHouse エンジンバージョンのアップグレード - ApsaraDB for ClickHouse

本トピックでは、コンソールで ApsaraDB for ClickHouse Community-compatible Edition クラスターのメジャーエンジンバージョンをワンクリックでアップグレードする方法について説明します。

背景情報

サービスエクスペリエンスを向上させるため、古いクラスターは速やかに最新バージョンにアップグレードしてください。ApsaraDB for ClickHouse Community-compatible Edition は、コンソールでワンクリックアップグレード機能を提供しています。アップグレードプロセスは、クラスターアーキテクチャによって異なります。

旧アーキテクチャのクラスターの場合、システムは最新バージョンを実行する新しいクラスターを自動的に作成し、ソースクラスターから新しいクラスターにデータを移行してアップグレードを完了します。
新アーキテクチャのクラスターの場合、システムはインスタンスをクローンしてカーネルをアップグレードすることにより、インスタンスのバージョンを直接更新します。

スムーズな移行を確実にするために、ご利用のクラスターのバージョンに適したアップグレード操作を選択してください。

事前準備：クラスターアーキテクチャの確認

アップグレードの前に、コンソールでクラスターアーキテクチャを確認し、適切な検証方法と手順を選択します。手順は以下の通りです。

[クラスター] ページで、対象クラスターの ID をクリックし、クラスター情報 ページに移動します。
クラスターのプロパティ セクションで、メジャーバージョンのアップグレード をクリックします。これは Version の右側にあります。
表示された メジャーバージョンのアップグレード ダイアログボックスで、3 番目の 時間を設定するための設定項目を確認します。
- バージョンアップグレードの実行時間：：新アーキテクチャのクラスターを示します。
- 書き込み停止時間：旧アーキテクチャのクラスターを示します。

新アーキテクチャのクラスターをアップグレードするには、「新アーキテクチャクラスターのアップグレード」をご参照ください。

旧アーキテクチャのクラスターをアップグレードするには、「旧アーキテクチャクラスターのアップグレード」をご参照ください。

新アーキテクチャクラスターのアップグレード

前提条件

クラスターが [実行中] 状態であること。

注意事項

ワンクリックでのメジャーエンジンバージョンのアップグレードプロセスが開始されると、キャンセルすることはできません。
説明
ワンクリックでのメジャーエンジンバージョンのアップグレード後は、バージョンのロールバックはサポートされていません。アップグレード後に以前のバージョンにロールバックする機能が必要な場合は、クラスターをクローンしてアップグレードできます。詳細については、「クローンによるメジャーエンジンバージョンのアップグレード」をご参照ください。
ワンクリックでのメジャーエンジンバージョンのアップグレードは単一のクラスターに適用され、アップグレード完了後にソースバージョンにロールバックすることはできません。
スムーズなアップグレードを確実にするために、アップグレードを開始する前にアプリケーションからの書き込み操作を停止してください。アップグレード中にクラスターは自動的に書き込みを停止しますが、アプリケーションが事前に書き込みを停止しない場合、同期の待機時間が長くなったり、同期が迅速に完了しなかったりする可能性があります。これはアップグレードの適時性に影響を与える可能性があります。
アップグレードがサービスに与える影響を軽減するために、アップグレードを開始する前に以下の検証を行ってください。
- 互換性とパフォーマンスの検証：書き込みおよびクエリ操作の機能、構文、パフォーマンスの違いを検証します。
- アップグレード期間の検証：バージョンアップグレード中にインスタンスは複数回再起動します。データベース、テーブル、またはパーティション (Parts) が多数あるインスタンスでは、再起動に時間がかかる場合があります。
  重要
  クラスターに大量のデータがコールドストレージにあり、クローン検証を使用する場合、ワンクリックアップグレードはクローン検証よりも時間がかかります。これは、クローン操作にコールドデータが含まれないためです。
検証の実行方法の詳細については、「バージョンの互換性の検証」をご参照ください。

クラスターへの影響

バージョンアップグレード中、クラスターは複数回再起動し、読み取りおよび書き込み操作ができなくなります。アップグレードはオフピーク時間帯に実行してください。

バージョンの互換性の検証

ワンクリックでのメジャーエンジンバージョンのアップグレードは単一のクラスターのみを対象とし、ロールバックできないため、事前にアップグレードをテストする必要があります。続行する前に、新バージョンがソースバージョンの機能と完全に互換性があることを確認し、アップグレード期間を検証してください。手順は以下の通りです。

重要

クラスターでホットデータとコールドデータの階層型ストレージが有効になっている場合、クローン操作にはホットデータのみが含まれます。新しいクラスターではコールドデータをクエリできません。

対象インスタンスの クラスター情報 ページに移動します。左側のナビゲーションウィンドウで、バックアップリカバリ をクリックします。インスタンスがバックアップされた後、インスタンスの復元 をクリックします。
リアルタイムレプリカからクローンすることを選択し、ターゲットカーネルバージョンをアップグレード先のバージョンに設定します。
クローンクラスターを作成します。
互換性検証を実行します。
1. アプリケーションのクエリと新バージョンの互換性を検証します。詳細については、「SQL 互換性の検証」をご参照ください。
2. ビジネスの特徴に戻りましょう。

操作手順

Alibaba Cloud アカウントで ApsaraDB for ClickHouse コンソールにログインします。
ページの左上隅で、対象クラスターが配置されているリージョンを選択します。
左側のナビゲーションウィンドウで、Community Edition インスタンスのリスト をクリックします。
対象クラスターを見つけ、クラスター ID をクリックして クラスター情報 ページに移動します。
クラスターのプロパティ セクションで、 メジャーバージョンのアップグレード をクリックします。このオプションは Versionの右側にあります。

指示に従って次のパラメーターを設定し、 を決定 ボタンをクリックします。

設定項目	説明	例
[クラスターカーネルバージョンをアップグレード]	ターゲットクラスターのバージョン。アップグレード後にバージョンをロールバックすることはできません。現在、バージョン 25.3 のみがサポートされています。	23.8 (LTS バージョン)
[バージョンアップグレードの実行時間]	クラスターバージョンのアップグレードの実行時間。重要指定時刻またはメンテナンスウィンドウ内でのアップグレードを選択すると、クラスターのステータスが Running からバージョンをアップグレードしていますに変わります。指定時刻またはメンテナンスウィンドウに達するまで、クラスターは通常通り読み取りおよび書き込みリクエストを処理できますが、アップグレード、スペックダウン、スケーリング、移行などの O&M 操作は実行できません。指定時間：将来の時点を選択してメジャーバージョンのアップグレードを実行します。メンテナンス可能な時間帯にアップグレードする：現在のクラスターのメンテナンスウィンドウがデフォルトで選択されます。今すぐアップグレード：アップグレード操作を直ちに実行します。	2024-05-29 14:46
[クローン検証を実行するかどうか]	クローン検証が実行されましたまたはクローン検証のスキップ (非推奨) を選択します。	クローン検証を実行

旧アーキテクチャクラスターのアップグレード

前提条件

クラスターが [実行中] 状態であること。

注意事項

ワンクリックでのメジャーエンジンバージョンのアップグレードは単一のクラスターに適用され、アップグレード完了後にソースバージョンにロールバックすることはできません。
説明
ワンクリックでのメジャーエンジンバージョンのアップグレード後は、バージョンのロールバックはサポートされていません。アップグレード後に以前のバージョンにロールバックする機能が必要な場合は、データを移行してアップグレードできます。詳細については、「移行によるアップグレード」をご参照ください。
クラスターをアップグレードする際、データベースとテーブルについて以下の点にご注意ください。
- MergeTree ファミリーエンジンを使用するテーブルの場合、既存データは新しいクラスターに移行され、アップグレード中に自動的に再分散されます。
- 外部テーブルやログテーブルなど、MergeTree ファミリーエンジンを使用しないテーブルの場合、テーブルスキーマのみが移行されます。データは移行されません。
- マテリアライズドビューの場合、スキーマのみが移行されます。データは移行されません。
- Kafka または RabbitMQ エンジンを使用するテーブルは、移行がサポートされていません。アップグレード前にこれらのテーブルを削除する必要があります。
- アップグレード後、内部ノードの IP アドレスが変更されます。データの書き込みやアクセスがノードの IP アドレスに依存している場合は、クラスターの VPC CIDR ブロックを再度取得する必要があります。詳細については、「クラスターの VPC CIDR ブロックの取得」をご参照ください。
アップグレードがサービスに与える影響を軽減するために、アップグレードを開始する前に以下の検証を行ってください。
- 互換性とパフォーマンスの検証：書き込みおよびクエリ操作の機能、構文、パフォーマンスの違いを検証します。
- アップグレード期間の検証：バージョンアップグレード中にインスタンスは複数回再起動します。データベース、テーブル、またはパーティション (Parts) が多数あるインスタンスでは、再起動に時間がかかる場合があります。
検証の実行方法の詳細については、「バージョンの互換性の検証」をご参照ください。

クラスターへの影響

Community-compatible Edition クラスターのアップグレード中、移行の最後の 10 分間 (書き込みが許可されない) を除き、クラスターは読み取りおよび書き込み操作が可能です。残りの移行時間を確認するには、「アップグレード進捗の表示」をご参照ください。

バージョンの互換性の検証

新しいクラスターを購入して移行検証を実行します。詳細については、「データ移行によるメジャーエンジンバージョンのアップグレード」をご参照ください。
新しいクラスターで、SQL 互換性の検証を実行します。詳細については、「SQL 互換性の検証」をご参照ください。
アプリケーションの機能について回帰テストを実行して検証します。

クラスターのアップグレード

Alibaba Cloud アカウントで ApsaraDB for ClickHouse コンソールにログインします。
ページの左上隅で、対象クラスターが配置されているリージョンを選択します。
左側のナビゲーションウィンドウで、Community Edition インスタンスのリスト をクリックします。
対象クラスターを見つけ、クラスター ID をクリックして クラスター情報 ページに移動します。
クラスターのプロパティセクションで、メジャーバージョンのアップグレード (Versionの右側) をクリックします。

プロンプトに従って次のパラメーターを設定し、 を決定 ボタンをクリックします。

設定項目	説明	例
[インスタンスカーネルバージョンをアップグレード]	ターゲットクラスターのバージョン。アップグレード後にバージョンをロールバックすることはできません。現在、バージョン 23.8 のみがサポートされています。	23.8 (LTS バージョン)
書き込み停止時間	アップグレード前後のデータ整合性を確保するため、アップグレードの最後の 10 分間にクラスターは自動的に書き込み操作を停止します。書き込み停止時間の設定には以下のルールが適用されます。アップグレードを成功させるために、書き込み停止時間を少なくとも 30 分に設定してください。アップグレードは 5 日以内に完了する必要があります。したがって、書き込み停止時間の終了日は、`現在の日付 + 5 日` 以下でなければなりません。書き込み停止がビジネスに与える影響を軽減するために、書き込み停止時間をオフピーク時間帯に設定してください。	`2025-03-20 10:08` - `2025-03-25 10:08`
インスタンス移行検証を実行	Verification Performed または [インスタンス移行検証をスキップ (非推奨)] を選択します。	インスタンス移行検証を実行

次のステップ：
- アップグレードの進捗状況を確認するには、「アップグレード進捗の表示」をご参照ください。
- 指定した書き込み停止時間を過ぎてもクラスターのステータスが [アップグレード中] のままである場合は、移行を完了するために書き込み停止時間を変更する必要があります。
- アップグレードがサービスに影響を与え、停止したい場合は、アップグレードをキャンセルできます。

アップグレード進捗の表示

Alibaba Cloud アカウントで ApsaraDB for ClickHouse コンソールにログインします。
ページの左上隅で、対象クラスターが配置されているリージョンを選択します。
左側のナビゲーションウィンドウで、Community Edition インスタンスのリスト をクリックします。
対象クラスターを見つけ、クラスター ID をクリックして クラスター情報 ページに移動します。
クラスターの状態 セクションにある、View Progress (Status の右側) をクリックします。
表示される 書き込み停止ウィンドウの変更 ダイアログボックスで、スペックアップの進捗を確認できます。たとえば、MergeTree のスキーマ移行の進捗、データ移行、データ移行の推定残り時間、およびその他のスキーマ移行の進捗などを確認できます。

書き込み停止時間の変更

指定した書き込み停止時間を過ぎてもクラスターのステータスが [アップグレード中] のままである場合、データ移行はまだ完了していません。アップグレードを正常に完了させるために、書き込み停止時間を調整する必要があります。

Alibaba Cloud アカウントで ApsaraDB for ClickHouse コンソールにログインします。
ページの左上隅で、対象クラスターが配置されているリージョンを選択します。
左側のナビゲーションウィンドウで、Community Edition インスタンスのリスト をクリックします。
対象クラスターを見つけ、クラスター ID をクリックして クラスター情報 ページに移動します。
クラスターの状態 セクションで、View Progress (Statusの右) をクリックします。
表示される 書き込み停止ウィンドウの変更 ダイアログボックスで、 書き込み停止時間 を変更し、 [確認]をクリックします。
説明
書き込み停止時間 の設定ルールは、「クラスターのアップグレード」で説明されている 書き込み停止時間 パラメーターのルールと同じです。

アップグレードのキャンセル

アップグレードがサービスに影響を与え、停止したい場合は、アップグレードをキャンセルできます。

Alibaba Cloud アカウントで ApsaraDB for ClickHouse コンソールにログインします。
ページの左上隅で、対象クラスターが配置されているリージョンを選択します。
左側のナビゲーションウィンドウで、Community Edition インスタンスのリスト をクリックします。
対象クラスターを見つけ、クラスター ID をクリックして クラスター情報 ページに移動します。
クラスターの状態 セクションで、View Progress をクリックします。これは Status の右側にあります。
表示された 書き込み停止ウィンドウの変更 ダイアログボックスで、Cancel Upgradeをクリックします。
説明
Cancel Upgrade をクリックしても、アップグレードタスクはすぐには停止せず、約 5 分後に完全に停止します。

よくある質問

Q：メジャーエンジンバージョンのアップグレード中に Unsupported Kafka table definition というエラーが報告された場合はどうすればよいですか？

A：現在のバージョンの Kafka テーブルでは、DEFAULT キーワードを使用してデフォルトのフィールド値を定義することがサポートされていません。これにより、カーネルパッケージの起動に失敗します。この問題を解決するには、以下の手順を実行してください。

select create_table_query from system.tables where engine = 'Kafka' 文を実行して、すべての Kafka テーブルを検索します。
テーブルのデータ定義言語 (DDL) 文をバックアップします。
テーブルを削除します。
テーブルを再作成します。
重要
テーブルを再作成する際、DEFAULT キーワードを使用してデフォルトのフィールド値を定義しないでください。

Q：メジャーエンジンバージョンのアップグレード中に Unsupported MaterializedMySQL table definition というエラーが報告された場合はどうすればよいですか？

A：現在のバージョンの MaterializedMySQL エンジンの設定パラメーターは、ソースクラスターのバージョンと互換性がありません。この問題を解決するには、以下の手順を実行してください。

select name from system.databases where engine = 'MaterializedMySQL' 文を実行して、MaterializedMySQL エンジンを使用するデータベースを検索します。
データベースの DDL 文をバックアップします。
データベースを削除します。
カーネルバージョンをアップグレードします。
バックアップした DDL 文をターゲットバージョンと互換性があるように調整し、MaterializedMySQL エンジンを使用するデータベースを再作成します。

Q：メジャーエンジンバージョンのアップグレード中に Unsupported table definition other than 20.3: Nullable(Array(*))/SecondaryIndex(KEY definition exists) というエラーが報告された場合はどうすればよいですか？

A：クラスターのバージョンが 20.3 の場合、Alibaba Cloud が開発した以下のような機能を使用している可能性があります。

Nullable(Array(*)) 型のテーブルフィールドの定義。
KEY キーワードを使用して定義されたセカンダリインデックス。

これらの機能はオープンソースの ClickHouse にマージされていないため、20.8 以降のインスタンスバージョンには含まれていません。アップグレードする前に関連するテーブルを調整してください。以下の操作を実行できます。

ソースクラスターのバージョンとターゲットバージョンの互換性を検証します。
重要
20.3 と現在のバージョンの間のバージョン差が大きいため、サービスに影響を与えないように、アップグレードを実装する前に徹底的な検証を行う必要があります。
Nullable(Array(*)) で修飾されたフィールドを削除し、再度フィールドを追加します。
KEY キーワードで定義されたセカンダリインデックスを削除します。アップグレードが完了した後、テーブルに再度スキップインデックスを追加します。
重要
2 種類のインデックスは実装原理が異なるため、パフォーマンスに差が生じる可能性があります。

参考資料

データ移行と同期。

移行によるメジャーエンジンバージョンのアップグレード

クローンによるメジャーエンジンバージョンのアップグレード。

マイナーエンジンバージョンのアップグレード。