pg_restore は、pg_dump によっていずれかの非プレインテキスト形式でアーカイブされた PostgreSQL データベースをリストアするためのユーティリティです。このコマンドは、テーブル内のデータを含め、すべてのユーザ定義型、関数、テーブル、インデックス、集約、演算子を再生成するために必要なコマンドを発行します。
アーカイブファイルには、pg_restore がデータベースを再構築するための情報が含まれています。 それだけではなく、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 のカスタム形式です。これは、もっとも柔軟な形式であり、スキーマ要素もデータロードも並び替えることができます。また、この形式はデフォルトで圧縮されます。
データベースのバージョンチェックを無視します。
指定した index のみ、定義をリストアします。
アーカイブの内容を一覧表示します。このコマンドの出力は -L オプションにて、リストアするアイテムの並び替えや限定を行なう際に使用可能です。
list-file 内の要素のみを、ファイル内の出現順にリストアします。行を移動することも、行の先頭に ; を付けてコメントアウトすることも可能です。
アイテムをダンプした時の順番のままリストアします。 デフォルトでは pg_dump は処理を簡単に行えるような順番でアイテムをダンプし、変更された OID 順にアーカイブに保存します。このオプションは、OID による順番づけを無視します。
OID による順番づけに従ってアイテムをリストアします。 デフォルトでは pg_dump は処理を簡単に行えるような順番でアイテムをダンプし、変更された OID 順にアーカイブに保存します。このオプションは、OID による順番づけを厳密に守ります。
元のオブジェクトの所有権のリストアを行ないません。オブジェクトの所有権は、データベース接続に使用したユーザ名のものになります。
リストアするプロシージャや関数を指定します。
変更された OID による順番づけに従って、アイテムをリストアします。 デフォルトでは pg_dump は処理を簡単に行えるような順番でアイテムをダンプし、変更された OID 順にアーカイブに保存します。ほとんどのオブジェクトは、OID 順にリストアされますが、(ルールやインデックスなどの) いくつかのリストアは、その OID に関係なく、リストア処理の最後に行なわれます。このオプションはデフォルトです。
アーカイブをリストアしている間、pg_restore は通常、作成したオブジェクトの所有権を修正するために異なるユーザ名で何回もデータベースに接続しなおします。(例えば、再接続のために手動による (パスワードの) 入力が必要である場合など) この処理が好まれない場合は、このオプションを使用して、pg_restore が再接続要求を発行しないようにすることができます。(プレインテキストモードでは、データベース未接続の場合の接続要求は psql \connect コマンドを発行することで実現しています。) しかし、このオプションはどちらかといえばナマクラ道具です。 -X use-set-session-authorization オプションを使用しない 限り、これにより pg_restore は全てのオブジェクトの所有権情報を失ってしまうからです。
スキーマ (定義) をリストアし、データはリストアしません。シーケンスの値は初期化されます。
トリガを使用不可能にする場合に使用する、スーパユーザのユーザ名を指定します。 これは --disable-triggers を使用する場合にのみ該当します。
table 用のスキーマとデータのみをリストアします。
trigger の定義のみをリストアします。
冗長モードを指定します。
アクセス権限 (grant/revoke コマンド) のリストアを行ないません。
通常、アーカイブのリストアの際に (例えば、現在のオブジェクトの所有権を正しく設定するために) 現在のデータベースユーザの変更要求を行なう場合、データベースへの新しい接続が必ず開かれます。この時に (パスワードなど) 手動による操作が必要となる場合があります。 -X use-set-session-authorization オプションを使用した場合、pg_restore は代わりに SET SESSION AUTHORIZATION コマンドを使用します。これは同じ効果が得られますが、アーカイブをリストアするユーザはデータベーススーパユーザでなければなりません。このオプションは -R オプションを無効にします。
このオプションは、データのみのダンプを作成する際にしか適用されません。 データのリロード中、pg_restore に対し、ターゲットテーブル上のトリガを一時的に使用不可にするためのコマンドを実行するよう指示します。 このオプションは、参照整合性検査や、データのリロード中には呼び出されないようにしたいテーブル上のその他のトリガがある場合に使用します。
現在のところ、--disable-triggers を指定してコマンドを実行するのは、スーパーユーザでなければなりません。 そのため、ユーザは -S でスーパーユーザを指定するか、あるいは推奨される方法として --use-set-session-authorization を指定し、その後 PostgreSQL スーパユーザとして pg_restore を実行する必要があります。
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_restore は、指定したホストとポート上の PostgreSQL サーバに接続できませんでした。このメッセージが表示された場合、サーバが正しいホストで稼働していること、および、正しいポートを指定していることを確認して下さい。認証システムを使用するサイトの場合は、必要な認証証明があることを確認して下さい。
Note: 直接データベース接続が -d オプションで指定された場合、pg_restore は内部で SQL 文を実行します。pg_restore の実行に問題が発生した場合は、例えば、psql を使用して、そのデータベースで情報の選択を行うことができるかどうかを確認して下さい。
システムにおいて template1 データベースに対しローカルな変更を行っている場合、pg_restore の出力を、確実に空のデータベースにロードするよう注意して下さい。 そうしないと、追加したオブジェクトの重複定義によるエラーが発生することになります。ローカルな追加が含まれない、空のデータベースを作成するには、template1 からではなく template0 からコピーして下さい。 以下に例を示します。
CREATE DATABASE foo WITH TEMPLATE = template0;
pg_restore の制限を以下に示します。
既存のテーブルにデータをリストアする際、pg_restore はデータを挿入する前に、ユーザテーブル上のトリガを無効にする問い合わせを発行します。 そして、データのリストアが完了した後に再度有効にする問い合わせを発行します。リストアが途中で停止してしまった場合、システムカタログは間違った状態のままになっているかもしれません。
pg_restore はラージオブジェクトを 1 つだけのテーブルに対してはリストアしません。アーカイブにラージオブジェクトが含まれている場合、全てのラージオブジェクトがリストアされます。
pg_dump の制限についての詳細は、pg_dump の文書も参照して下さい。
データベースをダンプします。
$ pg_dump mydb > db.out
このデータベースは以下のようにしてリロードします。
$ psql -d database -f db.out
ラージオブジェクトを含む、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