PG_RESTORE(1)

NAME
pg_restore - pg_dumpによって作成されたアーカイブファイルからPostgreSQLデータベースをリストアする

SYNOPSIS

pg_restore [ option... ] [ filename ]

説明

pg_restoreは、pg_dump(1)によってアーカイブされた非プレインテキスト形式のアーカイブファイルを使って、PostgreSQLデータベースをリストアするためのユーティリティです。 このコマンドは、データベースを再構成して保存された時点の状態にするために必要なコマンドを発行します。 また、pg_restoreは、アーカイブファイルから、リストアする内容を選択したり、リストアする前にアイテムの並び替えを行うこともできます。 アーカイブファイルはアーキテクチャに依存しない移植性を持つように設計されています。

pg_restoreの操作には2つのモードがあります。 データベース名が指定された場合、そのアーカイブは直接指定したデータベースにリストアされます データベース名が指定されなかった場合は、データベースを再構築するために必要となるSQLコマンドが含まれたスクリプトが作成されます（ファイルもしくは標準出力に書き出されます）。 このスクリプトの内容は、pg_dumpのプレインテキスト形式の出力と同じです。 実際に、出力を制御するオプションの中には、pg_dumpのオプションに類似したものがああります。

当然ながら、pg_restoreによって、アーカイブファイルに存在しない情報をリストアすることはできません。 例えば、アーカイブが、``INSERTコマンドの形式でデータダンプ''を行うオプションを使用して作成されたものであった場合、pg_restoreは、COPY文を使用してデータを読み込むことはできません。

オプション

pg_restoreは以下のコマンドライン引数を受け付けます。

filename
    リストアするアーカイブファイルの場所を指定します。 指定がない場合は、標準入力が使用されます。

-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は形式を自動認識するので、このオプションは必須ではありません。 指定する値は、以下のいずれかになります。

    t

    tar アーカイブがtarアーカイブであることを表します。 このアーカイブ形式では、並び替えを行ったり、スキーマ要素を除外してデータベースをリストアしたりすることができます。 また、リストア時にデータの一部のみをリロードすることもできます。

    c

    custom
        アーカイブがpg_dumpのカスタム形式であることを表します。 最も柔軟な形式であり、データロードだけでなくスキーマ要素も並び替えることができます。 また、この形式はデフォルトで圧縮されます。

-i

--ignore-version
    廃止されたオプションで、現在は無視されます。

-I index

--index=index
    指定したインデックスの定義のみをリストアします。

-j number-of-jobs

--jobs=number-of-jobs
    pg_restoreのもっとも時間がかかる部分、つまり、データのロード、インデックスの作成、制約の作成部分を複数の同時実行ジョブを使用して実行します。 このオプションは、複数プロセッサマシンで稼働するサーバに大規模なデータベースをリストアする時間を劇的に減らすことができます。 オペレーティングシステムに依存して、各ジョブは1プロセスまたは1スレッドです。 そして別々のサーバへの接続を使用します。 このオプションの最適値はサーバ、クライアント、ネットワークの構成に依存します。 要素にはCPUコア数やディスク構成も含まれます。 試行する最初の値としてサーバのCPUコア数を勧めます。 しかし、多くの場合これより大きな値でもリストア時間を高速化することができます。 当然ながらあまりに大きな値を使用すると、スラッシングのために性能が劣化することになります。 独自アーカイブ書式のみがこのオプションをサポートします。 入力ファイルは通常のファイルでなければなりません（例えばパイプはいけません）。 このオプションは、直接データベースサーバに接続するのではなく、スクリプトを生成する場合に無視されます。 また、複数ジョブは--single-transactionオプションといっしょに使用することはできません。

-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を付与すると、初期接続に任意のユーザ名を使用できるようになります。ただし、この場合は、全てのオブジェクトの所有者がリストアしたユーザになります。

--no-tablespaces
    テーブル空間を選択するコマンドを出力しません。 このオプションを付けると、すべてのオブジェクトはリストア時デフォルトであったテーブル空間内に作成されます。

-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コマンド）のリストアを行いません。

--disable-triggers
    このオプションは、データのみのダンプを作成する際にしか適用されません。 データのリロード中、pg_restoreに対し、対象テーブル上のトリガを一時的に無効にするコマンドを実行するよう指示します。 このオプションは、データのリロード中には呼び出したくない参照整合性検査やその他のトリガがある場合に使用します。 現在のところ、--disable-triggersを指定してコマンドを実行するのは、スーパーユーザでなければなりません。 そのため、ユーザは-Sでスーパーユーザを指定するか、あるいはPostgreSQLのスーパーユーザ権限でpg_restoreを実行する必要があります（後者の方がより望ましい方法です）。

--use-set-session-authorization
    ALTER OWNERコマンドの代わりに、標準SQLのSET SESSION AUTHORIZATIONコマンドを出力して、オブジェクトの所有権を決定します。 これにより、ダンプの標準への互換性が高まりますが、ダンプ内のオブジェクトの履歴によっては正しくリストアされない可能性が生じます。

--no-data-for-failed-tables
    デフォルトでは、関連するテーブルの作成に失敗した（たとえば、既に存在するなどの理由により）としてもテーブルデータオブジェクトはリストアされます。 このオプションにより、こうしたテーブルデータは単に無視されるようになります。 これは、対象のデータベースに目的のテーブルの中身が含まれている時に便利です。 たとえばPostGISなどのPostgreSQL拡張用の補助テーブルが既に対象のデータベース内に存在する可能性があります。 このオプションを指定すれば、二重ロードや古いデータのロードを防ぐことができます。 このオプションはSQLスクリプト出力を生成する時ではなく、直接データベースにリストアする時にのみ効果的です。

-1

