pg_restore は、pg_dump によっていずれかの非プレインテキスト形式でアーカイブされた PostgreSQL データベースをリストアするためのユーティリティです。 このコマンドは、保存された時点の状態にデータベースを再構成するために必要なコマンドを発行します。 また、アーカイブファイルを使用して、pg_restore は何をリストアするかを選択することができ、さらに、リストアする前にアイテムの並び換えを行うこともできます。 アーカイブファイルはアーキテクチャに依存しない移植性を持つように設計されています。
pg_restore の操作には 2 つのモードがあります。 データベース名が指定された場合は、そのアーカイブは直接指定したデータベースにリストアされます。 (ラージオブジェクトのリストアはデータベースに直接接続するしかありません。) さもなくば、データベースを再構築するために必要となる SQL コマンドを内容とするスクリプトが作成され (ファイルもしくは標準出力に書き出され) ます。 この内容は、pg_dump のプレインテキスト形式の出力に似ています。 従ってこのスクリプトの出力を制御するオプションのいくつかは pg_dump のオプションに類似しています。
当然ながら、pg_restore は、アーカイブファイルに存在しない情報を戻すことはできません。 例えば、アーカイブが、"INSERT コマンドによるデータダンプ" オプションを使用して作成されたものであった場合、pg_restore は、COPY 文を使用してデータを読み込むことができません。
pg_restore は以下のコマンドライン引数を受け付けます。
リストアするアーカイブファイルの場所を指定します。指定がない場合は、標準入力が使用されます。
データのみをリストアし、スキーマ (データ定義) はリストアしません。
再作成前に、データベースオブジェクトを掃除 (削除) します。
リストア前にデータベースを作成します。 (このオプションがある場合、-d で指定したデータベースは最初の CREATE DATABASE コマンドの発行時にのみ使用されます。全てのデータはアーカイブ内に記述された名前のデータベースにリストアされます。)
dbname データベースに接続し、このデータベースに直接リストアします。
作成するスクリプト、もしくは、-l を使用した場合の一覧用の出力ファイルを指定します。デフォルトは標準出力です。
アーカイブの形式を指定します。pg_restore は形式を自動設定しますので、形式の指定は必須ではありません。指定する場合は、以下のいずれかをとります。
アーカイブは tar アーカイブです。このアーカイブ形式では、並び替えやスキーマ要素を除外するデータベースのリストアを行なうことができます。また、リストア時にデータを選択してリロードすることもできます。
アーカイブの形式は pg_dump のカスタム形式です。これは、もっとも柔軟な形式であり、スキーマ要素もデータロードも並び替えることができます。また、この形式はデフォルトで圧縮されます。
データベースのバージョンチェックを無視します。
指定したインデックスの定義のみをリストアします。
アーカイブの内容を一覧表示します。この操作の出力は -L オプションにて、リストアするアイテムの並び替えや限定を行なう際に使用可能です。
list-file 内の要素のみを、ファイル内の出現順にリストアします。行を移動することも、行の先頭に ; を付けてコメントアウトすることも可能です。 (後述の例を参照してください。)
アイテムを、pg_dumpで生成した通りの順番でリストアします。 このオプションは実際にはあまり使用されません。 pg_dump は自身に都合の良い順番でアイテムを生成し、これは安全にリストアできる順番とは異なるためです。 (これは、そのアーカイブの目録に最後にリストされるアイテムの順番ではありません。) -rも参照してください。
OID による順番づけに従ってアイテムをリストアします。 このオプションは場合によっては有用です。 OIDによっておおよその元の生成順を判るからです。 両方が指定されている場合、このオプションは、-N を上書きします。 -rも参照してください。
オブジェクトの所有権を元のデータベースに合わせるためのコマンドを出力しません。 デフォルトでpg_restore は、SET SESSION AUTHORIZATIONを発行して、作成したスキーマ要素の所有権を設定します。 スーパーユーザ(もしくは、そのスクリプト内の全てのオブジェクトを所有するユーザ)によって、データベースへの最初の接続が行われていない限り、これらの文は失敗します。 -Oを付与することで、任意のユーザ名を初期接続のために使用できるようになり、また、このユーザが作成される全てのオブジェクトの所有者となります。
指定した関数のみをリストアします。 関数や引数の名前を正確にダンプファイルの目録通りのスペルに合わせることに注意してください。
オブジェクトの種類によってアイテムを再調整します。 (これは、もしあれば-N や -oで指定されたソートの後に発生します。) この再調整は、最善のリストア性能を与えることを目的としたものです。
-N、-o、-r がいずれもなければ、pg_restore はダンプの目録に現われる順番でアイテムをリストアします。 もし -L が指定されていたら、list-file 内の出現順になります。 -o と -rの組合せは、ダンプの目録を作成する前に、pg_dumpによるソートを二重化しますので、通常はこれを指定する必要はありません。
このオプションは廃止されましたが、後方互換のためにまだ受け付けられます。
スキーマ (データ定義) をリストアし、データはリストアしません。シーケンスの値は初期化されます。
トリガを使用不可能にする場合に使用する、スーパユーザのユーザ名を指定します。 これは --disable-triggers を使用する場合にのみ該当します。
指定されたテーブルのみの定義かデータ、もしくはその両方をリストアします。
指定されたトリガだけをリストアします。
冗長モードを指定します。
アクセス権限 (grant/revoke コマンド) のリストアを行ないません。
通常、アーカイブのリストアの際に (例えば、現在のオブジェクトの所有権を正しく設定するために) 現在のデータベースユーザの変更要求を行なう場合、データベースへの新しい接続が必ず開かれます。 この時に (パスワードなど) 手動による操作が必要となる場合があります。 -X use-set-session-authorization オプションを使用した場合、pg_restore は代わりに SET SESSION AUTHORIZATION コマンドを使用します。 これは同じ効果が得られますが、アーカイブをリストアするユーザはデータベーススーパユーザでなければなりません。 このオプションは -R オプションを無効にします。
このオプションは、データのみのダンプを作成する際にしか適用されません。 データのリロード中、pg_restore に対し、ターゲットテーブル上のトリガを一時的に使用不可にするためのコマンドを実行するよう指示します。 このオプションは、参照整合性検査や、データのリロード中には呼び出されないようにしたいテーブル上のその他のトリガがある場合に使用します。
現在のところ、--disable-triggers を指定してコマンドを実行するのは、スーパーユーザでなければなりません。 そのため、ユーザは -S でスーパーユーザを指定するか、あるいは推奨される方法として PostgreSQL スーパーユーザとして pg_restore を実行する必要があります。
pg_restore は更に以下のコマンドライン引数を接続パラメータとして受け付けます。
サーバが稼働しているマシンのホスト名を指定します。 この値がスラッシュから始まる場合、Unix ドメインソケット用のディレクトリとして使用されます。 デフォルトは 設定されていれば PGHOST 環境変数から取られます。 設定されていなければ、Unix ドメインソケット接続と仮定されます。
サーバが接続を監視する TCP ポートもしくはローカル Unix ドメインソケットファイルの拡張子を指定します。 ポート番号のデフォルトは、設定されている場合、環境変数 PGPORT の値となり、設定されていなければコンパイル時のデフォルト値となります。
指定したユーザとして接続します。
強制的にパスワードのプロンプトを表示します。これは、パスワード認証が必要なサーバの場合、自動的に行なわれます。
直接のデータベース接続が -d オプションで指定されている場合、pg_restore は内部で SQL 文を実行します。 pg_restore の実行に問題があった場合、例えば psql などを用いて、そのデータベースから情報を選択できることを確認してください。
システムにおいて template1 データベースに対しローカルな変更を行っている場合、pg_restore の出力を、確実に空のデータベースにロードするよう注意して下さい。 そうしないと、追加したオブジェクトの重複定義によるエラーが発生することになります。 ローカルな追加が含まれない、空のデータベースを作成するには、template1 からではなく template0 からコピーして下さい。 以下に例を示します。
CREATE DATABASE foo WITH TEMPLATE template0;
pg_restore の制限を以下に示します。
--disable-triggers オプションを使用して既存のテーブルにデータをリストアする際、pg_restore はデータを挿入する前に、ユーザテーブル上のトリガを無効にする問い合わせを発行します。 そして、データの挿入が完了した後に再度有効にする問い合わせを発行します。 リストアが途中で停止してしまった場合、システムカタログは間違った状態のままになっているかもしれません。
pg_restore はラージオブジェクトを 1 つだけのテーブルに対してはリストアしません。アーカイブにラージオブジェクトが含まれている場合、全てのラージオブジェクトがリストアされます。
pg_dump の制限についての詳細は、pg_dump の文書も参照して下さい。
オプティマイザが有用な統計情報を持つように、リストアした後にリストアしたテーブルそれぞれに対して ANALYZE を実行することを勧めます。
ラージオブジェクトを含む mydb というデータベースを tar ファイルにダンプします。
$ pg_dump -Ft -b mydb > db.tar
(ラージオブジェクトを含む)このデータベースを既存の newdb というデータベースにリロードします。
$ pg_restore -d newdb db.tar
データベースのアイテムの並び換えのためには、まずこのアーカイブの目録をダンプしなければなりません。
$ pg_restore -l archive.file > archive.list
一覧ファイルは、ヘッダと各アイテムを1行で表したものから構成されます。
; ; Archive created at Fri Jul 28 22:28:36 2000 ; dbname: birds ; TOC Entries: 74 ; Compression: 0 ; Dump Version: 1.4-0 ; Format: CUSTOM ; ; ; Selected TOC Entries: ; 2; 145344 TABLE species postgres 3; 145344 ACL species 4; 145359 TABLE nt_header postgres 5; 145359 ACL nt_header 6; 145402 TABLE species_records postgres 7; 145402 ACL species_records 8; 145416 TABLE ss_old postgres 9; 145416 ACL ss_old 10; 145433 TABLE map_resolutions postgres 11; 145433 ACL map_resolutions 12; 145443 TABLE hs_old postgres 13; 145443 ACL hs_old
セミコロンはコメントの始まりです。 行の先頭の番号は、各アイテムに割り当てられた内部アーカイブ ID を示します。
このファイルの行はコメントアウト、削除、並び替えすることができます。以下に例を示します。
10; 145433 TABLE map_resolutions postgres ;2; 145344 TABLE species postgres ;4; 145359 TABLE nt_header postgres 6; 145402 TABLE species_records postgres ;8; 145416 TABLE ss_old postgres
このファイルを pg_restore の入力として使用して、アイテム 10 と 6 だけを、その順番でリストアすることができます。
$ pg_restore -L archive.list archive.file