pg_dumpall — PostgreSQLのデータベースクラスタをスクリプトファイルへ抽出する
pg_dumpall
[connection-option
...] [option
...]
pg_dumpallはクラスタの全てのPostgreSQLデータベースを、1つのスクリプトファイルに書き出す(「ダンプする」)ためのユーティリティです。 スクリプトファイルには、データベースのリストアのためにpsqlへの入力として使うことのできるSQLコマンドが含まれています。 これはクラスタ内の各データベースに対してpg_dumpを呼び出すことで行われます。 さらに、pg_dumpallは、全てのデータベースに共通するグローバルオブジェクト、すなわちデータベースロール、テーブル空間、および権限パラメータに対する設定許可をダンプします。 (pg_dumpはこれらのオブジェクトを保存しません)。
pg_dumpallは全てのデータベースからテーブルを読み込むため、完全なダンプを作成するには、おそらくデータベーススーパーユーザとして接続する必要がある可能性が高いでしょう。 さらに、保存されたスクリプトを実行する時には、ロールを追加したり、データベースを作成したりするので、スーパーユーザ権限が必要になるでしょう。
SQLスクリプトは標準出力に書き込まれます。
それをファイルにリダイレクトするためには、-f
/--file
オプションまたはシェルの演算子を使用して下さい。
pg_dumpallは、PostgreSQLサーバに何度か接続しなければなりません(データベースごとに接続することになります)。
パスワード認証を使用している場合、その度にパスワード入力が促されます。
そのような場合は~/.pgpass
ファイルを用意しておくと便利です。
詳細は34.16を参照してください。
以下のコマンドラインオプションは出力内容や形式を制御します。
-a
--data-only
データのみをダンプし、スキーマ(データ定義)をダンプしません。
-c
--clean
ダンプされたデータベース、ロール、テーブル空間を再作成する前に、それらをすべてDROP
するSQLコマンドを発行します。
このオプションは、リストアが既存のクラスタを上書きする場合に便利です。
オブジェクトが対象とするクラスタに存在しない場合、--if-exists
も指定されていない限り、リストア中に無視可能なエラーメッセージが報告されます。
-E encoding
--encoding=encoding
指定された文字エンコーディングでダンプを作ります。
デフォルトでは、ダンプはデータベースエンコーディングで作られます。
(同じ結果を得る他の方法はPGCLIENTENCODING
環境変数を望みのダンプエンコーディングに設定することです。)
-f filename
--file=filename
出力を指定したファイルに送ります。 これが省略されると標準出力が使用されます。
-g
--globals-only
グローバルオブジェクト(ロールとテーブル空間)のみをダンプし、データベースのダンプを行いません。
-O
--no-owner
オブジェクトの所有権を元のデータベースに一致させるためのコマンドを出力しません。
デフォルトでは、pg_dumpallはALTER OWNER
文またはSET SESSION AUTHORIZATION
文を発行して作成したスキーマ要素の所有権を設定します。
スーパーユーザ(もしくは、スクリプト内の全てのオブジェクトを所有するユーザ)以外のユーザがスクリプトを実行した場合、これらの文は失敗します。
任意のユーザがリストアできるスクリプトを作成するには、-O
を指定してください。ただし、この場合は、全てのオブジェクトの所有者がリストアしたユーザとなってしまいます。
-r
--roles-only
ロールのみをダンプし、データベースやテーブル空間のダンプを行いません。
-s
--schema-only
オブジェクト定義(スキーマ)のみをダンプし、データをダンプしません。
-S username
--superuser=username
トリガを無効にする際に使用するスーパーユーザのユーザ名を指定します。
これは--disable-triggers
を使用する場合にのみ使用されます
(通常はこのオプションを使うよりも、出力されたスクリプトをスーパーユーザ権限で実行する方が良いでしょう)。
-t
--tablespaces-only
テーブル空間のみをダンプし、データベースやロールのダンプを行いません。
-v
--verbose
冗長モードを指定します。 これを指定すると、pg_dumpallは開始時刻と終了時刻をダンプファイルに、進行メッセージを標準エラーに出力するようになります。 オプションを繰り返すと、追加のデバッグレベルメッセージが標準エラーに現れます。 このオプションはpg_dumpにも渡されます。
-V
--version
pg_dumpallのバージョンを表示し、終了します。
-x
--no-privileges
--no-acl
アクセス権限のダンプ(grant/revokeコマンド)を行いません。
--binary-upgrade
このオプションは現位置でのアップグレード用のユーティリティにより使用されるものです。 他の目的での使用は推奨されませんし、サポートもされません。 このオプションの動作は、将来通知することなく変更される可能性があります。
--column-inserts
--attribute-inserts
明示的に列名を付けたINSERT
コマンド(INSERT INTO
)としてダンプします。
これによりリストアは非常に遅くなります。
主に、PostgreSQL以外のデータベースにロード可能なダンプを作成する時に有用です。
table
(column
, ...) VALUES...
--disable-dollar-quoting
このオプションは、関数本体用のドル引用符の使用を無効にし、強制的に標準SQLの文字列構文を使用した引用符付けを行います。
--disable-triggers
このオプションは、データのみのダンプを作成する場合だけに使用します。 データのリストア中に、対象とするテーブル上のトリガを一時的に使用不可にするためのコマンドを出力するようpg_dumpallに指示します。 このオプションは、データのリストア中には呼び出したくない参照整合性検査やその他のトリガがテーブル上にある場合に使用します。
現在のところ、--disable-triggers
を指定してコマンドを実行するのは、スーパーユーザでなければなりません。
そのため、-S
でスーパーユーザの名前を指定するか、あるいは、可能であれば、スーパーユーザ権限でスクリプトを開始するよう注意する必要があります。
--exclude-database=pattern
名前がpattern
にマッチするデータベースをダンプしません。
複数の--exclude-database
オプションを記述することで複数のパターンを除外できます。
pattern
パラメータはpsqlの\d
コマンドで使用される規則(パターン参照)と同じ規則に従うパターンとして解釈されます。ですので、ワイルドカード文字をパターン内に記述することで、複数のデータベースを除外することもできます。
ワイルドカードを使用する時は、シェルによりそのワイルドカードを展開させないように、パターンを引用符で括ってください。
--extra-float-digits=ndigits
浮動小数点データをダンプする時に、利用できる最大の精度の代わりに、extra_float_digitsで指定された値を使います。 バックアップ目的で作られたダンプルーチンは、このオプションを使うべきではありません。
--if-exists
DROP ... IF EXISTS
コマンドを使用して、--clean
モードでオブジェクトを削除します。
これは、「does not exist」エラーを抑制します。
このオプションは、--clean
も指定されていない場合には無効です。
--inserts
データを(COPY
ではなく)INSERT
コマンドとしてダンプします。
これを行うとリストアが非常に遅くなります。
主にPostgreSQL以外のデータベースにロード可能なダンプを作成する時に有用です。
列の順序を変更した場合はリストアが失敗する可能性があることに注意してください。
さらに低速になりますが、--column-inserts
オプションの方が安全です。
--load-via-partition-root
テーブルパーティションに対するデータをダンプするとき、COPY
やINSERT
文をパーティション自体ではなく、それを含むパーティション階層のルートに向けさせます。
これにより、データが読み込まれるときに各行に対して適切なパーティションが再判断されるようになります。
これは、行が必ずしも元のサーバと同じパーティションに落ちないようなサーバにデータをリストアするときに有用でしょう。
例えば、パーティション列がtext型で二つのシステムがパーティション列をソートするのに使われる照合順序の異なった定義を持っている場合に、これは起こりえることです。
--lock-wait-timeout=timeout
ダンプ開始時に共有テーブルロックの獲得のために永遠に待機しません。
指定したtimeout
の間にテーブルをロックすることができない場合は失敗します。
タイムアウトはSET statement_timeout
で受け付けられる任意の書式で指定できます。
--no-comments
コメントをダンプしません。
--no-publications
パブリケーションをダンプしません。
--no-role-passwords
ロールのパスワードをダンプしません。
リストア時にロールのパスワードはNULLになるため、パスワードが設定されるまでは、パスワード認証は常に失敗します。
このオプションが指定された場合、パスワードの値が不要となるので、ロール情報はpg_authid
ではなく、カタログビューのpg_roles
から読み取られます。
従って、pg_authid
へのアクセスが何らかのセキュリティポリシーによって制限されている場合にも、このオプションは役立ちます。
--no-security-labels
セキュリティラベルをダンプしません。
--no-subscriptions
サブスクリプションをダンプしません。
--no-sync
デフォルトでは、pg_dumpall
はすべてのファイルが確実にディスクに書き込まれるまで待機します。
このオプションを使うとpg_dumpall
は待機せずに戻るため、より高速になりますが、これは、その後にオペレーティングシステムがクラッシュすると、ダンプが破損する可能性があることを意味します。
一般的に言って、このオプションはテスト用には有用ですが、実運用の環境からデータをダンプするときには使用しないほうが良いでしょう。
--no-table-access-method
セレクトテーブルアクセスメソッドにコマンドを出力しません。 このオプションを使用すると、リストア中にどのテーブルアクセスメソッドがデフォルトであっても、すべてのオブジェクトが作成されます。
--no-tablespaces
オブジェクト用にテーブル空間を作成または選択するコマンドを出力しません。 このオプションを付けると、すべてのオブジェクトはリストア時のデフォルトのテーブル空間内に作成されます。
--no-toast-compression
TOAST圧縮手法を設定するコマンドを出力しません。 このオプションにより、列はすべてデフォルトの圧縮の設定でリストアされます。
--no-unlogged-table-data
ログを取らないテーブルの内容をダンプしません。 このオプションはテーブル定義(スキーマ)をダンプするかどうかには影響しません。 そのテーブルデータのダンプを抑制するだけです。
--on-conflict-do-nothing
INSERT
コマンドにON CONFLICT DO NOTHING
を追加します。
このオプションは、--inserts
または--column-inserts
が同時に指定されていなければ、有効ではありません。
--quote-all-identifiers
強制的にすべての識別子に引用符を付与します。
このオプションは、pg_dumpallのメジャーバージョンとは異なるメジャーバージョンのPostgreSQLのサーバーからデータベースをダンプするとき、あるいは出力を異なるメジャーバージョンのサーバにロードする予定であるときに推奨されます。
デフォルトでは、pg_dumpallは、それ自身のメジャーバージョンにおける予約語である識別子に対してのみ引用符を付与します。
これは、他のバージョンのサーバを処理するときに互換性の問題を引き起こす場合があります。
他のバージョンのサーバでは予約語の集合が多少、異なる場合があるからです。
--quote-all-identifiers
を使用することで、ダンプのスクリプトが読みにくくなりますが、このような問題を防ぐことができます。
--rows-per-insert=nrows
(COPY
ではなく)INSERT
コマンドでデータをダンプします。
INSERT
コマンド1つあたりの最大行数を制御します。
指定する値は0より大きくなければなりません。
リストア中のエラーでは、テーブルの内容がまるごと失われることはなく、問題のあるINSERT
の一部の行が失われるだけです。
--use-set-session-authorization
ALTER OWNER
コマンドの代わりに標準SQLのSET SESSION AUTHORIZATION
コマンドを出力します。
これにより、ダンプの標準への互換性が高まりますが、ダンプ内のオブジェクトの履歴によっては正しくリストアされない可能性があります。
-?
--help
pg_dumpallコマンドライン引数の使用方法を表示し、終了します。
以下のコマンドラインオプションは、データベース接続パラメータを制御します。
-d connstr
--dbname=connstr
サーバに接続するために使用されるパラメータを接続文字列として指定します。これは衝突するコマンドラインオプションよりも優先します。
このオプションは、他のクライアントアプリケーションとの一貫性のために--dbname
と呼ばれます。
しかしpg_dumpallは多くのデータベースに接続しなければなりませんので、接続文字列内のデータベース名は無視されます。
グローバルオブジェクトをダンプするために使用されるデータベースの名前を指定するため、または他のどのデータベースをダンプしなければならないかを見つけるためには-l
を使用してください。
-h host
--host=host
データベースサーバが稼働しているマシンのホスト名を指定します。
この値がスラッシュから始まる場合、Unixドメインソケット用のディレクトリとして使用されます。
デフォルトは、設定されていれば環境変数PGHOST
から取得されます。設定されていなければ、Unixドメインソケット接続とみなされます。
-l dbname
--database=dbname
グローバルオブジェクトをダンプし、他のどのデータベースをダンプすべきかを見つけるために接続するデータベースの名前を指定します。
指定されなかった場合、postgres
が使用されます。
もしこれも存在しない場合はtemplate1
が使用されます。
-p port
--port=port
サーバが接続を監視するTCPポートもしくはローカルUnixドメインソケットファイルの拡張子を指定します。
デフォルトは、設定されている場合、環境変数PGPORT
の値になります。設定されていなければ、コンパイル時のデフォルト値となります。
-U username
--username=username
接続ユーザ名です。
-w
--no-password
パスワードの入力を促しません。
サーバがパスワード認証を必要とし、かつ、.pgpass
ファイルなどの他の方法が利用できない場合、接続試行は失敗します。
バッチジョブやスクリプトなどパスワードを入力するユーザが存在しない場合にこのオプションは有用かもしれません。
-W
--password
データベースに接続する前に、pg_dumpallは強制的にパスワード入力を促します。
サーバがパスワード認証を要求する場合pg_dumpallは自動的にパスワード入力を促しますので、これが重要になることはありません。
しかし、pg_dumpallは、サーバにパスワードが必要かどうかを判断するための接続試行を無駄に行います。
こうした余計な接続試行を防ぐために-W
の入力が有意となる場合もあります。
パスワードの入力はダンプするデータベース毎に繰り返し促されます。
通常は、手作業のパスワード入力に依存するよりも~/.pgpass
を設定する方が良いでしょう。
--role=rolename
ダンプを作成する際に使用するロール名を指定します。
このオプションによりpg_dumpallはデータベースに接続した後にSET ROLE
rolename
コマンドを発行するようになります。
認証に使用したユーザ(-U
で指定されたユーザ)がpg_dumpallで必要とされる権限を持たないが、必要な権限を持つロールに切り替えることができる場合に有用です。
一部のインストレーションではスーパーユーザとして直接ログインさせないポリシーを取ることがありますが、このオプションを使用することでポリシーに反することなくダンプを作成することができます。
PGHOST
PGOPTIONS
PGPORT
PGUSER
デフォルトの接続パラメータです。
PG_COLOR
診断メッセージで色を使うかどうかを指定します。
可能な値はalways
、auto
、never
です。
また、このユーティリティは、他のほとんどのPostgreSQLユーティリティと同様、libpqでサポートされる環境変数を使用します(34.15を参照してください)。
pg_dumpallは、内部でpg_dumpを呼び出すので、診断メッセージの一部ではpg_dumpを参照しています。
--clean
オプションは、ダンプスクリプトを新しいクラスタにリストアする意図のときであっても、有用なことがあります。
--clean
の使用は、スクリプトに組み込みのpostgres
およびtemplate1
データベースを削除して再作成する権限を与え、これらのデータベースが元のクラスタに持っていたものと同じ属性(例えばロケールやエンコーディング)を保つことを保証します。
このオプションが無いと、これらのデータベースは既存のデータベースレベルの属性を維持します。
オプティマイザが正確な統計情報を使用できるように、リストア後は、リストアしたテーブルそれぞれに対してANALYZE
を実行することを勧めます。
また、vacuumdb -a -z
を実行すると、全てのデータベースを解析することができます。
ダンプスクリプトはエラー無しに完全に実行すると期待すべきではありません。
特にスクリプトは存在する全てのロールに対してCREATE ROLE
を発行するので、宛先のクラスタが異なるブートストラップスーパーユーザ名で初期化されていない限り、ブートストラップスーパーユーザについて「role already exists」エラーを受け取ることは確実です。
このエラーは無害であり、無視してください。
--clean
オプションの使用は、追加で無害な存在しないオブジェクトについてのエラーメッセージを発生させますが、--if-exists
を加えることでエラー発生を最小化できます。
pg_dumpallでは、必要なテーブル空間用のディレクトリがリストア前に存在していることを要求します。 存在しないと、デフォルト以外の場所にあるデータベースに関して、そのデータベース生成が失敗します。
全てのデータベースを書き出す場合、以下のようにします。
$
pg_dumpall > db.out
上記のファイルからデータベースをリストアする場合、以下のようにします。
$
psql -f db.out postgres
ここではどのデータベースに接続するかということは重要ではありません。なぜならpg_dumpallが作成するスクリプトファイルには、保存されたデータベースの作成および接続のための適切なコマンドが含まれているからです。
例外は--clean
を指定した場合で、最初にpostgres
データベースに接続しなければなりません。
このときのスクリプトは即座に他のデータベースを削除しようとし、接続中のデータベースに対しては失敗するでしょう。
発生し得るエラーの原因については、pg_dumpを参照してください。