PostgreSQLのメジャーバージョンアップを計画する｜最新バージョンとサポート終了日の確認から切り戻し手段の用意まで

この記事のポイント

・pg_upgrade --checkで事前に互換性問題を洗い出してから本番作業に入る
・pg_dumpallで論理バックアップを取得しておけば確実な切り戻しができる
・PostgreSQL 14は2026年11月でEOL。早めの移行計画が必要
・pg_upgradeはインプレース移行のため、pg_dump/restoreより大幅に速い

# バイナリのバージョン確認
$ psql -V
psql (PostgreSQL) 14.12

# 起動中クラスターのバージョン確認（psqlで接続後）
$ psql -U postgres -c "SELECT version();"
                                                     version
-----------------------------------------------------------------------------------------------------------------
 PostgreSQL 14.12 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 11.4.1 20230605 (Red Hat 11.4.1-2), 64-bit
(1 row)

# RHEL/Rocky Linux: インストール済みPostgreSQLパッケージを確認
$ rpm -qa | grep postgresql
postgresql14-14.12-1PGDG.rhel9.x86_64
postgresql14-server-14.12-1PGDG.rhel9.x86_64
postgresql14-libs-14.12-1PGDG.rhel9.x86_64

# データディレクトリの場所を確認
$ systemctl cat postgresql-14 | grep PGDATA
Environment=PGDATA=/var/lib/pgsql/14/data/

# インストール済み拡張機能を一覧表示
$ psql -U postgres -c "SELECT name, default_version FROM pg_available_extensions WHERE installed_version IS NOT NULL;"
        name        | default_version
--------------------+-----------------
 pg_stat_statements | 1.10
 plpgsql            | 1.0
(2 rows)

# 全データベースの論理バックアップ（postgresユーザーで実行）
$ pg_dumpall -U postgres > /backup/before_upgrade_$(date +%Y%m%d).sql

# バックアップサイズと内容を確認
$ ls -lh /backup/before_upgrade_*.sql
-rw-r--r-- 1 postgres postgres 1.2G Sep 05 10:23 /backup/before_upgrade_20260905.sql

$ head -5 /backup/before_upgrade_20260905.sql
--
-- PostgreSQL database cluster dump
--
-- Dumped from database version 14.12
-- Dumped by pg_dumpall version 14.12

# RHEL/Rocky Linux: PostgreSQL 17のパッケージをインストール
$ dnf install -y postgresql17-server postgresql17

# 新クラスターを初期化（旧クラスターと文字コードを揃える）
$ /usr/pgsql-17/bin/postgresql-17-setup initdb

# Ubuntu 24.04 LTS: PostgreSQL 17をインストール
# apt install -y postgresql-17
# Ubuntu はインストール時に自動でinitdbが実行される

# 新クラスターのサービスは起動しない（pg_upgradeが直接操作するため）

# postgresユーザーで実行（pg_upgradeはOSユーザーがpostgresである必要がある）
$ sudo -u postgres /usr/pgsql-17/bin/pg_upgrade   --old-datadir=/var/lib/pgsql/14/data   --new-datadir=/var/lib/pgsql/17/data   --old-bindir=/usr/pgsql-14/bin   --new-bindir=/usr/pgsql-17/bin   --check

Performing Consistency Checks
-----------------------------
Checking cluster versions                                   ok
Checking database user is the install user                  ok
Checking database connection settings                       ok
Checking for prepared transactions                          ok
Checking for system-defined composite types in user tables  ok
Checking for reg* data types in user tables                 ok
Checking for contrib/isn with bigint-passing mismatch       ok
Checking for tables WITH OIDS                               ok
Checking for presence of required libraries                 ok
Checking for running databases                              ok
Checking for postgresql.conf file                           ok
Checking for pg_hba.conf file                               ok

*Clusters are compatible*

# 旧クラスターを停止
$ systemctl stop postgresql-14

# 旧クラスターが停止していることを確認
$ systemctl is-active postgresql-14
inactive

# pg_upgradeを実行（--checkなし＝本番移行）
$ sudo -u postgres /usr/pgsql-17/bin/pg_upgrade   --old-datadir=/var/lib/pgsql/14/data   --new-datadir=/var/lib/pgsql/17/data   --old-bindir=/usr/pgsql-14/bin   --new-bindir=/usr/pgsql-17/bin

Performing Consistency Checks
-----------------------------
Checking cluster versions                                   ok
...

Performing Upgrade
------------------
Analyzing all rows in the new cluster                       ok
Freezing all rows on the new cluster                        ok
Deleting files from new pg_xact                             ok
Copying old pg_xact to new server                           ok
Setting oldest XID for new cluster                          ok
Setting next multixact ID and offset for new cluster        ok
Resetting WAL archives                                      ok
Setting frozenxid and minmxid counters in new cluster       ok
Restoring global objects in the new cluster                 ok
Restoring database schemas in the new cluster               ok
Copying user relation files                                 ok
Setting next OID for new cluster                            ok
Sync data directory to disk                                 ok
Creating script to analyze new cluster                      ok
Creating script to delete old cluster                       ok

Upgrade Complete
----------------
Optimizer statistics are not transferred by pg_upgrade so,
once you start the new server, consider running:
    ./analyze_new_cluster.sh

Running this script will delete the old cluster's data files:
    ./delete_old_cluster.sh

# 新クラスター（PostgreSQL 17）を起動
$ systemctl enable postgresql-17
$ systemctl start postgresql-17

# バージョンを確認
$ psql -U postgres -c "SELECT version();"
                                                     version
-----------------------------------------------------------------------------------------------------------------
 PostgreSQL 17.0 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 11.4.1 20230605 (Red Hat 11.4.1-2), 64-bit
(1 row)

# データベース一覧を確認
$ psql -U postgres -l
                                  List of databases
   Name    |  Owner   | Encoding |   Collate   |    Ctype    |   Access privileges
-----------+----------+----------+-------------+-------------+-----------------------
 myapp_db  | appuser  | UTF8     | en_US.UTF-8 | en_US.UTF-8 |
 postgres  | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |
 template0 | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =c/postgres
 template1 | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =c/postgres
(4 rows)

# 統計情報を再収集（pg_upgradeは統計を移行しないため必須）
$ sudo -u postgres ./analyze_new_cluster.sh

# アプリケーションの動作確認を終えた後に旧クラスターを削除
$ sudo -u postgres ./delete_old_cluster.sh

# 新クラスターを停止
$ systemctl stop postgresql-17

# 旧クラスターを起動（旧データディレクトリはそのまま残っている）
$ systemctl start postgresql-14
$ systemctl is-active postgresql-14
active

# バージョンを確認して旧クラスターに戻ったことを確認
$ psql -U postgres -c "SELECT version();"

# 新規クラスターにpg_dumpallバックアップを復元（最終手段）
$ psql -U postgres -f /backup/before_upgrade_20260905.sql postgres