pg_restore [ -a ] [ -c ] [ -C ] [ -d dbname ] [ -f output-file ] [ -F format ] [ -i index ] [ -l ] [ -L contents-file ] [ -N | -o | -r ] [ -O ] [ -P function-name ] [ -R ] [ -s ] [ -S ] [ -t table ] [ -T trigger ] [ -v ] [ -x ] [ -X keyword] [ -h host ] [ -p port ] [ -U username ] [ -W ] [ archive-file ]
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 は全てのオブジェクトの所有権情報を失ってしまうからです。
スキーマ(定義)をリストアし、データはリストアしません。シーケンスの値は初期化されます。
トリガの無効化やスキーマ要素の所有権の設定に使用する、スーパユーザのユーザ名を指定します。デフォルトでは、pg_restore は、現在のユーザがスーパユーザであった場合はそのユーザ名を使用します。
table 用のスキーマとデータのみをリストアします。
trigger の定義のみをリストアします。
冗長モードを指定します。
アクセス権限(grant/revoke コマンド)のリストアを行ないません。
通常、アーカイブのリストアの際に(例えば、現在のオブジェクトの所有権を正しく設定するために)現在のデータベースユーザの変更要求を行なう場合、データベースへの新しい接続を必ず開きます。この時に(パスワードなど)手作業による操作が必要となる場合があります。 -X use-set-session-authorization オプションを使用した場合、pg_restore は代わりに SET SESSION AUTHORIZATION コマンドを使用します。これは同じ効果が得られますが、アーカイブをリストアするユーザはデータベーススーパユーザでなければなりません。このオプションは -R オプションを無効にします。
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 は、指定したホストとポート上の postmaster プロセスに接続できませんでした。このメッセージが現れた場合、サーバが正しいホストで稼働していること、および、正しいポートを指定していることを確認して下さい。認証システムを使用するサイトの場合は、必要な認証証明があることを確認して下さい。
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
tar ファイルへのラージオブジェクトを含む、mydb というデータベースを以下のようにダンプします。
$ 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