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)。
出典
- PostgreSQL 18 Documentation「pg_dump」https://www.postgresql.org/docs/current/app-pgdump.html (2026-11-11 に確認)
- PostgreSQL 18 Documentation「pg_restore」https://www.postgresql.org/docs/current/app-pgrestore.html (2026-11-11 に確認)
- PostgreSQL 18 Documentation「pg_dumpall」https://www.postgresql.org/docs/current/app-pg-dumpall.html (2026-11-11 に確認)
- 社の実測 2026-09-20・2026-10-03・2026-10-06・2026-10-20・2026-11-08・2026-11-09