pg_dump は PostgreSQL データベースを、スクリプトファイル、もしくは、アーカイブファイルに保存するユーティリティです。このスクリプトファイルはプレインテキスト形式であり、保存時の状態のデータベースを再構成するために必要な SQL コマンドが書き込まれています。 これらのスクリプトをリストアするには psql を使用します。 これらのスクリプトは、他のマシンや他のアーキテクチャ上でさえも、データベースを再構築するために使うことができます。また、少し編集すれば他の SQL データベース製品上でもデータベースを再構築することができます。
更に、pg_restore を使用してデータベースを再構築することを目的とした、アーカイブファイル形式もあります。このファイルを使用して、pg_restore はリストア対象を選択することも、リストアするアイテムの並び替えも行なうことができます。アーカイブファイルもまた、アーキテクチャを越えて移植できるように設計されています。
pg_dump は全てのユーザ定義型、関数、テーブル、インデックス、集約、演算子を再作成するために必要となる情報を保存します。更に、エディタに読み込ませることもできるだけではなく、すぐにデータベースにコピーすることができるように全てのデータはテキスト形式でコピーされます。
アーカイブファイル形式の1つを使用し、pg_restore と組み合わせて使用する場合、pg_dump は柔軟なアーカイブ / 転送機構を提供します。pg_dump を使用してデータベース全体をバックアップし、pg_restore を使用して、アーカイブの内容を検査したり、データベースの一部を選択してリストアしたりすることができます。もっとも柔軟な出力ファイル形式は、"custom" 形式 (-Fc) です。この形式は、保存された項目の選択や並び換えを行うことができ、また、デフォルトで圧縮されています。tar 形式 (-Ft) は圧縮されず、また、ロードの際に並び替えを行なうことができません。しかし、他の点では、かなり柔軟なものです。その上、tar などの他のツールを使用して操作することができます。
pg_dump を実行中は、(標準エラーに出力される) 警告、特に後述の制限に関する警告が出力されていないか確認して下さい。
pg_dump は、そのデータベースが並行して使用されていたとしても一貫性のあるバックアップを作成します。pg_dump は他のユーザによる対象データベースへのアクセスを (読み込みも書き込みも) ブロックしません。
以下のコマンドラインオプションを使用して出力形式を制御することができます。
ダンプ (抽出) するデータベースの名前を指定します。 指定されていない場合は、環境変数 PGDATA が使われます。 この変数も設定されていない場合は、接続のために指定されたユーザ名が使用されます。
データのみをダンプし、スキーマ (データ定義) はダンプしません。
このオプションは、プレインテキスト形式の場合にのみ意味があります。他の形式では、pg_restore を呼び出す時にこのオプションを指定することができます。
ラージオブジェクトをダンプに含めます。
データベースオブジェクトを作成する前に掃除 (削除) するためのコマンドを書き出します。
このオプションは、プレインテキスト形式の場合にのみ意味があります。他の形式では、pg_restore を呼び出す時にこのオプションを指定することができます。
データベース自体を作成し、作成したデータベースに接続するコマンドを始めに出力します。(この形のスクリプトを使用する場合、スクリプトを実行する前にどのデータベースに接続すればいいかという問題 を考える必要がなくなります。)
このオプションは、プレインテキスト形式の場合にのみ意味があります。他の形式では、pg_restore を呼び出す時にこのオプションを指定することができます。
データを (COPY ではなく) INSERT コマンドとしてダンプします。 これを行うとリストアに時間がかかりますが、生成されたアーカイブは他の SQL データベースへの移植性が高くなります。
データを明示的に列名を付けた INSERT コマンド (INSERT INTO table (column, ...) VALUES...) としてダンプします。これによりリストアは非常に遅くなります。 しかし、列の順番を変更する場合にはこれが必要です。
出力を指定のファイルに送ります。省略時は標準出力が使用されます。
出力形式を選択します。format は以下の値のいずれかです。
プレインテキストの SQL スクリプトファイルを出力します (デフォルト)。
pg_restore への入力に適した tar アーカイブを出力します。このアーカイブ形式では、並び替えやスキーマ要素を除外するデータベースのリストアを行なうことができます。また、リストア時にデータを選択してリロードすることもできます。
pg_restore への入力に適したカスタムアーカイブを出力します。これは、もっとも柔軟な形式であり、スキーマ要素もデータロードも並び替えることができます。また、この形式はデフォルトで圧縮されます。
pg_dump とデータベースサーバのバージョンの不一致を無視します。
pg_dump は、バージョン 7.0 以上であれば前のリリースの PostgreSQL データベースも処理できますが、7.0 より古いバージョンのデータベースの処理はできません。バージョンチェックを無効にする必要がある場合に、このオプションを使います (もし pg_dump が失敗したとしても、警告されなかったとは言えませんよ)。
各テーブルのオブジェクト識別子 (OID) をダンプします。アプリケーションで 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 を呼び出す時にこのオプションを指定することができます。
スキーマ (データ定義) のみをダンプし、データはダンプしません。
トリガを使用不可能にする場合に使用する、スーパユーザのユーザ名を指定します。 これは --disable-triggers を使用する場合にのみ該当します。 (通常は --use-set-session-authorization を指定して、その後スーパユーザとして結果スクリプトを開始する方が良いでしょう。)
table のデータのみをダンプします。
冗長モードを指定します。 これを指定すると、pg_dump は進行状況メッセージを標準エラーに出力します。
アクセス権限 (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 がターゲットテーブル上のトリガを一時的に使用不可にするためのコマンドを含めるよう指示します。 このオプションは、参照整合性検査や、データのリロード中には呼び出されないようにしたいテーブル上のその他のトリガがある場合に使用します。
現在のところ、--disable-triggers を指定してコマンドを実行するのは、スーパーユーザでなければなりません。 そのため、ユーザは -S でスーパーユーザを指定するか、あるいは望ましい方法として --use-set-session-authorization を指定し、その後スーパーユーザとして結果スクリプトを開始する必要があります。 どちらのオプションも指定しない場合は、スクリプト全体をスーパーユーザとして実行する必要があります。
このオプションは、プレインテキスト形式の場合にのみ意味があります。他の形式では、pg_restore を呼び出す時にこのオプションを指定することができます。
圧縮をサポートするアーカイブ形式で使用する、圧縮レベルを指定します (現時点では、カスタムアーカイブ形式のみが圧縮をサポートしています)。
以下のコマンドラインオプションは、データベース接続パラメータを制御します。
サーバが稼働しているマシンのホスト名を指定します。ホスト名がスラッシュから始まる場合、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 は、指定したホストとポート上の PostgreSQL サーバに接続できませんでした。このメッセージが表示された場合、サーバが正しいホストで稼働していること、および、正しいポートを指定していることを確認して下さい。
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 はデータを挿入する前にユーザテーブルにトリガを無効とするための問い合わせを出力し、そしてデータが挿入されるとそれらを再び有効にするための問い合わせを出力します。リストアが途中で停止してしまった場合、システムカタログは間違った状態のままになっているかもしれません。
tar アーカイブのメンバのサイズは、8 GB 未満に制限されています。 (これは tar ファイル形式が本来持っている制限です。) そのため、テーブルのテキスト表現がこのサイズを越える場合には、この形式は使用できません。 tar アーカイブとその他の出力形式の合計サイズには制限がありません (オペレーティングシステムによる制限がある場合は別です)。