★PostgreSQLカンファレンス2024 12月6日開催/チケット販売中★
他のバージョンの文書 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

pg_restore

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

概要

pg_restore [connection-option...] [option...] [filename]

説明

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

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

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

オプション

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

filename

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

-a
--data-only

データのみをリストアし、スキーマ(データ定義)はリストアしません。 アーカイブ内にある、テーブルデータ、ラージオブジェクト、シーケンス値がリストアされます。

このオプションは--section=dataを指定することと似ていますが、歴史的な理由により同一ではありません。

-c
--clean

再作成前にデータベースオブジェクトを整理(削除)します。 (--if-existsが使われなければ、対象のデータベースの中にオブジェクトがない場合に、害のないメッセージをいくつか出力するかもしれません。)

-C
--create

リストア前にデータベースを作成します。 --cleanも同時に指定されている場合、接続する前に対象データベースを削除し再作成します。

--createでは、pg_restoreは、もしあるならデータベースのコメントもリストアします。また、あらゆる設定変数の当データベースに対する設定、すなわち、このデータベースを対象にしたALTER DATABASE ... SET ...ALTER ROLE ... IN DATABASE ... SET ...コマンドもリストアします。 --no-aclが指定されていない限り、データベース自体に対するアクセス権限もリストアされます。

このオプションがある場合、-dで指定したデータベースは最初のDROP DATABASECREATE DATABASEコマンドの発行時にのみ使用されます。 そして、すべてのデータはアーカイブ内に記述された名前のデータベースにリストアされます。

-d dbname
--dbname=dbname

dbnameデータベースに接続し、このデータベースに直接リストアします。 dbname接続文字列でも構いません。 その場合、接続文字列パラメータは衝突するコマンドラインオプションよりも優先します。

-e
--exit-on-error

データベースにSQLコマンドを送信中にエラーが発生した場合、処理を終了します。 デフォルトでは、処理を続行し、リストア処理の最後に発生したエラーの数を表示します。

-f filename
--file=filename

作成するスクリプト(-lを使用した場合はアーカイブの一覧)の出力ファイルを指定します。 stdout(標準出力)に出力するには-を使ってください。

-F format
--format=format

アーカイブの形式を指定します。 pg_restoreは形式を自動認識するので、このオプションは必須ではありません。 指定する値は以下のいずれかになります。

c
custom

アーカイブがpg_dumpのカスタム形式であることを表します。

d
directory

アーカイブがディレクトリアーカイブであることを表します。

t
tar

アーカイブがtarアーカイブであることを表します。

-I index
--index=index

指定したインデックスの定義のみをリストアします。 複数の-Iスイッチをつけることで複数のインデックスを指定できます。

-j number-of-jobs
--jobs=number-of-jobs

pg_restoreのもっとも時間がかかる部分、つまり、データのロード、インデックスの作成、制約の作成部分を最大number-of-jobsの並行セッションを使用して実行します。 このオプションは、複数プロセッサマシンで稼働するサーバに大規模なデータベースをリストアする時間を劇的に減らすことができます。 データベースサーバに直接接続するのではなくスクリプトを生成する場合には、このオプションは無視されます。

各ジョブは1プロセスまたは1スレッド(オペレーティングシステムに依存)です。 各ジョブはサーバへの別々の接続を使用します。

このオプションの最適値はサーバ、クライアント、ネットワークのハードウェア構成に依存します。 要素にはCPUコア数やディスク構成も含まれます。 試行する最初の値としてサーバのCPUコア数を勧めます。 しかし、多くの場合これより大きな値でもリストア時間を高速化することができます。 当然ながらあまりに大きな値を使用すると、スラッシングのために性能が劣化することになります。

カスタムアーカイブ書式およびディレクトリアーカイブ書式のみがこのオプションをサポートします。 入力ファイルは通常のファイルまたはディレクトリでなければなりません(例えばパイプや標準入力はいけません)。 また、複数ジョブは--single-transactionオプションといっしょに使用することはできません。

-l
--list

アーカイブの内容を一覧表として出力します。 このコマンドが出力する一覧は、-Lオプションに対する入力として使用することができます。 -n-tなどのフィルタオプションを-lといっしょに使用すると、一覧出力する項目が制限されます。

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

