pg_dumpとpsqlの互換性エラー：transaction_timeout未認識問題の解決法

問題概要

PostgreSQL環境で以下の操作を行うと発生するエラーについて説明します：

1. pg_dumpでデータベーススキーマをエクスポート：

pg_dump --schema-only 'postgresql://.../db1' > schema.sql

2. 出力ファイルschema.sqlを別データベースにインポート：

psql 'postgresql://.../db2' < schema.sql

3. 以下のエラーが発生：

ERROR:  unrecognized configuration parameter "transaction_timeout"

エラーの原因はダンプファイル内のこの行です：

SET transaction_timeout = 0;

具体的な環境

• PostgreSQLサーバー: 15.7（Dockerコンテナ）
• クライアントツール: psql 17.0, pg_dump 17.0
• OS: Ubuntu 22.04

なぜこれが問題なのか

pg_dumpが生成するSQLにpsqlやPostgreSQLサーバーが認識できないパラメータが含まれており、スキーマ移行プロセスが中断されます。単純なテーブル/インデックス/制約の移行だけが必要な場合にも発生します。

原因の根本分析

公式ドキュメント（pg_dump）に明確に記載されている動作です：

"pg_dumpの出力は、新しいバージョンのPostgreSQLへのデータ転送を目的としています。 ダンプファイルを旧バージョンのサーバーにロードすることは保証されていません（ダンプ元がその旧バージョンであっても同様です）"

主な要因は以下の通り：

1. バージョン不一致

   • pg_dump 17.0は最新機能に対応しているが
   • PostgreSQLサーバー15.7はtransaction_timeoutパラメータを認識しない

2. 上位互換限定の設計

   • pg_dumpは新しいバージョンへの移行を想計
   • 旧バージョンへのダンプロードは公式にサポート外

バージョン管理の重要性

pg_dumpツールのバージョンは、対象PostgreSQLサーバーのメジャーバージョンと一致させる必要があります。この整合性がないと互換性問題が高頻度で発生します。

解決方法：安全なスキーマエクスポート手法

方法1：--no-psqlオプションを使用（推奨）

pg_dump実行時にSET文を除外：

pg_dump --schema-only --no-psql 'postgresql://.../db1' > clean_schema.sql

このオプションの効果

• SETステートメントやセッション設定を完全排除
• 純粋なDDL（テーブル/インデックス/制約）のみ出力
• バージョン違い環境でも高い互換性を確保

方法2：ダンプファイルの前処理

既に生成されたschema.sqlを編集する場合：

# transaction_timeout設定行を削除
sed -i '/transaction_timeout/d' schema.sql

# またはすべてのSET文を削除
sed -i '/^SET /d' schema.sql

方法3：バージョン整合性の確保（根本解決）

ツールとサーバーのバージョンを一致させる：

# PostgreSQLサーバーと同じバージョンのpg_dumpを利用
docker run --rm -v $(pwd):/data postgres:15.7-bullseye \
  pg_dump --host 172.17.0.1 --schema-only -U user db1 > schema.sql

バージョン確認コマンド

# サーバーバージョン確認
psql --command="SELECT version();"

# pg_dumpバージョン確認
pg_dump --version

よくある質問

他のパラメータでも同様のエラーが出る場合は？

lock_timeout、idle_in_transaction_session_timeoutなど、バージョンで追加されたパラメータで同様の問題が発生します。対策は全て同じです：

1. --no-psqlオプションを使用
2. 該当SET文を手動削除
3. バージョン整合を取る

本番環境で安全に適用するには？

1. テスト環境で空のDBにインポート試験
2. \i schema.sqlでなく--single-transaction使用：

psql --single-transaction -v ON_ERROR_STOP=1 'postgresql://.../db2' < clean_schema.sql

3. インポート後に\dでオブジェクト一覧を検証

まとめ：ベストプラクティス

課題	解決策	効果
互換性エラー	--no-psqlオプション使用	セッション設定の排除
バージョン差異	ツールとサーバーのバージョン一致	根本的な互換性確保
大規模スキーマ移行	--single-transaction利用	アトミックな適用保証

最終的な推奨ワークフロー：

# 1. バージョン確認
psql --version && pg_dump --version

# 2. 安全なダンプ取得（新規の場合）
pg_dump --schema-only --no-psql -U ユーザー名 db1 > schema.sql

# 3. 既存ファイルの修復（既に生成済みの場合）
sed -i '/^SET /d' schema.sql

# 4. トランザクション保証で適用
psql --single-transaction -v ON_ERROR_STOP=1 -U ユーザー名 db2 < schema.sql

::: success 予防的対応 定期メンテナンスタスクでは、pg_dumpツールのバージョンアップをサーバーアップグレードと同期させることで、将来の互換性問題を未然防止できます。 :::