pg_dumpとは、PostgreSQL のひとつのデータベースを、使用中でも一貫した状態のままファイルへ書き出す道具です。

  • pg_dump の形式(plain・custom・directory・tar)の違いと、復元に pg_restore と psql のどちらを使うか
  • よく使うオプション(-j・-n・-t・--schema-only・--data-only)と、メジャー版をまたぐ時の決まり
  • 当社が本番の控えで実際に踏んだ、版の食い違い・無音の待ち・DDL のロック待ちと、表を消す前の控えの取り方

当社は、本番の DB の控えと DB の変更を、CI の job と AIエージェント の席に任せて回しています。この頁は、PostgreSQL の公式の文書に書いてある pg_dump の定義と使い方を、その道で当社が実際に止まった記録と並べたものです。

pg_dump の形式:-Fp・-Fc・-Fd・-Ft

pg_dump は 1 回に 1 つのデータベースだけを書き出し、使用中の DB でも一貫した控えを作り、読む人・書く人を止めません(公式の文書)。出力の形は -F で選びます。

形式中身既定の圧縮並列の書き出し(-j)復元に使う道具
-Fp(plain・既定)
SQL の台本(文字のファイル)
しない
不可
psql
-Fc(custom)
pg_restore 用の控えのファイル 1 つ
する
不可
pg_restore
-Fd(directory)
表ごとにファイルを分けたディレクトリ
する(gzip)
可(この形式だけ)
pg_restore
-Ft(tar)
tar の形の控え
圧縮に対応しない
不可
pg_restore

出典: PostgreSQL 18 Documentation「pg_dump」https://www.postgresql.org/docs/current/app-pgdump.html (2026-11-11 に確認)。

tar の形式は、復元の時に表のデータの順を入れ替えられない、とも書かれています(公式の文書)。控えから一部だけ戻す・並列で戻す事を考えるなら、custom か directory が扱いやすい形です。

pg_dump の使い方:よく使うオプション

オプション何をするか(公式の文書)
-j njobs
njobs 個の表を同時に書き出す。directory 形式でだけ使える。DB へ njobs+1 本の接続を開くので max_connections に余裕が要る
-n pattern(--schema)
名前が合う schema と、その中の物だけを書き出す。付けなければ、system 以外の schema を全部書き出す
-t pattern(--table)
名前が合う表だけを書き出す。view・materialized view の定義も対象だが、その中身は書き出さない
-s(--schema-only)
物の定義(schema)だけを書き出し、データは書き出さない。--data-only とは併用できない
-a(--data-only)
データだけを書き出し、定義は書き出さない。表のデータ・large object・sequence の値が対象
--lock-wait-timeout
書き出しの初めに表の共有のロックを取る時、決めた時間で取れなければ待ち続けずに失敗する

出典: PostgreSQL 18 Documentation「pg_dump」https://www.postgresql.org/docs/current/app-pgdump.html (2026-11-11 に確認)。

形の例は次のとおりです(DB の名前とファイルの名前は置き換えて読んでください)。

# custom 形式で 1 ファイルに書き出す
pg_dump -Fc -f mydb.dump mydb

# directory 形式で並列に書き出す(開く接続は jobs の数+1 本・公式の文書)
pg_dump -Fd -j 4 -f mydb_dir mydb

# 定義だけを SQL の台本で書き出す
pg_dump --schema-only -f schema.sql mydb

接続プールの transaction モードを通して pg_dump を撃たない話は、PgBouncer(接続プール)の頁に書いています。

復元は pg_restore か psql で行う

pg_restore は、pg_dump が plain 以外の形式で作った控えから DB を戻す道具です。-d で接続先の DB を指せば直接その DB へ戻し、-j の並列の復元は custom と directory の形式でだけ使えます(公式の文書)。-l で控えの目次を出し、それを編集して -L に渡すと、載せた物だけをその順で戻せます(公式の文書)。plain の SQL の台本は psql に流して戻します(公式の文書)。

# custom の控えを別の DB へ戻す
pg_restore -d newdb mydb.dump

# plain の台本を戻す
psql -d newdb -f schema.sql

pg_dump は役割(role)と tablespace など、クラスタ全体に共通の物を保存しません。それらは pg_dumpall が書き出し、pg_dumpall の出力は psql に流す SQL の台本です(公式の文書)。

メジャー版をまたぐ時:pg_dump は自分より新しいサーバを読まない