list-file内で指定したアーカイブ要素のみをリストアします。 また、それらはそのファイルの出現順にリストアされます。 -n-tなどのフィルタオプションを-Lといっしょに使用すると、リストアする項目がさらに制限されます。

list-fileは通常、事前に行った-l操作の出力を編集して作成されます。 行の移動や削除、または、行の先頭にセミコロン(;)を付けてコメントアウトすることが可能です。 後述の例を参照してください。

-n schema
--schema=schema

指定されたスキーマ内のオブジェクトのみをリストアします。 複数の-nスイッチをつけることで複数のスキーマを指定できます。 これは特定のテーブルのみをリストアするために-tオプションと組み合わせることができます。

-N schema
--exclude-schema=schema

指定したスキーマ内にあるオブジェクトをリストアしません。 -Nオプションを複数回指定することで、複数のスキーマを除外することができます。

同じスキーマ名が-n-Nの両方で指定された場合は、-Nオプションが優先し、そのスキーマは除外されます。

-O
--no-owner

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

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

指定した関数のみをリストアします。 関数や引数の名前は、ダンプファイルの一覧で出力される通りのスペルで正確に入力するよう注意してください。 複数の-Pスイッチをつけることで複数の関数を指定できます。

-R
--no-reconnect

このオプションは廃止されました。後方互換性を保持するために受け入れられています。

-s
--schema-only

アーカイブ内にあるスキーマ項目の範囲でスキーマ(データ定義)のみをリストアし、データ(テーブルの内容)をリストアしません。

このオプションは--data-onlyの逆です。 このオプションは--section=pre-data --section=post-dataを指定することと似ていますが、歴史的な理由により同一ではありません。

(これと--schemaオプションと混同しないでください。schemaという単語を異なる意味で使用しています。)

-S username
--superuser=username

トリガを無効にする場合に使用する、スーパーユーザのユーザ名を指定します。 これは--disable-triggersを使う場合にのみ使用されます。

-t table
--table=table

指定されたテーブルのみについて、定義、データまたはその両方をリストアします。 この目的において、テーブルにはビュー、マテリアライズドビュー、シーケンス、外部テーブルが含まれます。 複数の-tスイッチを指定することで複数のテーブルを指定することができます。 -nオプションと組み合わせることでスキーマを指定することができます。

注記

-tが指定された場合、pg_restoreは選択されたテーブルが依存するその他のデータベースオブジェクトについてリストアしようとはしません。 そのため、初期化されたデータベースに特定のテーブルをリストアすることが成功する保証はありません。

注記

このフラグはpg_dump-tフラグと同じ動作をするわけではありません。 現在のところ、pg_restoreでワイルドカードマッチを提供する予定はありませんし、-tでスキーマ名を含めることもできません。 加えて、pg_dump-tフラグは選択されたテーブルの(インデックスなどの)従属オブジェクトもダンプしますが、pg_restore-tフラグではそのような従属オブジェクトを含めません。

注記

PostgreSQLの9.6より前のバージョンでは、このフラグはテーブルにのみマッチし、その他の種類のリレーションとはマッチしませんでした。

-T trigger
--trigger=trigger

指定されたトリガだけをリストアします。 複数の-Tスイッチをつけることで、複数のトリガを指定できます。

-v
--verbose

冗長モードを指定します。 これを指定すると、pg_restoreは詳細なオブジェクトコメント、開始時刻と終了時刻を出力ファイルに、進行メッセージを標準エラーに出力するようになります。 オプションを繰り返すと、追加のデバッグレベルメッセージが標準エラーに現れます。

-V
--version

pg_restoreのバージョンを表示し、終了します。

-x
--no-privileges
--no-acl

アクセス権限(grant/revokeコマンド)のリストアを行いません。

-1
--single-transaction

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

--disable-triggers

このオプションは、データのみのダンプからリストアする際にしか適用されません。 データのリストア中、pg_restoreに対し、対象テーブル上のトリガを一時的に無効にするコマンドを実行するよう指示します。 このオプションは、データのリストア中には呼び出したくない参照整合性検査やその他のトリガがある場合に使用します。

