> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> アップデートに関するドキュメント

# セルフマネージドのアップグレード

<div id="clickhouse-upgrade-overview">
  ## ClickHouse アップグレードの概要
</div>

このドキュメントには、次の内容が含まれています。

* 一般的なガイドライン
* 推奨される手順
* システム上のバイナリをアップグレードする際の詳細

<div id="general-guidelines">
  ## 一般的なガイドライン
</div>

以下の注意事項は、計画を立てる際の参考になるほか、この後の文書でそのような推奨を行っている理由を理解するのにも役立ちます。

<div id="upgrade-clickhouse-server-separately-from-clickhouse-keeper-or-zookeeper">
  ### ClickHouse server は ClickHouse Keeper または ZooKeeper とは別にアップグレードする
</div>

ClickHouse Keeper または Apache ZooKeeper に対するセキュリティ修正が必要でない限り、ClickHouse server のアップグレード時に Keeper もアップグレードする必要はありません。アップグレードの過程では Keeper の安定性を維持する必要があるため、Keeper のアップグレードを検討する前に、まず ClickHouse server のアップグレードを完了してください。

<div id="minor-version-upgrades-should-be-adopted-often">
  ### マイナーバージョンのアップグレードはこまめに行うべきです
</div>

新しいマイナーバージョンがリリースされたら、常にできるだけ早く最新バージョンへアップグレードすることを強く推奨します。マイナーリリースに破壊的変更はありませんが、重要なバグ修正 (場合によってはセキュリティ修正も) を含んでいます。

<div id="test-experimental-features-on-a-separate-clickhouse-server-running-the-target-version">
  ### 対象バージョンで稼働する別の ClickHouse server で実験的機能をテストする
</div>

実験的機能の互換性は、いつどのように破綻してもおかしくありません。実験的機能を使用している場合は、changelog を確認し、対象バージョンをインストールした別の ClickHouse server を用意して、そこで実験的機能の利用をテストすることを検討してください。

<div id="downgrades">
  ### ダウングレード
</div>

アップグレード後、新しいバージョンが依存している一部の機能と互換性がないことに気付いた場合でも、新機能をまだ一切使用していなければ、比較的新しい (1年未満の) バージョンにダウングレードできることがあります。いったん新機能を使用すると、ダウングレードはできなくなります。

<div id="multiple-clickhouse-server-versions-in-a-cluster">
  ### 1 つのクラスター内に複数の ClickHouse server バージョンがある場合
</div>

当社では、1 年間の互換性ウィンドウ (2 つの LTS バージョンを含む) を維持するよう努めています。つまり、任意の 2 つのバージョンの差が 1 年未満である場合 (またはその間に LTS バージョンが 2 つ未満しかない場合) 、それらは同じクラスター内で連携して動作できるはずです。ただし、distributed queries の性能低下や、ReplicatedMergeTree における一部のバックグラウンド操作で再試行可能な error など、軽微な問題が発生する可能性はあるため、クラスター内のすべてのメンバーはできるだけ早く同じバージョンにアップグレードすることを推奨します。

リリース日の差が 1 年を超える異なるバージョンを同じクラスターで実行することは、決して推奨しません。データ損失が発生することは想定していませんが、クラスターが使用不能になる可能性があります。バージョン差が 1 年を超える場合に想定される問題には、次のようなものがあります。

* クラスターが動作しない可能性がある
* 一部、あるいはすべての queries が予期しない error で失敗する可能性がある
* 予期しない error や警告が logs に表示される可能性がある
* ダウングレードできなくなる可能性がある

<div id="incremental-upgrades">
  ### 段階的なアップグレード
</div>

現在のバージョンと対象バージョンの差が1年を超える場合は、次のいずれかの方法を推奨します。

* ダウンタイムを伴うアップグレードを行う (すべてのサーバーを停止し、すべてのサーバーをアップグレードした後、すべてのサーバーを起動する) 。
* または、中間バージョンを経由してアップグレードする (現在のバージョンより1年未満だけ新しいバージョン) 。

<div id="recommended-plan">
  ## 推奨プラン
</div>

以下は、ClickHouse をダウンタイムなしでアップグレードするための推奨手順です。

1. 設定変更をデフォルトの `/etc/clickhouse-server/config.xml` ファイルには入れず、代わりに `/etc/clickhouse-server/config.d/` に配置してください。`/etc/clickhouse-server/config.xml` はアップグレード時に上書きされる可能性があるためです。
2. 互換性のない変更がないか、[changelog](/ja/resources/changelogs/oss/2026) を確認してください (対象リリースから現在使用中のリリースまでさかのぼって確認します) 。
3. 互換性のない変更として挙がっている項目のうち、アップグレード前に対応できるものは事前に対応し、アップグレード後に必要な変更は一覧にまとめてください。
4. 各分片について、同じ分片内の他のレプリカをアップグレードしている間も稼働させておくレプリカを 1 つ以上特定してください。
5. アップグレード対象のレプリカでは、1 台ずつ次を実施します:

* ClickHouse server を停止する
* server を対象バージョンにアップグレードする
* ClickHouse server を起動する
* システムが安定したことを示す Keeper メッセージが出るまで待機する
* 次のレプリカに進む

6. Keeper log と ClickHouse log にエラーがないか確認します

7. 手順 4 で特定したレプリカを新しいバージョンにアップグレードします

8. 手順 1 〜 3 で作成した変更一覧を参照し、アップグレード後に必要な変更を行います。

<Note>
  このエラーメッセージは、レプリケート環境で複数のバージョンの ClickHouse が稼働している場合には想定内です。すべてのレプリカが同じバージョンにアップグレードされると、表示されなくなります。

  ```text theme={null}
  MergeFromLogEntryTask: Code: 40. DB::Exception: Checksums of parts don't match:
  hash of uncompressed files doesn't match. (CHECKSUM_DOESNT_MATCH)  Data after merge is not
  byte-identical to data on another replicas.
  ```
</Note>

<div id="clickhouse-server-binary-upgrade-process">
  ## ClickHouse server バイナリのアップグレード手順
</div>

ClickHouse を `deb` パッケージからインストールした場合は、サーバー上で次のコマンドを実行します。

```bash theme={null}
$ sudo apt-get update
$ sudo apt-get install clickhouse-client clickhouse-server
$ sudo service clickhouse-server restart
```

推奨されている `deb` パッケージ以外の方法で ClickHouse をインストールした場合は、適切な更新方法を使用してください。

<Note>
  1 つの分片のすべてのレプリカが同時にオフラインになるタイミングが発生しない限り、複数のサーバーを同時に更新できます。
</Note>

古いバージョンの ClickHouse を特定のバージョンにアップグレードする場合:

例:

`xx.yy.a.b` は現在の安定版バージョンです。最新の安定版バージョンは[こちら](https://github.com/ClickHouse/ClickHouse/releases)で確認できます。

```bash theme={null}
$ sudo apt-get update
$ sudo apt-get install clickhouse-server=xx.yy.a.b clickhouse-client=xx.yy.a.b clickhouse-common-static=xx.yy.a.b
$ sudo service clickhouse-server restart
```