pg_restoreは、pg_dumpによってアーカイブされた非プレインテキスト形式のアーカイブファイルを使って、PostgreSQLデータベースをリストアするためのユーティリティです。 このコマンドは、データベースを再構成して保存された時点の状態にするために必要なコマンドを発行します。 また、pg_restoreは、アーカイブファイルから、リストアする内容を選択したり、リストアする前にアイテムの並び替えを行うこともできます。 アーカイブファイルはアーキテクチャに依存しない移植性を持つように設計されています。
pg_restoreの操作には2つのモードがあります。 データベース名が指定された場合、そのアーカイブは直接指定したデータベースにリストアされます データベース名が指定されなかった場合は、データベースを再構築するために必要となるSQLコマンドが含まれたスクリプトが作成されます(ファイルもしくは標準出力に書き出されます)。 このスクリプトの内容は、pg_dumpのプレインテキスト形式の出力と同じです。 実際に、出力を制御するオプションの中には、pg_dumpのオプションに類似したものがああります。
当然ながら、pg_restoreによって、アーカイブファイルに存在しない情報をリストアすることはできません。 例えば、アーカイブが、"INSERTコマンドの形式でデータダンプ"を行うオプションを使用して作成されたものであった場合、pg_restoreは、COPY文を使用してデータを読み込むことはできません。
pg_restoreは以下のコマンドライン引数を受け付けます。
リストアするアーカイブファイルの場所を指定します。 指定がない場合は、標準入力が使用されます。
-a
--data-only
データのみをリストアし、スキーマ(データ定義)はリストアしません。
-c
--clean
再作成前に、データベースオブジェクトをクリーンアップ(削除)します。
-C
--create
リストア前にデータベースを作成します
(このオプションがある場合、-d
で指定したデータベースは最初のCREATE DATABASEコマンドの発行時にのみ使用されます。
そして、全てのデータはアーカイブ内に記述された名前のデータベースにリストアされます)。
-d dbname
--dbname=dbname
dbnameデータベースに接続し、このデータベースに直接リストアします。
-e
--exit-on-error
データベースにSQLコマンドを送信中にエラーが発生した場合、処理を終了します。 デフォルトでは、処理を続行し、リストア処理の最後に発生したエラーの数を表示します。
-f filename
--file=filename
作成するスクリプト(-l
を使用した場合はアーカイブの一覧)の出力ファイルを指定します。
デフォルトは標準出力です。
-F format
--format=format
アーカイブの形式を指定します。 pg_restoreは形式を自動認識するので、このオプションは必須ではありません。 指定する値は、以下のいずれかになります。
アーカイブがtarアーカイブであることを表します。 このアーカイブ形式では、並び替えを行ったり、スキーマ要素を除外してデータベースをリストアしたりすることができます。 また、リストア時にデータの一部のみをリロードすることもできます。
アーカイブがpg_dumpのカスタム形式であることを表します。 最も柔軟な形式であり、データロードだけでなくスキーマ要素も並び替えることができます。 また、この形式はデフォルトで圧縮されます。
-i
--ignore-version
データベースのバージョンチェックを無視します。
-I index
--index=index
指定したインデックスの定義のみをリストアします。
-l
--list
アーカイブの内容を一覧として出力します。
このコマンドが出力する一覧は、-L
オプションで、リストアするアイテムの並び替えや選択を行う際に使用することができます。
-L list-file
--use-list=list-file
list-file内で指定した要素のみを、指定された順にリストアします。 行を移動したり、行の先頭に;を付けてコメントアウトしたりすることも可能です (後述の例を参照してください)。
-n namespace
--schema=schema
指定されたスキーマ内のオブジェクトのみをリストアします。
これは特定のテーブルのみをリストアするために-t
オプションと組み合わせることができます。
-O
--no-owner
オブジェクトの所有者を元のデータベースに合わせるためのコマンドを出力しません。
デフォルトでは、pg_restoreは、ALTER OWNERまたはSET SESSION AUTHORIZATIONを発行して、作成したスキーマ要素の所有者を設定します。
データベースに最初に接続したのがスーパーユーザ(もしくは、そのスクリプト内の全てのオブジェクトを所有するユーザ)でない場合、これらの文は失敗します。
-O
を付与すると、初期接続に任意のユーザ名を使用できるようになります。ただし、この場合は、全てのオブジェクトの所有者がリストアしたユーザになります。
-P function-name(argtype [, ...])
--function=function-name(argtype [, ...])
指定した関数のみをリストアします。 関数や引数の名前は、ダンプファイルの一覧で出力される通りのスペルで正確に入力するよう注意してください。
-R
--no-reconnect
このオプションは廃止されました。後方互換性を保持するために受け入れられています。
-s
--schema-only
スキーマ(データ定義)のみをリストアし、データ(テーブルの内容)をリストアしません。
シーケンスの現在値はリストアされません。
("スキーマ"という用語を別の意味で使用する、--schema
オプションと混同しないでください。)
-S username
--superuser=username
トリガを無効にする場合に使用する、スーパーユーザのユーザ名を指定します。
これは--disable-triggers
を使う場合にのみ使用されます。
-t table
--table=table
指定されたテーブルのみリストアします(テーブル定義だけ、または、データだけを対象とすることもできます)。
-T trigger
--trigger=trigger
指定されたトリガだけをリストアします。
-v
--verbose
冗長モードを指定します。
-x
--no-privileges
--no-acl
アクセス権限(grant/revokeコマンド)のリストアを行いません。
-X use-set-session-authorization
--use-set-session-authorization
ALTER OWNERコマンドの代わりに、標準SQLのSET SESSION AUTHORIZATIONコマンドを出力して、オブジェクトの所有権を決定します。 これにより、ダンプの標準への互換性が高まりますが、ダンプ内のオブジェクトの履歴によっては正しくリストアされない可能性が生じます。
-X disable-triggers
--disable-triggers
このオプションは、データのみのダンプを作成する際にしか適用されません。 データのリロード中、pg_restoreに対し、対象テーブル上のトリガを一時的に無効にするコマンドを実行するよう指示します。 このオプションは、データのリロード中には呼び出したくない参照整合性検査やその他のトリガがある場合に使用します。
現在のところ、--disable-triggers
を指定してコマンドを実行するのは、スーパーユーザでなければなりません。
そのため、ユーザは-S
でスーパーユーザを指定するか、あるいはPostgreSQLのスーパーユーザ権限でpg_restoreを実行する必要があります(後者の方がより望ましい方法です)。
pg_restoreはさらに以下のコマンドライン引数を接続パラメータとして受け付けます。
-h host
--host=host
サーバが稼働しているマシンのホスト名を指定します。 この値がスラッシュから始まる場合、Unixドメインソケット用のディレクトリとして使用されます。 デフォルトは、設定されていればPGHOST環境変数から取得されます。 設定されていなければ、Unixドメインソケット接続と仮定されます。
-p port
--port=port
サーバが接続を監視するTCPポートもしくはローカルUnixドメインソケットファイルの拡張子を指定します。 デフォルトは、設定されている場合、PGPORT環境変数の値となります。設定されていなければ、コンパイル時のデフォルト値となります。
-U username
指定したユーザとして接続します。
-W
強制的にパスワードのプロンプトを表示します。 これは、パスワード認証が必要なサーバの場合、自動的に行われます。
-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 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