はじめに (対象読者・この記事でわかること)

この記事は、PostgreSQL を本番環境や開発環境で利用しているエンジニア、DB 管理者、もしくは pgAdmin の GUI からデータベースのバックアップ・レストアを行おうとして失敗した経験のある方を対象としています。特に以下のような状況に心当たりがある方に有益です。

  • pgAdmin の「Backup」ボタンは正常に動作するが、「Restore」時にエラーが出て処理が止まる
  • 「File not found」や「permission denied」などのメッセージが表示されるが原因が分からない
  • CLI（pg_restore/psql）を併用した方が早く解決できるか知りたい

本記事を読むことで、pgAdmin でリストアが失敗する典型的な原因 3 種類と、それぞれの対処手順、さらにコマンドラインでの代替リストア方法が理解でき、実務ですぐにトラブルを解決できるようになります。執筆のきっかけは、社内プロジェクトでバックアップファイルが壊れていたことが原因でリリースが遅延した経験です。その教訓を共有し、同じ失敗を繰り返さないための指針を提供します。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。

  • PostgreSQL の基本的な概念（データベース、スキーマ、テーブル）
  • pgAdmin 3 以上のインストールと基本操作（接続、クエリツールの使用）
  • コマンドライン（ターミナル）での基本操作と psql、pg_restore の基本的な使い方

pgAdmin でリストアが失敗する主な原因と概要

pgAdmin は GUI で手軽にバックアップ・レストアができる便利なツールですが、内部的には pg_dump と pg_restore（もしくは psql）を呼び出しています。そのため、以下のような環境依存や設定ミスがあるとリストアが失敗します。

原因 具体例 発生しやすいシチュエーション
1. パス/権限の問題 「File not found」や「Permission denied」 バックアップファイルが別ユーザーのホームディレクトリにある、または pgAdmin が実行ユーザー (例: postgres ユーザー) の権限でアクセスできない
2. バックアップ形式の不一致 「Restore failed: error while processing data: invalid input syntax」 pg_dump で取得した形式 (カスタム形式 vs プレーンテキスト) がリストア時に指定した形式と合わない
3. バージョン差異 「ERROR: could not connect to server: server closed the connection unexpectedly」 バックアップが PostgreSQL 13 で取得され、リストア先が PostgreSQL 12 もしくは 14 などバージョンが異なる場合

これらの原因は、pgAdmin の GUI だけではエラーメッセージが簡潔すぎて原因特定が難しいことが多いです。そこで次章では、それぞれの原因に対する具体的な対処手順を詳しく解説します。

具体的な手順と実装方法

ステップ 1：バックアップファイルの場所と権限を確認

  1. ファイルの所在を確認
    pgAdmin の「Restore」画面で指定したパスが実際にサーバー上に存在するか、ターミナルで ls -l <path> を実行して確認します。
    bash ls -l /var/lib/pgsql/backups/mydb.backup

  2. 所有者と権限の調整
    pgAdmin は通常、サーバー側の postgres ユーザー権限で動作します。バックアップファイルが root や別ユーザー所有の場合は、chown と chmod で権限を変更します。
    bash sudo chown postgres:postgres /var/lib/pgsql/backups/mydb.backup sudo chmod 600 /var/lib/pgsql/backups/mydb.backup

  3. pgAdmin の「File」フィールドで絶対パスを使用
    相対パスは pgAdmin の作業ディレクトリに依存するため、絶対パスを必ず指定しましょう。

ポイント：権限エラーは GUI では「permission denied」のみ表示されることが多く、実際のファイル権限を確認することで即解決できます。

ステップ 2：バックアップ形式の整合性を確認

pgAdmin の「Backup」ダイアログでは「Format」(Plain, Custom, Tar, Directory) を選べます。リストア時に同じ形式であることが必須です。

  1. 形式の確認
    バックアップファイルの拡張子だけでは判別できないため、file コマンドで中身を確認します。
    bash file /var/lib/pgsql/backups/mydb.backup # 出力例: PostgreSQL custom archive format

  2. pgAdmin のリストア設定
    - 「Format」欄で Custom が選択されているか確認。
    - 「Restore options」タブで「Only data」や「Only schema」など、必要なオプションだけを有効にする。

  3. CLI での検証（オプション）
    bash pg_restore -l /var/lib/pgsql/backups/mydb.backup これでバックアップに含まれるオブジェクトリストが表示され、正常に読めることを確認します。