現在のところ、--disable-triggersが生成するコマンドを実行するのは、スーパーユーザでなければなりません。 そのため、-Sでスーパーユーザの名前を指定するか、あるいは、可能であれば、PostgreSQLのスーパーユーザ権限でpg_restoreを実行する必要があります。

--enable-row-security

このオプションは、行セキュリティのあるテーブルの内容をリストアするときにのみ意味を持ちます。 デフォルトではpg_restorerow_securityをoffに設定し、すべてのデータが確実にテーブルにリストアされるようにします。 ユーザが行セキュリティを回避できるだけの十分な権限がないときはエラーが発生します。 このパラメータはpg_restorerow_securityをonに設定するようにし、ユーザが行セキュリティが有効なテーブルの内容をリストアできるようにします。 それでも、ユーザがダンプからテーブルに行を挿入する権限を持っていなければ、これは失敗します。

COPY FROMは行セキュリティをサポートしないので、このオプションは今のところ、ダンプがINSERT形式である必要があることに注意してください。

--if-exists

データベースオブジェクトを削除するときに、条件コマンドを使います(つまりIF EXISTS句を追加します)。 このオプションは、--cleanも指定されているのでなければ有効にはなりません。

--no-comments

たとえアーカイブにコメントが含まれていても、コメントをリストアするコマンドを出力しません。

--no-data-for-failed-tables

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

このオプションは直接データベースにリストアする時にのみ有効で、SQLスクリプト出力を生成する時は無効です。

--no-publications

アーカイブにパブリケーションが含まれていたとしても、それをリストアするコマンドを出力しません。

--no-security-labels

アーカイブにセキュリティラベルが含まれている場合であっても、セキュリティラベルを戻すコマンドを出力しません。

--no-subscriptions

アーカイブにサブスクリプションが含まれていたとしても、それをリストアするコマンドを出力しません。

--no-tablespaces

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

--section=sectionname

指定された部分のみをリストアします。 部分名はpre-datadatapost-dataのいずれかを取ることができます。 複数の部分を選択するために、このオプションを複数指定することができます。 デフォルトではすべての部分をリストアします。

data部分には、実際のテーブルデータやラージオブジェクト定義が含まれます。 post-data項目は、インデックス定義、トリガ定義、ルール定義、有効化された検査制約以外の制約定義から構成されます。 pre-data項目は、他のすべてのデータ定義項目から構成されます。

--strict-names

スキーマ指定(-n/--schema)およびテーブル指定(-t/--table)がバックアップファイル内の少なくとも1つのスキーマあるいはテーブルにマッチすることを必要とします。

--use-set-session-authorization

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

-?
--help

pg_restoreコマンドライン引数の使用方法を表示し、終了します。

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

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

PG_COLOR

診断メッセージで色を使うかどうかを指定します。 可能な値はalwaysautoneverです。

また、このユーティリティは、他のほとんどのPostgreSQLユーティリティと同様、libpqでサポートされる環境変数を使用します(34.15を参照してください)。 しかしデータベース名が指定されていない場合はPGDATABASEは読み取られません。

診断

-dオプションによってデータベースに直接接続するよう指定されている場合、pg_restoreは内部でSQL文を実行します。 pg_restoreの実行時に問題が発生する場合は、psqlなどを使用して、そのデータベースから情報を選択できることを確認してください。 また、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の文書も参照してください。

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

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 Mon Sep 14 13:55:39 2009
;     dbname: DBDEMOS
;     TOC Entries: 81
;     Compression: 9
;     Dump Version: 1.10-0
;     Format: CUSTOM
;     Integer: 4 bytes
;     Offset: 8 bytes
;     Dumped from database version: 8.3.5
;     Dumped by pg_dump version: 8.3.8
;
;
; Selected TOC Entries:
;
3; 2615 2200 SCHEMA - public pasha
1861; 0 0 COMMENT - SCHEMA public pasha
1862; 0 0 ACL - public pasha
317; 1247 17715 TYPE public composite pasha
319; 1247 25899 DOMAIN public domain0 pasha

セミコロンで始まる行はコメントです。 行の先頭の番号は、各アイテムに割り当てられた内部アーカイブ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, pg_dumpall, psql