DBAtlas · データベース運用アトラス

PostgreSQL メジャーアップグレード (pg_upgrade / ロジカルレプリケーション)

PostgreSQLレベル: 上級所要時間: 1〜3 時間 (+ データ量に依存)

メジャーバージョンのアップグレード (例: 16 → 17): 方式の選択 (pg_upgrade --link / --copy / --clone、またはロジカルレプリケーションによるほぼ無停止の移行)、pg_upgrade --check、拡張機能の互換性、設定の移行、統計情報の再収集、rsync または pg_basebackup によるスタンバイの再構築、旧クラスタの削除、切り戻し手順書。シングルサーバ、ストリーミングレプリケーション (プライマリ + スタンバイ)、Patroni クラスタ (Patroni 公式のメジャーアップグレード手順: Patroni を停止し、leader で pg_upgrade を実行、DCS の登録を削除し、replica を Patroni で再複製) に対応します。RHEL 系と Debian/Ubuntu (pg_upgradecluster を含む) が対象です。

同じメジャーバージョン内の更新 (例: 17.4 → 17.6) にはこのガイドではなく pg-minor-update を使います。テーブル単位の継続的なレプリケーションや部分的な移行には pg-logical-repl、小規模なデータベースをダンプで別サーバへ移す場合は pg-dump-restore を使います。

構成: 同一サーバでのインプレース (pg_upgrade。シングルサーバ、プライマリ + スタンバイ、または Patroni クラスタ) または新サーバへ (ロジカル)

シナリオ

  • メジャーアップグレード — メジャーバージョンのアップグレード (例: 16 → 17): 事前チェック、バックアップ、pg_upgrade またはロジカルレプリケーション、検証、後片付け。
  • 切り戻し (アップグレード失敗 / 中止) — アップグレードが途中で止まった、または新バージョンで問題が発生した: 旧バージョンに戻します。--link で新クラスタを起動済みの場合、戻せるのはバックアップからのみです。

開始前の確認

  • 移行元クラスタは PostgreSQL … で、PGDG リポジトリからインストールされている (pg-install)。移行先バージョン … は移行元より新しい。
  • アプリケーションとドライバを PostgreSQL … でテスト済みで、同じアップグレードをテスト環境でリハーサル済み。… までの各メジャーバージョンのリリースノートの「Migration to Version」の節 (廃止された設定、動作の変更) を確認済み。
  • インストール済みのすべての拡張機能 (PostGIS、pg_repack、pgaudit、TimescaleDB…) に … 用のビルドがある。… 用がない拡張機能があればアップグレードはできません。
  • …新データディレクトリ用に現在のデータ量と同じ空き容量がある。…旧データディレクトリと新データディレクトリが同じファイルシステム上にある (ハードリンクの条件)。WAL と新カタログ用に数 GB の空き容量がある。…ファイルシステムが reflink に対応しており (XFS reflink=1 または Btrfs)、両ディレクトリが同じファイルシステム上にある。…
  • ロジカルレプリケーションスロット / subscription があれば一覧化済み: …移行元が PostgreSQL 17 以降なら pg_upgrade はロジカルスロットを移行しますが、すべての変更が消費済みである必要があります…移行元が PostgreSQL … の場合、pg_upgrade はロジカルスロットを移行しないため、アップグレード後に再作成が必要です…。
  • プライマリから各スタンバイへ postgres ユーザでパスワードなしの SSH が可能で、スタンバイに rsync がインストールされている。データディレクトリの構成が …/<version>/data 形式である (rsync は共通の親ディレクトリを使う)。
  • スタンバイがストリーミング中で、プライマリの pg_hba.conf がレプリケーション接続を許可しており、… のパスワードがスタンバイの ~postgres/.pgpass にある。
  • Patroni クラスタが正常: … が現在の leader で、すべての replica が streaming かつ遅延なし、Pending restart なし。クラスタ名 …、設定ファイル …、REST API のパスワードは /etc/patroni/patroni.env (pg-patroni の構成)。DCS (etcd) のスナップショットバックアップを取得済み。アップグレード中はクラスタが完全に停止し、HAProxy/VIP 経由の接続は拒否されます。
  • Patroni のバージョンが PostgreSQL … に対応している (Patroni のリリースノートで新メジャーバージョン対応を確認)。古い Patroni は新バージョンのパラメータや制御ファイルを認識できない場合があります。必要なら先に Patroni をローリングで更新してください。
  • 移行先サーバに pg-install で PostgreSQL … をインストール済みで、空の状態で稼働している。移行元の拡張機能の … 用ビルドがインストール済み。移行先から移行元のポート … に到達できる。
  • 移行するテーブルに主キーまたは replica identity がある (ない場合、移行元で UPDATE/DELETE がエラーになります)。一覧に出たテーブルに PK を追加するか、ALTER TABLE … REPLICA IDENTITY FULL を適用してください。
  • 最新でリストアを検証済みのバックアップがある… (pgBackRest)…。可能ならサーバ/ディスクのスナップショットも取得する。… --link 方式では、新クラスタを起動した後に戻る手段はこれだけです。…