ポイント：カスタム形式のバックアップは pg_restore が必要です。Plain 形式（SQL スクリプト）は psql でリストアできます。形式が合っていないと「invalid input syntax」エラーが即発生します。

ステップ 3：バージョン互換性のチェックと回避策

PostgreSQL のメジャーバージョン間では、pg_dump/pg_restore の互換性が保証されていますが、一部機能（例えば特定拡張機能やパラメータ）はバージョン差でエラーになることがあります。

  1. サーバーバージョンの確認
    bash psql -U postgres -c "SELECT version();"

  2. バックアップ取得時のバージョン情報を取得
    カスタム形式のバックアップはヘッダーにバージョンが埋め込まれています。pg_restore -v で確認できます。
    bash pg_restore -v /var/lib/pgsql/backups/mydb.backup | grep "PostgreSQL"

  3. 互換性が無い場合の対策
    - ダウングレードリストア: pg_dump の --format=plain と --no-owner オプションで SQL スクリプトを取得し、古いバージョンの psql で実行。
    - 拡張機能の除外: pg_restore --exclude-extension=postgis などで問題の拡張だけ除外してリストア。

ハマった点やエラー解決

エラーコード 内容 原因 解決策
ERROR: permission denied for schema public スキーマに対する権限不足 リストア時に postgres ユーザーが public スキーマに書き込めない GRANT ALL ON SCHEMA public TO postgres; を実行
pg_restore: error: could not open input file "mydb.backup": No such file or directory ファイルパスが見つからない GUI で相対パス指定、サーバ側とローカルが混同 絶対パスか、サーバ側にファイルを配置してから指定
ERROR: syntax error at or near "INSERT" プレーンテキストの SQL が途中で切れている バックアップが途中で中断、ファイルが破損 pg_dump を再取得、もしくは pg_restore -l でリスト確認

具体的な解決例：permission denied のケース

  1. エラーメッセージを確認し、対象スキーマを特定。
  2. psql で権限付与コマンドを実行。
    sql \c mydb GRANT ALL PRIVILEGES ON SCHEMA public TO postgres;
  3. 再度 pgAdmin の「Restore」ボタンを押すと、エラーが解消され正常にリストア完了。

コマンドラインでの代替リストア手順（最終手段）

pgAdmin がどうしても動作しない場合、以下のコマンドで直接リストアできます。

カスタム形式（.backup）の場合

Bash

pg_restore -h localhost -U postgres -d mydb -v /var/lib/pgsql/backups/mydb.backup
  • -v は詳細モードで進行状況を出力
  • -c オプションで既存オブジェクトを削除してからリストア可能
    bash pg_restore -c -d mydb /path/to/backup.backup

プレーンテキスト（SQL スクリプト）の場合

Bash

psql -h localhost -U postgres -d mydb -f /var/lib/pgsql/backups/mydb.sql

これらのコマンドは、エラーメッセージがそのままターミナルに出力されるため、原因特定が格段に楽になります。

まとめ

本記事では、pgAdmin でバックアップからのレストアが失敗する典型的な原因と、その具体的な対処手順を解説しました。

  • 原因1：ファイルパス・権限問題 → 絶対パス指定と所有者・権限の調整で解決
  • 原因2：バックアップ形式の不一致 → file コマンドで形式確認、pgAdmin の設定と pg_restore のオプションを合わせる
  • 原因3：バージョン互換性 → バージョン情報の確認と、必要に応じたダウングレードリストアや拡張除外で回避

これらを実践すれば、pgAdmin の GUI だけで完結できないリストア失敗も、コマンドライン併用で迅速に解決できるようになります。今後は、自動化スクリプトでバックアップ・リストアを一元管理する方法や、クラウド環境での pgAdmin のベストプラクティスについても記事化予定です。

参考資料