pg_restore

名前

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

概要

pg_restore [option...] [filename]

説明

pg_restore は、pg_dump によっていずれかの非プレインテキスト形式でアーカイブされた 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 データベースに接続し、このデータベースに直接リストアします。

-f filename
--file=filename

作成するスクリプト、もしくは、-l を使用した場合の一覧用の出力ファイルを指定します。デフォルトは標準出力です。

-F format
--format=format

アーカイブの形式を指定します。pg_restore は形式を自動設定しますので、形式の指定は必須ではありません。指定する場合は、以下のいずれかをとります。

t

アーカイブは tar アーカイブです。このアーカイブ形式では、並び替えやスキーマ要素を除外するデータベースのリストアを行なうことができます。また、リストア時にデータを選択してリロードすることもできます。

c

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

-i
--ignore-version

データベースのバージョンチェックを無視します。

-I index
--index=index

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

-l
--list

アーカイブの内容を一覧表示します。この操作の出力は -L オプションにて、リストアするアイテムの並び替えや限定を行なう際に使用可能です。

-L list-file
--use-list=list-file

list-file 内の要素のみを、ファイル内の出現順にリストアします。行を移動することも、行の先頭に ; を付けてコメントアウトすることも可能です。 (後述の例を参照してください。)

-N
--orig-order

アイテムを、pg_dumpで生成した通りの順番でリストアします。 このオプションは実際にはあまり使用されません。 pg_dump は自身に都合の良い順番でアイテムを生成し、これは安全にリストアできる順番とは異なるためです。 (これは、そのアーカイブの目録に最後にリストされるアイテムの順番ではありません。) -rも参照してください。

-o
--oid-order

OID による順番づけに従ってアイテムをリストアします。 このオプションは場合によっては有用です。 OIDによっておおよその元の生成順を判るからです。 両方が指定されている場合、このオプションは、-N を上書きします。 -rも参照してください。

-O
--no-owner

オブジェクトの所有権を元のデータベースに合わせるためのコマンドを出力しません。 デフォルトでpg_restore は、SET SESSION AUTHORIZATIONを発行して、作成したスキーマ要素の所有権を設定します。 スーパーユーザ(もしくは、そのスクリプト内の全てのオブジェクトを所有するユーザ)によって、データベースへの最初の接続が行われていない限り、これらの文は失敗します。 -Oを付与することで、任意のユーザ名を初期接続のために使用できるようになり、また、このユーザが作成される全てのオブジェクトの所有者となります。

-P function-name(argtype [, ...])
--function=function-name(argtype [, ...])

指定した関数のみをリストアします。 関数や引数の名前を正確にダンプファイルの目録通りのスペルに合わせることに注意してください。

-r
--rearrange

オブジェクトの種類によってアイテムを再調整します。 (これは、もしあれば-N-oで指定されたソートの後に発生します。) この再調整は、最善のリストア性能を与えることを目的としたものです。

-N-o-r がいずれもなければ、pg_restore はダンプの目録に現われる順番でアイテムをリストアします。 もし -L が指定されていたら、list-file 内の出現順になります。 -o-rの組合せは、ダンプの目録を作成する前に、pg_dumpによるソートを二重化しますので、通常はこれを指定する必要はありません。

-R
--no-reconnect

このオプションは廃止されましたが、後方互換のためにまだ受け付けられます。

-s
--schema-only

スキーマ (データ定義) をリストアし、データはリストアしません。シーケンスの値は初期化されます。

-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

通常、アーカイブのリストアの際に (例えば、現在のオブジェクトの所有権を正しく設定するために) 現在のデータベースユーザの変更要求を行なう場合、データベースへの新しい接続が必ず開かれます。 この時に (パスワードなど) 手動による操作が必要となる場合があります。 -X use-set-session-authorization オプションを使用した場合、pg_restore は代わりに SET SESSION AUTHORIZATION コマンドを使用します。 これは同じ効果が得られますが、アーカイブをリストアするユーザはデータベーススーパユーザでなければなりません。 このオプションは -R オプションを無効にします。

-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

強制的にパスワードのプロンプトを表示します。これは、パスワード認証が必要なサーバの場合、自動的に行なわれます。

環境

PGHOST
PGPORT
PGUSER

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

診断

直接のデータベース接続が -d オプションで指定されている場合、pg_restore は内部で SQL 文を実行します。 pg_restore の実行に問題があった場合、例えば psql などを用いて、そのデータベースから情報を選択できることを確認してください。

注釈

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

CREATE DATABASE foo WITH TEMPLATE template0;

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

履歴

pg_restore ユーティリティは PostgreSQL 7.1 から登場しました。

関連項目

pg_dump, pg_dumpall, psql