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データベースに接続し、このデータベースに直接リストアします。
データベースにSQLコマンドを送信している時にエラーが発生した場合終了します。 デフォルトでは続行し、リストア処理の終わりに発生したエラーの数を表示します。
作成するスクリプト、もしくは、-lを使用した場合の一覧用の出力ファイルを指定します。 デフォルトは標準出力です。
アーカイブの形式を指定します。 pg_restoreは形式を自動認識しますので、形式の指定は必須ではありません。 指定する場合は、以下のいずれかを取ります。
アーカイブはtarアーカイブです。 このアーカイブ形式では、並び替えやスキーマ要素を除外するデータベースのリストアを行なうことができます。 また、リストア時にデータを選択してリロードすることもできます。
アーカイブの形式はpg_dumpのカスタム形式です。 これは、もっとも柔軟な形式であり、スキーマ要素もデータロードも並び替えることができます。 また、この形式はデフォルトで圧縮されます。
データベースのバージョンチェックを無視します。
指定したインデックスの定義のみをリストアします。
アーカイブの内容を一覧表示します。 この操作の出力は-Lオプションにて、リストアするアイテムの並び替えや限定を行なう際に使用可能です。
list-file内の要素のみを、ファイル内の出現順にリストアします。 行を移動することも、行の先頭に;を付けてコメントアウトすることも可能です。 (後述の例を参照してください。)
オブジェクトの所有権を元のデータベースに合わせるためのコマンドを出力しません。 デフォルトでpg_restoreは、ALTER OWNERまたはSET SESSION AUTHORIZATIONを発行して、作成したスキーマ要素の所有権を設定します。 スーパーユーザ(もしくは、そのスクリプト内の全てのオブジェクトを所有するユーザ)によって、データベースへの最初の接続が行われていない限り、これらの文は失敗します。 -Oを付与することで、任意のユーザ名を初期接続のために使用できるようになり、また、このユーザが作成される全てのオブジェクトの所有者となります。
指定した関数のみをリストアします。 関数や引数の名前を正確にダンプファイルの目録通りのスペルに合わせることに注意してください。
このオプションは廃止されましたが、後方互換のためにまだ受け付けられます。
スキーマ(データ定義)をリストアし、データをリストアしません。 シーケンスの値は初期化されます。
トリガを使用不可能にする場合に使用する、スーパーユーザのユーザ名を指定します。 これは--disable-triggersを使用する場合にのみ該当します。
指定されたテーブルのみの定義かデータ、もしくはその両方をリストアします。
指定されたトリガだけをリストアします。
冗長モードを指定します。
アクセス権限(grant/revokeコマンド)のリストアを行ないません。
OWNER TOコマンドの代わりに標準SQLのSET SESSION AUTHORIZATIONコマンドを出力します。 これにより、ダンプの標準への互換性が高まりますが、ダンプ内のオブジェクトの履歴によっては正しくリストアされない可能性があります。
このオプションは、データのみのダンプを作成する際にしか適用されません。 データのリロード中、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は単一のテーブルのラージオブジェクトをリストアしません。 アーカイブにラージオブジェクトが含まれている場合、全てのラージオブジェクトがリストアされます。
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