--single-transaction
    リストアを単一トランザクションとして実行します（つまり発行するコマンドをBEGIN/COMMITで囲みます）。 これにより確実に、すべてのコマンドが完全に成功するか、まったく変更がなされないかのどちらかになります。 このオプションは--exit-on-errorを意味します。

pg_restoreはさらに以下のコマンドライン引数を接続パラメータとして受け付けます。

-h host

--host=host
    サーバが稼働しているマシンのホスト名を指定します。 この値がスラッシュから始まる場合、Unixドメインソケット用のディレクトリとして使用されます。 デフォルトは、設定されていればPGHOST環境変数から取得されます。 設定されていなければ、Unixドメインソケット接続と仮定されます。

-p port

--port=port
    サーバが接続を監視するTCPポートもしくはローカルUnixドメインソケットファイルの拡張子を指定します。 デフォルトは、設定されている場合、PGPORT環境変数の値となります。設定されていなければ、コンパイル時のデフォルト値となります。

-U username

--username=username
    接続ユーザ名です。

-w

--no-password
    パスワードの入力を促しません。 サーバがパスワード認証を必要とし、かつ、.pgpassファイルなどの他の方法が利用できない場合、接続試行は失敗します。 バッチジョブやパスワードを入力するユーザが存在しない場合にこのオプションは有用かもしれません。。

-W

--password
    データベースに接続する前に、pg_restoreは強制的にパスワード入力を促します。 サーバがパスワード認証を要求する場合pg_restoreは自動的にパスワード入力を促しますので、これが重要になることはありません。 しかし、pg_restoreは、サーバにパスワードが必要かどうかを判断するための接続試行を無駄に行います。 こうした余計な接続試行を防ぐために-Wの入力が有意となる場合もあります。

--role=rolename
    リストアを実行する際に使用するロール名を指定します。 このオプションによりpg_restoreはデータベースに接続した後にSET ROLE rolenameコマンドを発行するようになります。 認証に使用したユーザ（-Uで指定されたユーザ）がpg_restoreで必要とされる権限を持たないが、必要な権限を持つロールに切り替えることができる場合に有用です。 一部のインストレーションではスーパーユーザとして直接ログインさせないポリシーを取ることがありますが、このオプションを使用することでポリシーに反することなくリストアを行うことができます。

環境

PGHOST

PGOPTIONS

PGPORT

PGUSER
    デフォルトの接続パラメータです。

また、このユーティリティは、他のほとんどのPostgreSQLユーティリティと同様、libpqでサポートされる環境変数を使用します（in the documentationを参照してください）。

診断

-dオプションによってデータベースに直接接続するよう指定されている場合、pg_restoreは内部でSQL文を実行します。 pg_restoreの実行時に問題が発生する場合は、psql(1)などを使用して、そのデータベースから情報を選択できることを確認してください。 また、libpqフロントエンドライブラリで使用されるデフォルト接続設定や環境変数もすべて適用されます。

注釈

template1データベースに対しローカルな変更を行っている場合、pg_restoreの出力は、確実に空のデータベースにロードするよう注意してください。 そうしないと、おそらく追加されたオブジェクトの重複定義によってエラーが発生します。 ローカルな追加が反映されていない空のデータベースを作成するには、template1ではなくtemplate0をコピーしてください。 以下に例を示します。

CREATE DATABASE foo WITH TEMPLATE template0;

pg_restoreの制限を以下に示します。

•   --disable-triggersオプションを使用して既存のテーブルにデータをリストアする際、pg_restoreは、データを挿入する前に、ユーザテーブル上のトリガを無効にする問い合わせを発行し、 データの挿入が完了した後で、それらを再び有効にする問い合わせを発行します。 リストアが途中で停止した場合、システムカタログが不適切な状態のままになっている可能性があります。

•   pg_restoreは特定のテーブルのみのラージオブジェクトなどといった、ラージオブジェクトを選択してリストアすることはできません。 アーカイブにラージオブジェクトが含まれる場合、すべてのラージオブジェクトをリストアします。 もし-L、-tなどのオプション経由で実行された場合は、全くリストアしません。

pg_dumpの制限についての詳細は、pg_dump(1)のドキュメントも参照してください。

リストア後は、オプティマイザが有用な統計情報を持つように、リストアしたテーブルそれぞれに対してANALYZEを実行することをお勧めします。 詳しくはin the documentationおよびin the documentationを参照してください。

例

mydbという名前のデータベースをカスタム書式のダンプファイルにダンプしているものと仮定します。

$ pg_dump -Fc mydb > db.dump

データベースを削除し、ダンプファイルから再作成します。

$ dropdb mydb
$ pg_restore -C -d postgres db.dump

-dスイッチのデータベース名には、クラスタに存在するデータベースを指定することができます。 pg_restoreは、例えばmydbに対するCREATE DATABASEコマンドを発行するためだけに、この名前を使用します。 -Cを付けると、データは常にダンプファイル内に記載された名前のデータベースにリストアされます。

newdbという新しいデータベースにダンプファイルをリストアします。

$ createdb -T template0 newdb
$ pg_restore -d newdb db.dump

-Cを使用していないことに注目してください。 変わりにリストアするデータベースに直接接続しています。 また、新しいデータベースをtemplate1ではなくtemplate0からコピーして作成している点にも注目してください。 確実に初期状態を空にするためです。

データベースのアイテムを並び換えるには、まずこのアーカイブの内容の一覧をダンプしなければなりません。

$ pg_restore -l db.dump > db.list

一覧ファイルは、ヘッダと各アイテムを1行で表したものから構成されます。

;
; Archive created at Fri Jul 28 22:28:36 2000
;     dbname: mydb
;     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 db.list db.dump

関連項目
pg_dump(1), pg_dumpall(1), psql(1)