公式の文書は、pg_dump は自分より古い版の PostgreSQL のサーバから書き出せる一方、自分のメジャー版より新しいサーバからは書き出せず、壊れた控えを作る危険を冒すより試みる事自体を断る、と書いています。また、pg_dump の出力を古いメジャー版のサーバへ載せられる保証は無い、とも書かれています(https://www.postgresql.org/docs/current/app-pgdump.html 2026-11-11 に確認)。つまり、pg_dump の版はサーバと同じか新しいものを使います。

本番の控えで当社が踏んだ記録

場面起きた事どうしたか日付
CI の backup の job
server version mismatch(サーバ 17.6/pg_dump 16.15)で失敗し、終了コード 1
backup の job に postgresql-client-17 を入れて通した
2026-09-20
本番の deploy の段の pg_dump
切れた接続で失敗を返さず、無音で待ち続ける型が在った
直すように起票した
2026-10-20
本番の DB に列を足す DDL
別に走っていた全体の pg_dump が全部の表に AccessShareLock を持ち、lock_timeout 3 秒で 2 回止まった
lock_timeout は伸ばさず、pg_dump が終わるのを待って撃ち直した
2026-10-03
表を消す変更
変更を当てる workflow が先に pg_dump を取り、age で暗号化して Cloud Storage に置く
表を消す直前にもう一度 pg_dump を取ってから当てた
2026-11-08

出典: 社の実測(日付は各行)。

server version mismatch:試し環境で通らない job を本番で 1 度通す

本番の控えを取る CI の backup の job で、pg_dump が server version mismatch を出して終了コード 1 で失敗しました。サーバは 17.6、job に入っていた pg_dump は 16.15 でした(社の実測 2026-09-20)。上の公式の決まりどおり、古い pg_dump が新しいサーバを断った形です。backup の job に postgresql-client-17 を入れて通しました(社の実測 2026-09-20)。

この job は試し環境では通らない作りで、本番で初めて走って落ちました。そこで、本番の CI の台本は、試し環境で通らない job(backup のような物)も 1 度は本番で通してから「済み」にする、と決めました(社の実測 2026-09-20)。

失敗を返さない pg_dump は門にならない

本番の deploy の段に、変更の前の控えとして pg_dump を入れていました。そこで、接続が切れた時に pg_dump が失敗を返さず、無音で待ち続ける型を見つけ、直すように起票しました(社の実測 2026-10-20)。

控えが取れなければ先へ進まない、という門のつもりで置いた段でも、失敗を返さなければ門になりません。止まったのか、まだ書いているのかが外から分からないからです。

DDL が pg_dump のロック待ちで lock_timeout に止まった

本番の DB に列を足す DDL を当てた時、別に走っていた全体の pg_dump の COPY(状態は idle in transaction)が全部の表に AccessShareLock を持っていて、DDL は lock_timeout 3 秒で 2 回止まりました(社の実測 2026-10-03)。lock_timeout は伸ばさず、pg_dump が終わってロックが解けるのを待ってから撃ち直しました(社の実測 2026-10-03)。別の日にも同じ形で 3 回 lock_timeout に止まり、4 回目で COMMIT まで通りました(社の実測 2026-10-06)。

公式の文書も、並列の書き出しの間に別の接続が表の排他のロックを求めると、その要求は共有のロックが解けるまで待ちの列に入り、その表への他の操作も待たされる、と書いています(https://www.postgresql.org/docs/current/app-pgdump.html 2026-11-11 に確認)。lock_timeout を伸ばすと、DDL が待つ間に後ろの読み書きまで並んでしまうので、当社は短いまま撃ち直す側を選んでいます。DB の変更の当て方は prisma migrate の頁にまとめています。

表を消す前に、暗号化した pg_dump を Cloud Storage に置く

表を消す変更では、変更を当てる仕組み(GitHub Actions の workflow)が先に pg_dump を取り、age で暗号化して Cloud Storage に置きます。大きさは 1,177,074,712 バイトで、保持は 3 日でした(社の実測 2026-11-08)。別の DB では 2,472,274,424 バイト(社の実測 2026-11-08)、別の回では 2.54GB でした(社の実測 2026-11-09)。

そのうえで、表を消す直前にもう一度 pg_dump を取ってから当てました(社の実測 2026-11-08)。先に取った控えと消す瞬間の間にも書き込みは入るからです。

表を消した後に戻す道は、Cloud Storage の pg_dump だけになることがあります。保持の日数を過ぎれば控えは消えるので、表を消す前に、その保持の日数を先に確かめます(社の実測 2026-11-08)。

よくある質問

pg_dump と pg_dumpall の違いは?

pg_dump は 1 つのデータベースだけを書き出し、役割や tablespace などクラスタ全体の物は保存しません。pg_dumpall はクラスタの全部のデータベースと、それらの共通の物を 1 つの SQL の台本に書き出します(PostgreSQL 公式の文書)。

pg_dump の形式はどれを選べばいい?

SQL の台本として読みたいなら plain、pg_restore で一部だけ・並列で戻したいなら custom か directory です。書き出しを並列(-j)にできるのは directory だけです(PostgreSQL 公式の文書)。

pg_dump で server version mismatch が出たらどうする?

pg_dump は自分のメジャー版より新しいサーバからは書き出しを断ります(PostgreSQL 公式の文書)。サーバと同じか新しい版の pg_dump を入れます。当社はサーバ 17.6 に pg_dump 16.15 で当たり、postgresql-client-17 を入れて通しました(社の実測 2026-09-20)。

pg_dump の最中に DDL を当ててもいい?

pg_dump が表の共有のロックを持っている間、排他のロックを求める DDL は待たされます。当社は lock_timeout 3 秒で 2 回止まり、pg_dump が終わってから撃ち直しました(社の実測 2026-10-03)。

出典

  1. PostgreSQL 18 Documentation「pg_dump」https://www.postgresql.org/docs/current/app-pgdump.html (2026-11-11 に確認)
  2. PostgreSQL 18 Documentation「pg_restore」https://www.postgresql.org/docs/current/app-pgrestore.html (2026-11-11 に確認)
  3. PostgreSQL 18 Documentation「pg_dumpall」https://www.postgresql.org/docs/current/app-pg-dumpall.html (2026-11-11 に確認)
  4. 社の実測 2026-09-20・2026-10-03・2026-10-06・2026-10-20・2026-11-08・2026-11-09