概要
他所からもらったdumpファイルが、どのPostgreSQLバージョン（正確には、pg_dumpバージョン）で採られたものか分からないことって、あるでしょう？（あるんだよ）
手元のdumpファイルがリストアできないときに、「これ、聞いてたのより新しいバージョンのPg_dumpでバックアップしたやつですよね！？」って言うための根拠づくりをやっていくナレッジ。バージョン不一致時の対処方法も、軽めに選択肢だけ整理します。
| 項目 | 内容 |
|---|---|
| 取り扱う内容 | • dumpファイルのバージョン情報の確認方法 • バージョンの互換性に関する制約 • バージョン不一致時の対処方法 |
| 想定読者 | • PostgreSQLのバックアップ・リストア作業を行う人 • 外部から受領したdumpファイルを取り扱う人 • リストアを試みたが unsupported versionと表示されて困ってる人 |
| ゴール | • dumpファイルのバージョン情報を容易に確認できるようになる • dumpファイルバージョンの互換性問題を理解する |
前提知識：dumpファイルのバックアップとリストアにおける基本ルール
- 新しいバージョンの
pg_dumpで作成したダンプファイルは、古いバージョンのpg_restoreでは読み込めない - 古いバージョンの
pg_dumpで作成したダンプファイルは、新しいバージョンのpg_restoreで読み込むことができる- ただしv9.2より古いpg_dumpを使った場合は、保証対象外
これは、PostgreSQL v15 公式にも記載されています。
pg_dumpの出力はpg_dumpのバージョンより新しいバージョンのPostgreSQLデータベースへロード可能と想定できるようになっています。 また、pg_dumpは自身より古いバージョンのPostgreSQLデータベースを読み取ることもできます。 （現在はバージョン9.2までのサーバをサポートします。） しかし、pg_dumpはそれ自身のメジャーバージョンより新しいPostgreSQLサーバのダンプを取ることはできません。
また、上記のルールはカスタム形式で取得したdumpファイルに適用され、プレーンテキスト形式のdumpファイルには適用されません。
dumpファイルのメタ情報を参照する
手元のdumpファイルに対して、以下のコマンドでメタ情報を参照できます。dump取得先となったPostgreSQLバージョンとともに、dumpを生成したクライアントのpg_dumpバージョンも表示されます。
# dumpファイルの持っている情報を一部だけ参照
pg_restore -l backup.dump | head -n 12
結果：
; Archive created at 2024-10-30 19:19:43 UTC
; dbname: testdb
; TOC Entries: 4
; Compression: -1
; Dump Version: 1.14-0
; Format: CUSTOM
; Integer: 4 bytes
; Offset: 8 bytes
; Dumped from database version: 15.8 (Debian 15.8-1.pgdg120+1)
; Dumped by pg_dump version: 15.8 (Debian 15.8-1.pgdg120+1)
上記から読み取れる情報：
-
データベースバージョン:
Dumped from database versionの行で、dump取得元のPostgreSQLバージョンが分かる -
pg_dumpバージョン:
Dumped by pg_dump versionの行で、dumpを生成したクライアントのpg_dumpバージョンが分かる - バージョンの不一致: PostgreSQL v15に付属のpg_dumpでPostgreSQL v12のdumpをとった場合など、データベースバージョンとpg_dumpバージョンが異なることがある。これは正常な動作
- その他の情報: 作成日時、データベース名、ダンプフォーマット（この例では CUSTOM）なども確認できる
リストア環境のpg_restoreより新しいpg_dumpで作成されたファイルはリストアできない
dumpファイルがpg_restoreを実行しているクライアントよりも新しいpg_dumpバージョンで作られた物である場合、メタ情報の参照ができません。このとき、以下のようなメッセージが出ます。
# v15 pg_dumpで作成したファイルを、PostgreSQL v10のpg_restoreで`pg_restore -l`したときのリアクション
pg_restore: [archiver] unsupported version (1.14) in file header
このエラーメッセージは、dumpファイルのバージョンがリストア環境のpg_restoreバージョンと互換性がないことを示しています。
pg_dumpとpg_restoreのバージョンを確認する
前項のメッセージから、dumpをくれた相手がリストア環境より新しいバージョンのdb_dumpを使っていることが分かりました。確証を得るために、自分の環境と相手の環境とで、以下のコマンドを実行して、pg_dumpのバージョンに差分があることを確認できます。
# pg_restoreはpg_dumpと同じバージョンになるはずだが、念のため。
# 以下、PostgreSQL v10で実行したリアクション
pg_dump --version & pg_restore --version
# pg_dump (PostgreSQL) 10.21 (Debian 10.21-1.pgdg90+1)
# pg_restore (PostgreSQL) 10.21 (Debian 10.21-1.pgdg90+1)
バージョンの不一致を解決する
クライアントツール（pg_dump/pg_restore）のバージョンを合わせる
バージョンの不一致が確認された場合、正常にリストアするためにpg_dumpとpg_restoreのバージョンを合わせる必要があります。データベース本体のバージョンを変更する必要はありません。クライアントツール（pg_dumpやpg_restore）のバージョンを合わせればOKです。
以下の2つの選択肢から、リーダーやお客さんと相談して対応します。特に本番環境が絡む場合、承認なしに新しいツールを導入できないことがあるので、ちゃんと相談してください。
| 対応方針 | 対応内容 |
|---|---|
| dumpファイル作成環境で対応 | • 古いバージョンのpg_dumpを導入 • dumpファイルを作り直す |
| リストア環境で対応 | • 新しいバージョンのpg_restoreを導入 • 既存のdumpファイルをそのまま使用 |
クライアントツールの入手方法
PostgreSQLの完全インストール
開発環境など、自由にツールをインストールできる場合に採用してよさそう。該当バージョンのPostgreSQLをインストールすることで、必要なクライアントツールも一緒に入手できます。
バイナリのダウンロード
PostgreSQL公式のzipアーカイブ配布サイトから、zip形式のアーカイブをダウンロードします。アーカイブからpg_dumpおよびpg_restoreの実行ファイルを取り出して使用します。
付属のライブラリファイルも一緒に取り出さないといけないかも。まだ試したことがないので、動かされたらまた教えてください（すみません！）
既存のクライアントの利用
必要なバージョンのクライアントが、既にPCへインストールされている可能性があります。以下の点を確認します。
- コマンドラインで実行している場合、正しいバージョンのPostgreSQLクライアントがあるディレクトリにパスが通っているか確認する
- pgAdminやDBeaverなどの外部ツールを使用している場合、設定で使用するクライアントのバージョンを指定できる（はず）