PostgreSQL 18移行で詰まる3症状と切り分け手順

PostgreSQL 18は2025年9月にリリースされたメジャーバージョンです。initdbの既定値変更、非同期I/Oの導入、pg_upgradeによる統計情報の引き継ぎなど、移行時の挙動に直接影響する変更が複数入りました。そのため17までと同じ手順をそのまま流すと、pg_upgradeが途中で停止する、アプリから認証に失敗する、バージョンは上がったのに応答が遅いという3種類の症状が出ます。

この記事は要約版です。症状ごとの詳しい対処手順、確認コマンドと出力の読み方、移行前チェックリストは、ブログの完全版にまとめています: PostgreSQL 18 移行でつまずく原因と対処法

結論：既定値の変更点を先に確認する

最初に見るのは3点です。18で本当に動いているかとチェックサム設定が旧クラスタと一致しているかというクラスタの物理状態、pg_upgradeの出力ディレクトリとサーバログのFATAL/WARNING行、そして変更された既定値（data_checksums、password_encryption、io_method、effective_io_concurrency）です。当たりを付けずに設定を触ると状態が悪化します。

症状別の切り分け順は決まっています。pg_upgradeが完走しないならチェックサム不一致、拡張ライブラリ不足、ロケールとエンコーディング、ディスク容量の順。接続できないならpg_hba.confの認証方式、ロールのパスワード検証子の形式、クライアントドライバのSCRAM対応の順。遅いなら統計情報の有無、実行計画の差分、I/O関連パラメータの順に見ます。

チェックサム不一致が最も多い

18のinitdbはデータチェックサムを既定で有効化します。16以前で既定値のまま作ったクラスタはチェックサム無効なので、設定が食い違うとpg_upgradeはold cluster does not use data checksums but the new one doesという趣旨のエラーで停止します。対処は、新クラスタを--no-data-checksums付きで作り直すか、旧クラスタを正常停止してpg_checksums --enableで有効化してから上げるかの2通り。後者は全データページを書き換えるため、所要時間はデータ量とストレージ帯域にほぼ比例します。選択の基準は停止許容時間です。

認証と統計情報

password_encryptionの既定値は14以降scram-sha-256です。古い設定ファイルを引き継いだ環境では、ロールにmd5形式の検証子が残る混在状態になりがちです。切り替えはサーバ側の既定設定、各ロールのパスワード再設定、pg_hba.confの書き換えという順番を守ってください。逆順にするとロックアウトします。

性能面では、18のpg_upgradeがオプティマイザ統計を引き継ぎます。ただしCREATE STATISTICSで作った拡張統計など引き継がれない種類もあるため、vacuumdb --all --analyze-in-stages --missing-stats-onlyで不足分だけ埋めるのが安全です。io_methodの既定値はworkerで、劣化が疑わしいときは一時的にsyncへ戻して再起動し、差を比較します。

なお既定値や制限値はマイナーリリースで調整されます。最終判断は使用中バージョンの公式ドキュメントで確認してください。

まず実行する確認クエリ

SELECT version();
SHOW server_version_num;   -- 18 系は 180000 以上
SHOW data_checksums;       -- on / off
SHOW password_encryption;
SHOW io_method;

完全版で扱っている内容

• pg_upgradeが失敗・中断するときの対処。--checkの実行例、チェックサム不一致に対する2通りのコマンド、loadable_libraries.txtの読み方、--copyと--linkで異なる必要容量とロールバック手順
• 停止中のクラスタから状態を読むpg_controldataの実行例と、Database cluster stateやData page checksum versionなど見るべき3行の判断基準
• 接続できないときの切り分け。パスワード検証子の形式を一覧するSQL、md5からscram-sha-256への4ステップ、pg_hba_file_rulesによる事前検査、libpqとJDBCの対応バージョン
• 遅いときの対処。列統計が入っていないテーブルを洗い出すSQL、pg_stat_ioとpg_aiosによる非同期I/Oの効果測定、io_workersとeffective_io_concurrencyの調整方針
• OS更新に伴うcollation version mismatchとREINDEXの必要性、md5認証の扱いに関するFAQ、移行前チェックリスト

PostgreSQL 18 移行でつまずく原因と対処法