ガイドのフェーズ

  • 事前チェック — Patroni クラスタの状態を確認する · クラスタの属性を記録する · 拡張機能の RPM/deb を一覧表示する · プリペアドトランザクションと長時間トランザクションを確認する
  • 新クラスタの準備 — 新しいデータディレクトリを作成する · 同じ属性で新クラスタを作成する (initdb) · 設定を新クラスタへ移す · 新バージョンで無効な設定がないか確認する · Patroni のパラメータを新バージョンに合わせて確認する
  • バックアップと切り戻しポイント — バックアップを取得する (pgBackRest full) · バックアップを取得する (pg_dumpall + スナップショット)
  • 互換性チェック (pg_upgrade --check) — pg_upgrade --check
  • 停止: 旧クラスタを停止する — アプリケーションを停止する · 停止時の最終バックアップ (pgBackRest incr) · 停止時の最終論理バックアップ · 旧プライマリを停止する · replica で Patroni を停止する · leader で Patroni を停止する …
  • アップグレード — pg_upgrade を実行する · pg_upgradecluster でアップグレードする · conf.d のファイルを新クラスタへ移す · pgBackRest の設定を新クラスタ向けに変更する · patroni.yml の bin_dir と data_dir を新バージョンに変更する · pgBackRest の stanza を新バージョンにアップグレードする …
  • 新クラスタの起動 — 新クラスタを起動する · leader で Patroni を起動する · スタンバイをすぐに起動する
  • アップグレード後の作業 — 拡張機能を更新する · 統計情報を収集する · pgBackRest のチェックと新しいフルバックアップ
  • 検証 — バージョン、設定、データベース · Patroni クラスタを検証する · ログを確認する · アプリケーションのテスト
  • 旧クラスタの削除 — 旧データディレクトリを削除する · …replica…スタンバイ…の旧データディレクトリを削除する · 旧バージョンのソフトウェアを削除する
  • 移行元サーバの準備 — wal_level = logical · 移行元を再起動する · レプリケーションユーザを作成する · pg_hba.conf に移行先を追加する · pg_hba を再読み込みする · publication を作成する
  • 移行先のスキーマと subscription — 移行元のパスワードを .pgpass に書き込む · ロール (globals) をコピーする · スキーマをコピーする · subscription を作成する · 初期コピーの完了を待つ · 遅延を確認する
  • 最終切り替え (cutover) — 移行元で書き込みを停止する · 最後の変更が転送されたことを確認する · シーケンス値を転送する · subscription を削除する · 統計情報を収集する · アプリケーションを移行先に切り替える …
  • 切り戻し — 新クラスタを停止する · replica で Patroni を停止する · leader で Patroni を停止する · pg_control を元に戻す (--link、新クラスタは未起動) · …バックアップから切り戻す (--link、新クラスタは起動済み)…論理バックアップから切り戻す (--link、新クラスタは起動済み)… · Patroni なしでリカバリを完了する …
環境に合わせた手順プランを開く →