pg_restore

Name

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

Synopsis

pg_restore [options...]

説明

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 は以下のコマンドライン引数を受け付けます。(長いオプション形式は限られたプラットフォームでしか使用できません。)

archive-name

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

-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

指定した index のみ、定義をリストアします。

-l
--list

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

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

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

-N
--orig-order

アイテムをダンプした時の順番のままリストアします。 デフォルトでは pg_dump は処理を簡単に行えるような順番でアイテムをダンプし、変更された OID 順にアーカイブに保存します。このオプションは、OID による順番づけを無視します。

-o
--oid-order

OID による順番づけに従ってアイテムをリストアします。 デフォルトでは pg_dump は処理を簡単に行えるような順番でアイテムをダンプし、変更された OID 順にアーカイブに保存します。このオプションは、OID による順番づけを厳密に守ります。

-O
--no-owner

元のオブジェクトの所有権のリストアを行ないません。オブジェクトの所有権は、データベース接続に使用したユーザ名のものになります。

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

リストアするプロシージャや関数を指定します。

-r
--rearrange

変更された OID による順番づけに従って、アイテムをリストアします。 デフォルトでは pg_dump は処理を簡単に行えるような順番でアイテムをダンプし、変更された OID 順にアーカイブに保存します。ほとんどのオブジェクトは、OID 順にリストアされますが、(ルールやインデックスなどの) いくつかのリストアは、その OID に関係なく、リストア処理の最後に行なわれます。このオプションはデフォルトです。

-R
--no-reconnect

アーカイブをリストアしている間、pg_restore は通常、作成したオブジェクトの所有権を修正するために異なるユーザ名で何回もデータベースに接続しなおします。(例えば、再接続のために手動による (パスワードの) 入力が必要である場合など) この処理が好まれない場合は、このオプションを使用して、pg_restore が再接続要求を発行しないようにすることができます。(プレインテキストモードでは、データベース未接続の場合の接続要求は psql \connect コマンドを発行することで実現しています。) しかし、このオプションはどちらかといえばナマクラ道具です。 -X use-set-session-authorization オプションを使用しない 限り、これにより pg_restore は全てのオブジェクトの所有権情報を失ってしまうからです。

-s
--schema-only

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

-S username
--superuser=username

トリガを使用不可能にする場合に使用する、スーパユーザのユーザ名を指定します。 これは --disable-triggers を使用する場合にのみ該当します。

-t table
--table=table

table 用のスキーマとデータのみをリストアします。

-T trigger
--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 でスーパーユーザを指定するか、あるいは推奨される方法として --use-set-session-authorization を指定し、その後 PostgreSQL スーパユーザとして pg_restore を実行する必要があります。

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

-h host
--host=host

サーバが稼働しているマシンのホスト名を指定します。ホスト名がスラッシュから始まる場合、Unix ドメインソケット用のディレクトリとして使用されます。

-p port
--port=port

サーバが接続を監視するインターネット TCP/IP ポートもしくは Unix ドメインソケットファイルの拡張子を指定します。ポート番号のデフォルトは 5432、もしくは、(設定されている場合) 環境変数 PGPORT の値となります。

-U username

指定したユーザとして接続します。

-W

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

環境

PGHOST
PGPORT
PGUSER

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

診断

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_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

履歴

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

関連項目

pg_dump, pg_dumpall, psql, PostgreSQL 管理者用ガイド