pg_dump [-a | -s] [-b] [-c] [-C] [-d | -D] [-f file] [-F format] [-i] [-n | -N] [-o] [-O] [-R] [-S] [-t table] [-v] [-x] [-X keyword] [-Z 0...9] [-h host] [-p port] [-U username] [-W] dbname
pg_dump は PostgreSQL データベースを、スクリプトファイル、もしくは、アーカイブファイルに保存するユーティリティです。このスクリプトファイルはプレインテキスト書式であり、保存時の状態のデータベースを再作成するために必要な SQL コマンドが書き込まれています。これは、他のマシンや他のアーキテクチャ上でさえも、データベースを再構築するのに使うことができます。また、少し編集すれば他の RDMS 製品上でもデータベースを再構築することができます。更に、pg_restore を使用してデータベースを再構築することを目的とした、アーカイブファイル書式もあります。このファイルを使用して、pg_restore はリストア対象を選択することも、リストアするアイテムの並び替えも行なうことができます。アーカイブファイルもまた、アーキテクチャを越えて移植できるように設計されています。
pg_dump は全てのユーザ定義型、関数、テーブル、インデックス、集約、演算子を再作成するために必要となる情報を保存します。更に、エディタに読み込ませることもできるだけではなく、すぐにデータベースにコピーすることができるように全てのデータはテキスト書式でコピーされます
pg_dump はデータベースの中身をある PostgreSQL インストレーションから別のものへ移動するのに便利です。
アーカイブファイル書式の1つを使用し、pg_restore と組み合わせて使用する場合、pg_dump は柔軟な貯蔵・転送機構を提供します。pg_dump を使用してデータベース全体をバックアップし、pg_restore を使用して、アーカイブの内容を検査したり、データベースの一部を選択してリストアしたりすることができます。もっとも柔軟な出力ファイル書式は、"custom" 書式 (-Fc)です。この書式は保存された項目の選択や並び換えを行うことができ、また、デフォルトで圧縮されています。 tar 書式 (-Ft) は圧縮されず、また、ロードの際に並び替えを行なうことができません。しかし、他の点では、かなり柔軟なものです。その上、tar などの他のツールと組み合わせて操作することができます。
pg_dump を実行中は、(標準エラーに出力される)警告、特に後述の制限に関する警告が出力されていないか確認して下さい。
pg_dumpは、そのデータベースが並行して使用されていたとしても一貫性のあるバックアップを作成します。 pg_dump は他のユーザによる対象データベースへのアクセスを(読み込みも書き込みも)ブロックしません。
pg_dump は下記のコマンドライン引数を受けつけます。(長いオプション形式は限られたプラットフォームでしか使うことができません。)
抽出されるべきデータベースの名前を指定します。
データのみをダンプし、スキーマ(定義)はしません。
このオプションはプレインテキスト書式の場合にのみ有用です。他の書式では、pg_restore を呼び出す時にこのオプションを使用する可能性があります。
ラージオブジェクトをダンプに含めます。
データベースオブジェクトを作成する前に掃除(削除)するためのコマンドを書き出します。
このオプションはプレインテキスト書式の場合にのみ有用です。他の書式では、pg_restore を呼び出す時にこのオプションを指定する可能性があります。
データベース自身を作成し、作成したデータベースに接続するコマンドを始めに出力します。(この形のスクリプトを使用する場合、スクリプトを実行させる前にどのデータベースに接続すればいいかという問題を考える必要がなくなります。)
このオプションはプレインテキスト書式の場合にのみ有用です。他の書式では、pg_restore を呼び出す時にこのオプションを指定する可能性があります。
データを INSERT コマンドとして(COPYではなく)ダンプします。これはリストアをとても遅くします。しかし、生成されたアーカイブはより他の RDBMS への移植性が高くなります。
データを明示的に列名を付けた INSERT コマンド(INSERT INTO table (column, ...) VALUES ...)としてダンプします。これはリストアをとても遅くします。しかし、列の順番を変更する場合には必要なものです。
出力を指定されたファイルに送ります。省略時は標準出力が使用されます。
出力書式を選択します。format は以下のいずれかです。
プレインテキストの SQL スクリプトファイルを出力します(デフォルト)
pg_restore への入力に適した tar アーカイブを出力します。このアーカイブ書式の使用は、データベースがリストアされる時のスキーマ要素の削除もしくは並び替えを可能にします。どのデータがリストア時にリロードされるかを制限することも可能です。
pg_restore への入力に適したカスタムアーカイブを出力します。これは、もっとも柔軟な書式であり、スキーマ要素だけでなくデータロードの並び替えも可能です。この書式もデフォルトで圧縮されます。
pg_dump とデータベースサーバのバージョンの不一致を無視します。pg_dumpはシステムカタログについて多くを知っているので、どのバージョンの pg_dump も対応するデータベースサーバのリリースでのみ作動するように意図されています。もしバージョンチェックを無効にする必要がある場合にこのオプションを使います。(もしpg_dumpが失敗したとしても、警告されなかったとは言えませんよ。)
完全に必要でない限り、識別子を囲う二重引用符を抑えます。これは、もし識別子に予約語が使われていると、ダンプされたデータをロードするのに問題が発生するかもしれません。これはバージョン6.4 以前では pg_dump のデフォルト動作でした。
識別子を囲う二重引用符を含みます。これはデフォルトです。
それぞれのテーブルのオブジェクト識別子 (OIDs)をダンプします。アプリケーションでOID 列を(外部キー制約内などの)どこかで使用している場合は、このオプションを使用して下さい。その他の場合は、このオプションは使用しないで下さい。
オブジェクトの所有権を元のデータベースに一致させるためのコマンドを出力しません。典型的には、pg_dump はスキーマ要素の所有権を設定するために(psql特有の) \connect 文を発行します。 -R と -X use-set-session-authorization を参照して下さい。 -O はデータベースへの再接続を全て抑制するものではなく、ただ、所有権調整のために排他的に使用されるものであることに注意して下さい。
このオプションはプレインテキスト書式の場合にのみ有用です。他の書式では、pg_restore を呼び出す時にこのオプションを指定する可能性があります。
pg_dump が、リストア中にデータベースへの再接続を必要とするようなスクリプトを出力することを禁止します。普通のリストア用スクリプトでは、通常は、異なるユーザで何回も接続しなおして、オブジェクトの元々の所有権を設定します。このオプションはどちらかというとナマクラ道具です。これによって -X use-set-session-authorization を使用しない 限り pg_dump は所有権情報を失ってしまうからです。
データベースへのアクセスに(パスワードなど)手作業による操作が必要な場合も、リストア中の再接続を望まない理由の1つとなります。
このオプションはプレインテキスト書式の場合にのみ有用です。他の書式では、pg_restore を呼び出す時にこのオプションを指定する可能性があります。
スキーマ(定義)のみをダンプし、データはしません。
トリガの無効化やスキーマ要素の所有権変更などを行なう場合、 pg_dump によって生成されるスクリプトやアーカイブはスーパユーザ権限をもつことが必要です。このオプションはこういった場合に使用されるユーザ名を指定します。
table のデータのみをダンプします。
冗長モードを指定します。
アクセス権限 (grant/revoke コマンド)のダンプを抑制します。
通常、(プレインテキストモードの)pg_dump によって生成されたスクリプトは、(例えば、オブジェクトの所有権の設定など)現在のデータベースユーザを変更する必要がある場合に psql \connect コマンドを使用します。実際このコマンドは新規の接続を開きます。この際に(パスワードなどの)手作業の操作が必要になる可能性があります。 -X use-set-session-authorization オプションを使用すると、pg_dump は SET SESSION AUTHORIZATION コマンドを出力するようになります。これは同じ効果が得られますが、生成されたスクリプトをリストアするユーザはデータベーススーパユーザでなければなりません。このオプションは -R オプションを無効にします。
\connect が psql でのみ動作するのに対して、 SET SESSION AUTHORIZATION は標準の SQL コマンドですので、このオプションは理論的には出力スクリプトの移植性も向上させます。
このオプションはプレインテキスト書式の場合にのみ有用です。他の書式では、pg_restore を呼び出す時にこのオプションを指定する可能性があります。
圧縮をサポートするアーカイブ書式で使用する圧縮レベルを指定します(現時点では、カスタムアーカイブ書式のみが圧縮をサポートしています)。
pg_dump は更に、下記のコマンドライン引数を接続パラメータとして受けつけます。
サーバが稼働しているマシンのホスト名を指定します。ホスト名がスラッシュから始まる場合、Unix ドメインソケット用のディレクトリとして使用されます。
サーバが接続を監視するインターネット TCP/IP ポートもしくはUnix ドメインソケットの拡張子を指定します。ポート番号のデフォルトは 5432、もしくは、(設定されている場合)環境変数 PGPORT の値となります。
指定したユーザで接続します。
パスワードを強制的に促します。これは、パスワード認証が必要なサーバの場合自動的に行なわれます。
Connection to database 'template1' failed.
connectDBStart() -- connect() failed: No such file or directory
Is the postmaster running locally
and accepting connections on Unix socket '/tmp/.s.PGSQL.5432'?
pg_dump は、指定したホストとポート上の postmaster プロセスに接続できませんでした。このメッセージが現れた場合、postmaster が正しいホストで稼働していること、および、正しいポートを指定していることを確認して下さい。
Note: pg_dump は内部で SELECT 文を実行します。pg_dump の実行に問題が発生した場合、例えば psql を使用して、データベースから情報を選択できるかどうか確認して下さい。
インストレーションにおいて template1 データベースに対しローカルな変更を行っている場合、pg_dump の出力を、本当に空のデータベースにリストアする時には注意して下さい。おそらく追加したオブジェクトの重複定義によるエラーが発生することになります。ローカルな追加を行うことなく、空のデータベースを作成するには、template1 からではなく template0 からコピーして下さい。以下に例を示します。
CREATE DATABASE foo WITH TEMPLATE = template0;
pg_dump にはいくつかの制限があります
1つのテーブルのダンプ、もしくは、プレインテキストでのダンプの場合、 pg_dump はラージオブジェクトを取り扱いません。ラージオブジェクトは、バイナリアーカイブ書式の1つを使用して全体としてダンプされなければなりません。
データのみのダンプを行なう場合、pg_dump はデータを挿入する前にユーザテーブルにトリガを無効とするための問い合わせを発し、そしてデータが挿入されるとそれらをまた可能にするための問い合わせを発します。もしリストアが途中で中止された場合、システムカタログは間違った状態で残されるかもしれません。