pg_dump — PostgreSQLデータベースをスクリプトファイルまたは他のアーカイブファイルへ抽出する
pg_dump
[connection-option
...] [option
...] [dbname
]
pg_dumpはPostgreSQLデータベースをバックアップするユーティリティです。 データベースを使用中であっても一貫性のあるバックアップを作成することができます。 pg_dumpは他のユーザによるデータベースへのアクセス(読み書き)をブロックしません。
pg_dumpは単一のデータベースしかダンプしません。 クラスタ全体、あるいは、クラスタ内の全データベースに共通のグローバルオブジェクト(ロールやテーブル空間など)をダンプするにはpg_dumpallを使用してください。
ダンプはスクリプト形式、または、アーカイブファイル形式で出力することができます。 スクリプトダンプは、保存した時点の状態のデータベースを再構成するために必要なSQLコマンドが書き込まれた平文ファイルです。 このスクリプトを使ってリストアを行うには、それをpsqlに読み込ませます。 スクリプトファイルを使えば、ダンプを行ったのとは別のマシンや別のアーキテクチャ上でも、データベースを再構築することができます。 また、多少編集すれば他のSQLデータベース製品上でもデータベースの再構築が可能です。
もう1つの形式であるアーカイブファイル形式を使ってデータベースを再構築するには、pg_restoreを使用しなければなりません。 このファイルを使用すると、pg_restoreがリストア対象を選択したり、リストアするアイテムを並び替えたりできます。 アーカイブファイルもまた、アーキテクチャを越えて移植できるように設計されています。
いずれかのアーカイブファイル形式をpg_restoreと組み合わせて使用する場合は、pg_dumpの柔軟なアーカイブ/転送機構が利用できます。
具体的には、pg_dumpを使用してデータベース全体をバックアップし、pg_restoreを使用して、アーカイブの内容を検査したり、データベースの一部を選択してリストアしたりすることができます。
最も柔軟な出力ファイル形式は「カスタム」形式(-Fc
)と「ディレクトリ」形式(-Fd
)です。
これらはすべての保存された項目の選択や並び換えを行うことができ、並行リストアをサポートし、デフォルトで圧縮されます。
「ディレクトリ」形式は、並行ダンプをサポートする唯一の形式です。
pg_dumpの実行中は、標準エラーに出力される警告(特に後述の制限に関する警告)が出力されていないか確認してください。
以下のコマンドラインオプションは出力内容とその形式を制御します。
dbname
ダンプするデータベースの名前を指定します。
指定されていない場合は環境変数PGDATABASE
が使われます。
この変数も設定されていない場合は、接続のために指定されたユーザ名が使用されます。
-a
--data-only
データのみをダンプし、スキーマ(データ定義)はダンプしません。 テーブルデータ、ラージオブジェクト、シーケンス値がダンプされます。
このオプションは--section=data
を指定することと似ていますが、歴史的な理由で同一ではありません。
-b
--blobs
ラージオブジェクトをダンプに含めます。
--schema
、--table
、--schema-only
が指定された場合を除き、これがデフォルトの動作です。
したがって、-b
オプションは特定のスキーマやテーブルのダンプにラージオブジェクトを追加する場合にのみ有用です。
blobはデータとみなされるため、--data-only
が使われたときは含まれますが、--schema-only
が使われたときには含まれないことに注意してください。
-B
--no-blobs
ラージオブジェクトをダンプに含めません。
-b
と-B
の両方が指定された場合は、データのダンプ時にラージオブジェクトを出力します。
-b
の説明を参照してください。
-c
--clean
データベースオブジェクトを作成するコマンドの前に、データベースオブジェクトを整理(削除)するコマンドを書き出します。
(--if-exists
も指定されなければ、リストア先のデータベースの中に存在しないオブジェクトがある場合に、害がないエラーがいくつか発生するかもしれません。)
このオプションはアーカイブ(テキストでない)出力ファイルを出力する場合には無視されます。
アーカイブ形式では、pg_restore
を呼び出す時にこのオプションを指定できます。
-C
--create
初めにデータベース自体を作成するコマンドを出力し、その後、作成したデータベースに接続するコマンドを出力します
(このようなスクリプトを使用すると、スクリプトを実行する前に対象のインストレーションの中のどのデータベースに接続すればよいかという問題を考える必要がなくなります)。
--clean
も同時に指定されている場合、このスクリプトは接続する前に対象データベースを削除し再作成します。
--create
では出力に、もしあるならデータベースのコメントも含まれます。また、あらゆる設定変数の設定、すなわち、このデーベースを対象としているALTER DATABASE ... SET ...
とALTER ROLE ... IN DATABASE ... SET ...
コマンドも含まれます。
--no-acl
が指定されていない限り、データベースに対するアクセス権限自体もダンプされます。
このオプションはアーカイブ(テキストでない)出力ファイルを出力する場合には無視されます。
アーカイブ形式では、pg_restore
を呼び出す時にこのオプションを指定できます。
-e pattern
--extension=pattern
pattern
にマッチする拡張のみをダンプします。
このオプションが指定されなければ、対象データベース内にあるシステム以外の拡張すべてがダンプされます。
複数の-e
オプションを記述することで、複数の拡張を選択できます。
pattern
パラメータはpsqlの\d
コマンドと同じ規則に従うパターン(Patterns参照)として解釈されます。ですので、ワイルドカード文字をパターン内に記述することで、複数の拡張を選択することもできます。
ワイルドカードを使用する時は、シェルがそのワイルドカードを展開しないように、必要であればパターンを引用符で括ってください。
pg_extension_config_dump
により登録された設定リレーションは、その拡張が--extension
で指定されていればダンプに含まれます。
-e
が指定されると、pg_dumpは選択した拡張が依存する可能性のある、その他のデータベースオブジェクトのダンプを行ないません。
したがって、拡張指定のダンプ結果を初期状態のデータベースに正常にリストアできるという保証はありません。
-E encoding
--encoding=encoding
指定した文字セット符号化方式でダンプを作成します。
デフォルトではダンプはデータベースの符号化方式で作成されます。
(環境変数PGCLIENTENCODING
を好みのダンプ時の符号化方式に設定することで、同じ結果を得ることができます。)
サポートする符号化方式は24.3.1に記載されています。
-f file
--file=file
出力を指定のファイルに送ります。
ファイルを基にする出力形式ではこのパラメータは省くことができます。
省略時は標準出力が使用されます。
しかしディレクトリ出力形式の場合は、省略することはできず、ファイルではなく対象ディレクトリを指定します。
この場合、ディレクトリはpg_dump
が生成しますので、事前に存在してはなりません。
-F format
--format=format
出力形式を選択します。
format
には以下のいずれかを取ることができます。
p
plain
平文のSQLスクリプトファイルを出力します(デフォルト)。
c
custom
pg_restoreへの入力に適したカスタム形式アーカイブを出力します。 ディレクトリ出力形式と一緒に使用する場合、リストア時に手作業で保管された項目の選択、再順序付けできますので、これはもっとも柔軟な出力形式です。 また、この形式はデフォルトで圧縮されます。
d
directory
pg_restoreへの入力に適したディレクトリ形式のアーカイブを出力します。 これは、ダンプされる各テーブルおよびblobごとに1つのファイル、さらに、pg_restoreから読み取り可能な、機械的に読み取り易い書式でダンプしたオブジェクトを記述する目次ファイルと呼ばれるファイルを持つディレクトリを作成します。 ディレクトリ形式アーカイブは標準Unixツールで操作することができます。 例えば、未圧縮アーカイブ内のファイルをgzipツールを使用して圧縮することができます。 この形式はデフォルトで圧縮されます。 また並行ダンプをサポートします。
t
tar
pg_restoreへの入力に適したtar
形式のアーカイブを出力します。
このtar形式はディレクトリ形式と互換性があります。
tar形式アーカイブを展開すると、有効なディレクトリ形式のアーカイブを生成します。
しかしtar形式は圧縮をサポートしません。
またtar形式を使う場合、リストア時にテーブルデータ項目の相対的な順序を変更することはできません。
-j njobs
--jobs=njobs
njobs
個のテーブルを同時にダンプすることによって、並行してダンプを実行します。
このオプションはダンプを実行するのに必要な時間を減らすかもしれませんが、データベースサーバの負荷を増やします。
このオプションはディレクトリ出力形式でのみ使用することができます。
複数のプロセスが同時にそのデータを書き出すことができるのはディレクトリ形式だけだからです。
pg_dumpはnjobs
+1個のデータベース接続を開きます。
このため、すべての接続を収容できる程度にmax_connectionsが高いことを確認してください。
並行ダンプを実行している時にデータベースオブジェクトに対して排他ロックを要求すると、ダンプが失敗する可能性があります。
ダンプ実行中に誰かがダンプ予定のオブジェクトを削除してそれがなくなってしまうことがないように、ワーカプロセスがダンプする予定のオブジェクトに対してpg_dumpのリーダープロセスが共有ロック(ACCESS SHARE)を要求するのがその理由です。
その後他のクライアントがテーブルに対する排他ロックを要求すると、
そのロックは許可されませんが、リーダープロセスが共有ロックを解放することを待機するキューに保管されます。
その結果、テーブルへのその他のアクセスは許可されず、排他ロック要求の後のキューに保管されます。
これには、そのテーブルをダンプしようとする作業用プロセスも含まれます。
何らかの注意をしないと、古典的なデッドロック状態になります。
この競合を検知するためにpg_dumpの作業用プロセスはNOWAIT
オプションを使用する別の共有ロックを要求します。
作業用プロセスによる共有ロックが許可されない場合、だれかがその時に排他ロックを要求していることになり、ダンプを継続することができません。
pg_dumpには、ダンプを中断するしか選択肢がありません。
一貫したバックアップのためには、データベースサーバは、同期スナップショットをサポートする必要があります。
これはプライマリサーバについてはPostgreSQL 9.2で、スタンバイについてはバージョン10で導入された機能です。
この機能を用いれば、データベースクライアントは異なる接続を使用していたとしても、確実に同じデータセットを参照することができます。
pg_dump -j
は複数のデータベース接続を使用します。
リーダープロセスで一度、また、作業用ジョブそれぞれでも一度、データベースと接続します。
同期スナップショット機能がないと、異なる作業用ジョブがそれぞれの接続で同じデータを参照していることが保証されず、一貫性がないバックアップになってしまいます。
9.2より前のサーバで並行ダンプを実行させたいのであれば、データベースの内容が、リーダーがデータベースに接続してから最後の作業用ジョブがデータベースに接続するまでの間に変更されないことを確実にしなければなりません。
このためのもっとも簡単な方法は、バックアップを始める前にデータを変更するプロセス(DDLおよびDML)がデータベースにアクセスすることを止めさせることです。
また、9.2より前のPostgreSQLに対してpg_dump -j
を実行する場合は--no-synchronized-snapshots
パラメータを指定する必要もあります。
-n pattern
--schema=pattern
pattern
にマッチするスキーマのみをダンプします。
これはスキーマ自体とそこに含まれるオブジェクトすべてを選択します。
このオプションが指定されなければ、対象データベース内にあるシステム以外のスキーマ全てがダンプされます。
複数の-n
オプションを記述することで、複数のスキーマを選択することができます。
pattern
パラメータはpsqlの\d
コマンドと同じ規則に従うパターン(下記のPatterns参照)として解釈されます。
ですので、ワイルドカード文字をパターン内に記述することで、複数のスキーマを選択することもできます。
ワイルドカードを使用する時は、シェルがそのワイルドカードを展開しないように、必要であればパターンを引用符で括ってください。
Examplesを参照してください。
-n
が指定されると、pg_dumpは選択したスキーマ内のオブジェクトが依存する可能性がある、その他のデータベースオブジェクトのダンプを行いません。
したがって、スキーマ指定のダンプ結果を初期状態のデータベースに正常にリストアできるという保証はありません。
-n
が指定されると、blobなどの非スキーマオブジェクトはダンプされません。
--blobs
オプションをつけてダンプを行うことでblobも追加されます。
-N pattern
--exclude-schema=pattern
pattern
にマッチするスキーマをダンプしません。
このパターンは-n
と同様の規則に従って解釈されます。
-N
を複数指定して、複数のパターンのいずれかにマッチするスキーマを除外することができます。
-n
と-N
の両方が指定された場合、少なくとも1つの-n
にマッチし-N
オプションにマッチしないスキーマだけがダンプされます。
-n
なしで-N
が指定された場合、-N
にマッチするスキーマが通常のダンプから除外されます。
-O
--no-owner
オブジェクトの所有権を元のデータベースにマッチさせるためのコマンドを出力しません。
デフォルトでは、pg_dumpは、ALTER OWNER
文またはSET SESSION AUTHORIZATION
文を発行して、作成したデータベースオブジェクトの所有権を設定します。
スーパーユーザ(もしくは、そのスクリプト内の全てのオブジェクトを所有するユーザ)以外のユーザがスクリプトを実行した場合、これらの文は失敗します。
任意のユーザがリストアできるスクリプトを作成するには、-O
を指定してください。
ただし、この場合は、全てのオブジェクトの所有者がリストアしたユーザとなってしまいます。
このオプションはアーカイブ(テキストでない)出力ファイルを出力する場合には無視されます。
アーカイブ形式では、pg_restore
を呼び出す時にこのオプションを指定できます。
-R
--no-reconnect
このオプションは廃止されましたが、後方互換性を保持するため受け入れられます。
-s
--schema-only
データ定義(スキーマ)のみをダンプし、データはダンプしません。
このオプションは--data-only
の逆です。
これは--section=pre-data --section=post-data
を指定することと似ていますが、歴史的な理由のため同一ではありません。
(これと--schema
オプションと混乱しないでください。「schema」という単語を異なる意味で使用しています。)
データベース内の一部のみのテーブルのテーブルデータを除外するためには--exclude-table-data
を参照してください。
-S username
--superuser=username
トリガを無効にする場合に使用する、スーパーユーザのユーザ名を指定します。
これは--disable-triggers
を使う場合にのみ使用されます。
(通常は このオプションを使うよりも、出力されたスクリプトをスーパーユーザ権限で実行する方が良いでしょう。)
-t pattern
--table=pattern
pattern
にマッチする名前のテーブルのみをダンプします。
複数の-t
オプションを記述することで複数のテーブルを選択することができます。
pattern
パラメータはpsqlの \d
コマンドで使用される規則(下記のPatterns参照)と同じ規則に従うパターンとして解釈されます。
ですので、ワイルドカード文字をパターン内に記述することで、複数のテーブルを選択することもできます。
ワイルドカードを使用する時は、シェルによりそのワイルドカードを展開させないように、パターンを引用符で括ってください。
下記のExamplesを参照してください。
このオプションは、テーブルだけでなく、ビュー、マテリアライズドビュー、外部テーブル、シーケンスの定義をダンプするのにも使えます。
ビューやマテリアライズドビューの内容はダンプしませんし、対応する外部サーバに--include-foreign-data
が指定されている場合にのみ、外部テーブルの内容がダンプされます。
-t
が使用されると、-n
および-N
オプションの効果はなくなります。
-t
で選択したテーブルが、これらのオプションとは関係なくダンプされ、また、非テーブルオブジェクトはダンプされないためです。
-t
が指定されると、pg_dumpは選択したテーブル内のオブジェクトが依存する可能性がある他のデータベースオブジェクトのダンプを行いません。
したがって、テーブル指定のダンプ結果を初期化されたデータベースに正常にリストアできるという保証はありません。
-T pattern
--exclude-table=pattern
pattern
にマッチするテーブルをダンプしません。
このパターンは-t
と同じ規則に従って解釈されます。
-T
を複数指定することで、複数のパターンのいずれかにマッチするテーブルをすべて除外させることができます。
-t
と-T
の両方が指定された場合、少なくとも1つの-t
オプションにマッチし、-T
オプションにマッチしないテーブルのみがダンプされます。
-t
なしで-T
が指定された場合、通常のダンプから-T
にマッチするテーブルが除外されます。
-v
--verbose
冗長モードを指定します。 これを指定すると、pg_dumpは、詳細なオブジェクトコメント、開始時刻、終了時刻をダンプファイルに、進行状況メッセージを標準エラーに出力します。 オプションを繰り返すと、追加のデバッグレベルメッセージが標準エラーに現れます。
-V
--version
pg_dumpのバージョンを表示し、終了します。
-x
--no-privileges
--no-acl
アクセス権限(grant/revokeコマンド)のダンプを抑制します。
-Z 0..9
--compress=0..9
使用する圧縮レベルを指定します。 ゼロは圧縮無しを意味します。 カスタムおよびディレクトリアーカイブ形式では、これは個々のテーブルデータセグメントの圧縮を指定するもので、デフォルトでは中間レベルで圧縮されます。 平文出力では、非ゼロの圧縮レベルの指定によりあたかもgzipに渡されたかのように出力ファイル全体が圧縮されます。 しかしデフォルトは圧縮無しです。 tarアーカイブ形式では現在圧縮を全くサポートしていません。
--binary-upgrade
このオプションは現位置でのアップグレード用のユーティリティにより使用されるものです。 他の目的での使用は推奨されませんし、サポートもされません。 このオプションの動作は、将来通知することなく変更される可能性があります。
--column-inserts
--attribute-inserts
明示的に列名を付けたINSERT
コマンド(INSERT INTO
)としてデータをダンプします。
これによりリストアは非常に遅くなります。
主にPostgreSQL以外のデータベースへロード可能なダンプを作成する時に有用です。
リストア中のエラーでは、テーブルの内容がまるごと失われることはなく、問題のあるtable
(column
, ...)VALUES...INSERT
の一部の行が失われるだけです。
--disable-dollar-quoting
このオプションは、関数本体用のドル引用符の使用を無効にし、強制的に標準SQLの文字列構文を使用した引用符付けを行います。
--disable-triggers
このオプションは、データのみのダンプを作成する場合にしか適用されません。 データのリストア中に、対象テーブル上のトリガを一時的に無効にするコマンドを出力するようpg_dumpに指示します。 このオプションは、データのリストア中には呼び出したくない参照整合性検査やその他のトリガがテーブル上にある場合に使用します。
現在のところ、--disable-triggers
に対応するコマンドを実行するのは、スーパーユーザでなければなりません。
そのため、-S
でスーパーユーザの名前を指定するか、あるいは、可能であれば、スーパーユーザ権限でスクリプトを開始するよう注意する必要があります。
このオプションはアーカイブ(テキストでない)出力ファイルを出力する場合には無視されます。
アーカイブ形式では、pg_restore
を呼び出す時にこのオプションを指定できます。
--enable-row-security
このオプションは、行セキュリティのあるテーブルの内容をダンプするときにのみ意味を持ちます。 デフォルトでは、pg_dumpはrow_securityをoffに設定し、テーブルからすべてのデータがダンプされるようにします。 ユーザが行セキュリティを無視できるだけの十分な権限を持っていない場合、エラーが発生します。 このパラメータはpg_dumpがrow_securityをonに設定するようにすることで、テーブルの内容のうち、ユーザがアクセスできる部分をダンプすることを可能にします。
リストア時のCOPY FROM
が行セキュリティをサポートしていないので、今、このオプションを使う場合は、ダンプをINSERT
形式にするのがおそらく望ましいでしょう。
--exclude-table-data=pattern
pattern
にマッチするすべてのテーブルのデータをダンプしません。
パターンは-t
用の規則と同じ規則にしたがって解釈されます。
複数のパターンのいずれかにマッチするテーブルを除外することができるように、--exclude-table-data
を複数回与えることができます。
このオプションは、特定のテーブルに関してデータを格納する必要はないがテーブル定義は必要である場合に有用です。
データベース内のすべてのテーブルに関してデータを除外するためには、--schema-only
を参照してください。
--extra-float-digits=ndigits
浮動小数点データをダンプする時に、利用できる最大の精度の代わりに、extra_float_digits
で指定された値を使います。
バックアップ目的で作られたダンプルーチンは、このオプションを使うべきではありません。
--if-exists
データベースオブジェクトを初期化するときに、条件コマンドを使います(つまり、IF EXISTS
句を追加します)。
このオプションは、--clean
も指定されているのでなければ、有効にはなりません。
--include-foreign-data=foreignserver
foreignserver
パターンとマッチする外部サーバの外部テーブルのデータをダンプします。
複数の--include-foreign-data
スイッチを書くことで、複数の外部サーバを選択できます。
また、foreignserver
パラメータはpsqlの\d
コマンドで使われているのと同じ規則に従うパターンとして解釈されます(下記のPatternsを参照してください)ので、パターンにワイルドカード文字を書くことで複数の外部サーバを選択することもできます。
ワイルドカードを使う時は、シェルがワイルドカードを展開しないよう必要ならパターンを引用符で囲むことに注意してください。下記のExamplesを参照してください。
唯一の例外は空のパターンが許されていないことです。
--include-foreign-data
が指定された場合、pg_dumpは外部テーブルが書き込み可能かどうか確認しません。
そのため、外部テーブルのダンプの結果をリストアするのに成功する保証はありません。
--inserts
データを(COPY
ではなく)INSERT
コマンドの形式でダンプします。
これを行うとリストアに非常に時間がかかります。
主にPostgreSQL以外のデータベースへロード可能なダンプを作成する時に有用です。
リストア中のエラーでは、テーブルの内容がまるごと失われることはなく、問題のあるINSERT
の一部の行が失われるだけです。
列の順序を変更した場合はリストアが失敗する可能性があることに注意してください。
--column-inserts
はさらに処理が遅くなりますが、列の順序変更に対して安全です。
--load-via-partition-root
テーブルパーティションのデータをダンプするときには、COPY
あるいはINSERT
文の対象を、そのパーティションではなく、それを含むパーティション階層のルートにします。
これにより、データが読み込まれるときに各行に対して適切なパーティションが再判断されます。
これは行が元のサーバ上と同じパーティションに必ずしも落ちないようなサーバ上にデータを再読み込みするときに有用でしょう。
例えば、パーティション列がtext型で二つのシステムがパーティション列のソートで使われる照合順序の異なる定義を持っている場合に、これはあり得ます。
pg_restoreは与えられたアーカイブデータ要素がデータを投入するパーティションがどれであるかを正確に知ることがないため、このオプションで作られたアーカイブからリストアを行うときには並列化しない方が良いです。 並行ジョブ間でのロック競合のため、これは非効率になります。また、全ての関連データが読み込まれる前に外部キー制約が設定されることにより、場合によってはリロード失敗も起こります。
--lock-wait-timeout=timeout
ダンプの開始時に共有テーブルのロックを永遠に待ちません。
代わりに指定したtimeout
内にテーブルロックを獲得できなければ失敗します。
タイムアウトはSET statement_timeout
で受け付けられる任意の書式で指定できます。
(使用可能な形式はダンプの元となるサーバのバージョンに依存して異なりますが、すべてのバージョンにおいてミリ秒単位の整数値は受け付けられます。)
--no-comments
コメントをダンプしません。
--no-publications
パブリケーションをダンプしません。
--no-security-labels
セキュリティラベルをダンプしません。
--no-subscriptions
サブスクリプションをダンプしません。
--no-sync
デフォルトでは、pg_dump
はすべてのファイルが確実にディスクに書き出されるまで待機します。
このオプションを使うとpg_dump
は待機せずに戻るため、より高速になりますが、これは、その後にオペレーティングシステムがクラッシュすると、ダンプが破損する可能性があることを意味します。
一般的に言って、このオプションはテスト用には有用ですが、実運用の環境からデータをダンプするときには使用しない方が良いでしょう。
--no-synchronized-snapshots
このオプションにより、9.2より前のサーバに対してpg_dump -j
を実行することができます。
詳細については-j
パラメータの説明を参照してください。
--no-tablespaces
テーブル空間を選択するコマンドを出力しません。 このオプションを使用すると、すべてのオブジェクトはリストア時のデフォルトのテーブル空間の中に作成されます。
このオプションはアーカイブ(テキストでない)出力ファイルを出力する場合には無視されます。
アーカイブ形式では、pg_restore
を呼び出す時にこのオプションを指定できます。
--no-toast-compression
TOAST圧縮手法を設定するコマンドを出力しません。 このオプションにより、列はすべてデフォルトの圧縮の設定でリストアされます。
--no-unlogged-table-data
ログを取らないテーブルの内容をダンプしません。 このオプションはテーブル定義(スキーマ)をダンプするかどうかには影響しません。 そのテーブルデータのダンプを抑制するだけです。 スタンバイサーバからダンプを行う場合、ログを取らないテーブル内のデータは常に除外されます。
--on-conflict-do-nothing
INSERT
コマンドにON CONFLICT DO NOTHING
を追加します。
このオプションは、--inserts
、--column-inserts
または--rows-per-insert
が同時に指定されていなければ、有効ではありません。
--quote-all-identifiers
強制的にすべての識別子に引用符を付与します。
このオプションは、pg_dumpのメジャーバージョンとは異なるメジャーバージョンのPostgreSQLのサーバーからデータベースをダンプするとき、あるいは出力を異なるメジャーバージョンのサーバにロードする予定であるときに推奨されます。
デフォルトでは、pg_dumpは、それ自身のメジャーバージョンにおける予約語である識別子に対してのみ引用符を付与します。
これは、他のバージョンのサーバを処理するときに互換性の問題を引き起こす場合があります。
他のバージョンのサーバでは予約語の集合が多少、異なる場合があるからです。
--quote-all-identifiers
を使用することで、ダンプのスクリプトが読みにくくなりますが、このような問題を防ぐことができます。
--rows-per-insert=nrows
(COPY
ではなく)INSERT
コマンドでデータをダンプします。
INSERT
コマンド1つあたりの最大行数を制御します。
指定する値は0より大きくなければなりません。
リストア中のエラーでは、テーブルの内容がまるごと失われることはなく、問題のあるINSERT
の一部の行が失われるだけです。
--section=sectionname
指定した部分のみをダンプします。
部分名はpre-data
、data
、post-data
のいずれかを取ることができます。
複数の部分を選択するために、このオプションは複数回指定することができます。
デフォルトではすべての部分をダンプします。
data部分には、実際のテーブルデータとラージオブジェクトの中身、シーケンス値が含まれます。 post-data項目は、インデックス定義、トリガ定義、ルール定義、有効化された検査制約以外の制約定義が含まれます。 pre-data項目は、他のすべてのデータ定義項目が含まれます。
--serializable-deferrable
使用されるスナップショットがその後のデータベース状態と一貫性を持つことを保証するために、ダンプ時にserializable
トランザクションを使用します。
ダンプが失敗したり、serialization_failure
により他のトランザクションがロールバックしたりする危険がないように、トランザクションストリーム内で異常が発生することがない時点まで待つことでこれを行います。
トランザクション分離および同時実行性の制御については第13章を参照してください。
このオプションは障害対策のリカバリのみを目的とするダンプでは利点はありません。 元のデータベースを継続して更新しながら、レポート処理や他の読み取りのみの負荷分散のためにデータベースのコピーをロードするために使用されるダンプとして有用になります。 こうしないと、ダンプには 何らかのトランザクションの直列実行が最終的にコミットされた状態と一貫性がない状態が反映される可能性があります。 例えば、バッチ処理技術が使用される場合、 バッチは、バッチ内で存在するすべての項目を持たないダンプ内でクローズしたものと表示される可能性があります。
pg_dumpを始めた時に読み書きを行う実行中のトランザクションが存在しない場合、このオプションは何の差異ももたらしません。 読み書きを行うトランザクションが実行中の場合、確定できない期間、ダンプの起動が遅延される可能性があります。 動き出してからの性能は、このスイッチがある場合とない場合とで違いはありません。
--snapshot=snapshotname
データベースのダンプを作成する時に、指定した同期スナップショットを使用します (詳しくは表 9.90を参照して下さい)。
このオプションは、ダンプを論理レプリケーションスロット(第49章参照)あるいは同時実行セッションと同期させる必要がある時に役に立ちます。
並行ダンプの場合、新しいスナップショットを作る代わりに、このオプションで指定されたスナップショット名が使われます。
--strict-names
各拡張指定(-e
/--extension
)、各スキーマ指定(-n
/--schema
)および各テーブル指定(-t
/--table
)が、ダンプされるデータベース内の少なくとも1つの拡張、スキーマおよびテーブルにマッチすることを必要とします。
拡張、スキーマおよびテーブル指定のどれもがマッチするものを見つけられなかった場合は、--strict-names
がなくてもpg_dumpはエラーを発生させることに注意して下さい。
このオプションは-N
/--exclude-schema
、-T
/--exclude-table
、--exclude-table-data
には影響を与えません。
除外のパターンがマッチするオブジェクトを見つけられないことは、エラーとはみなされません。
--use-set-session-authorization
オブジェクトの所有権を決定するために、ALTER OWNER
コマンドの代わりに標準SQLのSET SESSION AUTHORIZATION
コマンドを出力します。
これにより、ダンプの標準への互換性が高まりますが、ダンプ内のオブジェクトの履歴によっては正しくリストアされない可能性が生じます。
また、SET SESSION AUTHORIZATION
を使用したダンプを正しくリストアするためには、確実にスーパーユーザ権限が必要となります。
ALTER OWNER
で必要な権限はこれよりも少なくなります。
-?
--help
pg_dumpのコマンドライン引数の使用方法を表示し、終了します。
以下のコマンドラインオプションは、データベース接続パラメータを制御します。
-d dbname
--dbname=dbname
接続するデータベースの名前を指定します。
コマンドラインでオプション以外の最初の引数としてdbname
を指定することと同じです。
dbname
は接続文字列でも構いません。
その場合、接続文字列パラメータは衝突するコマンドラインオプションに優先します。
-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_dumpは強制的にパスワード入力を促します。
サーバがパスワード認証を要求する場合pg_dumpは自動的にパスワード入力を促しますので、これが重要になることはありません。
しかし、pg_dumpは、サーバにパスワードが必要かどうかを判断するための接続試行を無駄に行います。
こうした余計な接続試行を防ぐために-W
の入力が有意となる場合もあります。
--role=rolename
ダンプを作成する際に使用するロール名を指定します。
このオプションによりpg_dumpはデータベースに接続した後にSET ROLE
rolename
コマンドを発行するようになります。
認証に使用したユーザ(-U
で指定されたユーザ)がpg_dumpで必要とされる権限を持たないが、必要な権限を持つロールに切り替えることができる場合に有用です。
一部のインストレーションではスーパーユーザとして直接ログインさせないポリシーを取ることがありますが、このオプションを使用することでポリシーに反することなくダンプを作成することができます。
PGDATABASE
PGHOST
PGOPTIONS
PGPORT
PGUSER
デフォルトの接続パラメータです。
PG_COLOR
診断メッセージで色を使うかどうかを指定します。
可能な値はalways
、auto
、never
です。
また、このユーティリティは、他のほとんどのPostgreSQLユーティリティと同様、libpqでサポートされる環境変数を使用します(34.15を参照してください)。
pg_dumpは内部でSELECT
文を実行します。
pg_dumpの実行時に問題が発生する場合は、psqlなどを使用して、そのデータベースから情報をselectできることを確認してください。
また、libpqフロントエンドライブラリで使用されるデフォルトの接続設定や環境変数も適用されます。
通常pg_dumpのデータベースに対する活動は統計情報コレクタにより収集されます。
これを望まない場合、PGOPTIONS
またはALTER USER
コマンドを使用してtrack_counts
パラメータを偽に設定してください。
データベースクラスタにおいてtemplate1
データベースに対し独自の変更を行っている場合、pg_dumpの出力は、確実に空のデータベースにリストアするように注意してください。
そうしないと、おそらく追加されたオブジェクトの重複定義によってエラーが発生します。
独自の追加が反映されていない空のデータベースを作成するには、template1
ではなくtemplate0
をコピーしてください。
以下に例を示します。
CREATE DATABASE foo WITH TEMPLATE template0;
データのみのダンプを選択し、--disable-triggers
オプションを使用する場合、pg_dumpはデータを挿入する前にユーザテーブルにトリガを無効にするコマンドを発行し、データの挿入が完了した後で、それらを再び有効にする問い合わせを発行します。
リストアが途中で停止した場合、システムカタログが不適切な状態のままになっている可能性があります。
pg_dumpが生成するダンプファイルには、オプティマイザが問い合わせ計画を決定する際に使用される統計情報が含まれていません。
そのため、最適な性能を発揮するために、ダンプファイルからリストアした後でANALYZE
を実行することをお勧めします。
詳しくは25.1.3および25.1.6を参照してください。
pg_dumpは新しいバージョンのPostgreSQLへのデータ移行に使用されますので、pg_dumpの出力はpg_dumpのバージョンより新しいバージョンのPostgreSQLデータベースへロード可能と想定できるようになっています。
また、pg_dumpは自身より古いバージョンのPostgreSQLデータベースを読み取ることもできます。
(現在はバージョン8.0までのサーバをサポートします。)
しかし、pg_dumpはそれ自身のメジャーバージョンより新しいPostgreSQLサーバのダンプを取ることはできません。
無効なダンプを作成するリスクは取らず、ダンプしようとさえしません。
また、pg_dumpの出力がメジャーバージョンが古いサーバにロードできるとは、たとえ同じバージョンのサーバから取得したダンプであっても、保証されていません。
より古いサーバへのダンプファイルのロードには、古いサーバでは理解できない構文を削除するために、ダンプファイルの手作業による修正が必要になることがあります。
バージョンをまたがる場合は--quote-all-identifiers
オプションの使用が推奨されます。
これにより、PostgreSQLの異なるバージョンで、予約語のリストが変わることによって発生する問題を防ぐことができるからです。
論理レプリケーションのサブスクリプションをダンプするとき、pg_dumpはconnect = false
オプションを使用するCREATE SUBSCRIPTION
生成するため、サブスクリプションのリストア時には、レプリケーションスロットの作成や初回のテーブルコピーのためのリモート接続が行われません。
このため、リモートサーバへのネットワーク接続を必要とせずにダンプをリストアできます。
その後でサブスクリプションを適切な方法で再有効化するのはユーザの責任です。
関連するホストが変更されたときは、接続情報も変更しなければならないかもしれません。
新しく完全なテーブルコピーを開始する前に、コピー先のテーブルを空にするのが適切なこともあります。
mydb
という名前のデータベースをSQLスクリプトファイルにダンプします。
$
pg_dump mydb > db.sql
newdb
という名前の(新規に作成した)データベースにスクリプトを再ロードします。
$
psql -d newdb -f db.sql
カスタム形式のアーカイブファイルにデータベースをダンプします。
$
pg_dump -Fc mydb > db.dump
ディレクトリ形式アーカイブにデータベースをダンプします。
$
pg_dump -Fd mydb -f dumpdir
5個の作業用ジョブを使用してデータベースをdirectory形式のアーカイブにダンプします。
$
pg_dump -Fd mydb -j 5 -f dumpdir
newdb
という名前の(新規に作成した)データベースにアーカイブファイルを再ロードします。
$
pg_restore -d newdb db.dump
アーカイブファイルをダンプ元と同じデータベースに再ロードし、そのデータベースの現在の内容を捨てます。
$
pg_restore -d postgres --clean --create db.dump
mytab
という名前の単一のテーブルをダンプします。
$
pg_dump -t mytab mydb > db.sql
detroit
スキーマ内の名前がemp
で始まるすべてのテーブルをダンプします。
ただし、employee_log
という名前のテーブルは除きます。
$
pg_dump -t 'detroit.emp*' -T detroit.employee_log mydb > db.sql
east
またはwest
で始まりgsm
で終わるスキーマをすべてダンプします。
ただし、test
という単語を含む場合は除きます。
$
pg_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb > db.sql
正規表現記法を使用してオプションをまとめた形で同じことを行います。
$
pg_dump -n '(east|west)*gsm' -N '*test*' mydb > db.sql
ts_
から始まる名前のテーブルを除き、すべてのデータベースオブジェクトをダンプします。
$
pg_dump -T 'ts_*' mydb > db.sql
大文字または大文字小文字混在の名前を-t
などのスイッチに指定するには、名前を二重引用符で括らなければなりません。
さもないと小文字に変換されます(下記のPatternsを参照してください)。
しかし、二重引用符はシェルでも特別に扱われますので、これも引用符で括らなければなりません。
したがって、大文字小文字混在の名前を持つテーブルを1つダンプするには、以下のようにしなければなりません。
$
pg_dump -t "\"MixedCaseName\"" mydb > mytab.sql