pg_dump

名前

pg_dump -- PostgreSQL データベースを、スクリプトファイルまたは他のアーカイブファイルへ抽出

概要

pg_dump [option...] [dbname]

説明

pg_dumpPostgreSQL データベースをバックアップするユーティリティです。 データベースを同時に使用していても一貫性のあるバックアップを作成します。 pg_dump は他のユーザによるデータベースへのアクセス(読み書き)をブロックしません。

スクリプトとして、あるいは、アーカイブファイル形式でダンプすることができます。 スクリプトファイルはプレインテキスト形式であり、保存時の状態のデータベースを再構成するために必要な SQL コマンドが書き込まれています。 これらのスクリプトをリストアするには psql を使用します。 これらのスクリプトは、他のマシンや他のアーキテクチャ上でさえも、データベースを再構築するために使うことができます。 また、少し編集すれば他の SQL データベース製品上でもデータベースを再構築することができます。

更に pg_restore を使用してデータベースを再構築することを目的とした、アーカイブファイル形式もあります。 このファイルを使用して、pg_restore はリストア対象を選択することも、リストアするアイテムの並び替えも行なうことができます。 アーカイブファイルもまた、アーキテクチャを越えて移植できるように設計されています。

アーカイブファイル形式の1つを使用し、pg_restore と組み合わせて使用する場合、pg_dump は柔軟なアーカイブ / 転送機構を提供します。 pg_dump を使用してデータベース全体をバックアップし、pg_restore を使用して、アーカイブの内容を検査したり、データベースの一部を選択してリストアしたりすることができます。 もっとも柔軟な出力ファイル形式は、"custom" 形式 (-Fc) です。 この形式は、保存された項目の選択や並び換えを行うことができ、また、デフォルトで圧縮されています。 tar 形式 (-Ft) は圧縮されず、また、ロードの際に並び替えを行なうことができません。 しかし、他の点では、かなり柔軟なものです。その上、tar などの他のツールを使用して操作することができます。

pg_dump の実行中は、(標準エラーに出力される) 警告、特に後述の制限に関する警告が出力されていないか確認して下さい。

オプション

以下のコマンドラインオプションを使用して出力形式を制御することができます。

dbname

ダンプ(抽出)するデータベースの名前を指定します。 指定されていない場合は、環境変数 PGDATABASE が使われます。 この変数も設定されていない場合は、接続のために指定されたユーザ名が使用されます。

-a
--data-only

データのみをダンプし、スキーマ (データ定義) はダンプしません。

このオプションは、プレインテキスト形式の場合にのみ意味があります。 他の形式では、pg_restore を呼び出す時にこのオプションを指定することができます。

-b
--blobs

ラージオブジェクトをダンプに含めます。

-c
--clean

データベースオブジェクトを作成する(ためのコマンドの)前に掃除(削除)するためのコマンドを書き出します。

このオプションは、プレインテキスト形式の場合にのみ意味があります。 他の形式では、pg_restore を呼び出す時にこのオプションを指定することができます。

-C
--create

データベース自体を作成し、作成したデータベースに接続するコマンドを始めに出力します。 (この形のスクリプトを使用する場合、スクリプトを実行する前にどのデータベースに接続すればいいかという問題を考える必要がなくなります。)

このオプションは、プレインテキスト形式の場合にのみ意味があります。 他の形式では、pg_restore を呼び出す時にこのオプションを指定することができます。

-d
--inserts

データを (COPY ではなく) INSERT コマンドとしてダンプします。 これを行うとリストアに非常に時間がかかりますが、生成されたアーカイブは他の SQL データベース管理システムへの移植性が高くなります。

-D
--column-inserts
--attribute-inserts

データを明示的に列名を付けた INSERT コマンド (INSERT INTO table (column, ...) VALUES...) としてダンプします。 これによりリストアは非常に遅くなります。 しかし、列の順番を変更する場合にはこれが必要です。

-f file
--file=file

出力を指定のファイルに送ります。 省略時は標準出力が使用されます。

-F format
--format=format

出力形式を選択します。format は以下の値のいずれかです。

p

プレインテキストの SQL スクリプトファイルを出力します (デフォルト)。

t

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

c

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

-i
--ignore-version

pg_dump とデータベースサーバのバージョンの不一致を無視します。

pg_dump は、前のリリースの PostgreSQL データベースも処理できますが、(現時点では7.0より前の)非常に古いバージョンのデータベースの処理はできません。 バージョンチェックを無効にする必要がある場合に、このオプションを使います (もし pg_dump が失敗したとしても、警告されなかったとは言えませんよ)。

-n namespace
--schema=schema

schemaの内容のみをダンプします。 このオプションが指定されなければ、対象データベース内にあるシステム以外のスキーマ全てがダンプされます。

注意: このモードでは、pg_dump は選択したスキーマ内のオブジェクトが依存する可能性がある他のデータベースオブジェクトのダンプを行いません。 したがって、スキーマ単体のダンプの結果を初期化されたデータベースに正常にリストアできるかどうかの保証はありません。

-o
--oids

各テーブルのオブジェクト識別子 (OID) をダンプします。 アプリケーションで OID 列を (外部キー制約など) 何らかの形で使用している場合は、このオプションを使用して下さい。 その他の場合は、このオプションは使用しないで下さい。

-O
--no-owner

オブジェクトの所有権を元のデータベースに一致させるためのコマンドを出力しません。 デフォルトでpg_dumpは、 SET SESSION AUTHORIZATION 文を発行して、作成したスキーマ要素の所有権を設定します。 スーパーユーザ(もしくは、そのスクリプト内の全てのオブジェクトを所有するユーザ)で起動させずに、このスクリプトを実行すると、これらの文は失敗します。 任意のユーザがリストアできるスクリプトを作成するためには、-Oを指定してください。 ただし、この場合は全てのオブジェクトの所有者は、そのリストアしたユーザとなってしまいます。

このオプションは、プレインテキスト形式の場合にのみ意味があります。 他の形式では、pg_restore を呼び出す時にこのオプションを指定することができます。

-R
--no-reconnect

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

-s
--schema-only

スキーマ (データ定義) のみをダンプし、データはダンプしません。

-S username
--superuser=username

トリガを無効にする場合に使用する、スーパユーザのユーザ名を指定します。 これは --disable-triggers を使用する場合にのみ該当します。 (通常は これを付けずにスーパユーザとして結果スクリプトを開始する方が良いでしょう。)

-t table
--table=table

table のデータのみをダンプします。 同じ名前のテーブルが異なるスキーマに複数存在することがあり、この場合、一致する全てのテーブルがダンプされます。 1テーブルのみを選択するには、--schema--table の両方を指定してください。

注意: このモードでは、pg_dump は選択したテーブル内のオブジェクトが依存する可能性がある他のデータベースオブジェクトのダンプを行いません。 したがって、テーブル単体のダンプの結果を初期化されたデータベースに正常にリストアできるかどうかの保証はありません。

-v
--verbose

冗長モードを指定します。 これを指定すると、pg_dump は進行状況メッセージを標準エラーに出力します。

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

アクセス権限 (grant/revoke コマンド) のダンプを抑制します。

-X use-set-session-authorization
--use-set-session-authorization

このオプションは廃止となりましたが、まだ、後方互換のために受け付けられます。 現在のpg_dumpでは、常に、以前のバージョンでこのオプションが指定された場合の方法で動作します。

-X disable-triggers
--disable-triggers

このオプションは、データのみのダンプを作成する場合だけに該当します。 データのリロード中に、pg_dump が対象とするテーブル上のトリガを一時的に使用不可にするためのコマンドを含めるよう指示します。 このオプションは、参照整合性検査やデータのリロード中には呼び出されないようにしたいテーブル上のその他のトリガがある場合に使用します。

現在のところ、--disable-triggers を指定してコマンドを実行するのは、スーパーユーザでなければなりません。 そのため、ユーザは -S でスーパーユーザを指定するか、あるいは望ましい方法として、スーパーユーザとして注意してスクリプトの残りを開始する必要があります。

このオプションは、プレインテキスト形式の場合にのみ意味があります。他の形式では、pg_restore を呼び出す時にこのオプションを指定することができます。

-Z 0..9
--compress=0..9

圧縮をサポートするアーカイブ形式で使用する、圧縮レベルを指定します (現時点では、カスタムアーカイブ形式のみが圧縮をサポートしています)。

以下のコマンドラインオプションは、データベース接続パラメータを制御します。

-h host
--host=host

サーバが稼働しているマシンのホスト名を指定します。 この値がスラッシュから始まる場合、Unix ドメインソケット用のディレクトリとして使用されます。 デフォルトは 設定されていれば PGHOST 環境変数から取られます。 設定されていなければ、Unix ドメインソケット接続と仮定されます。

-p port
--port=port

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

-U username

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

-W

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

環境

PGDATABASE
PGHOST
PGPORT
PGUSER

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

診断

pg_dump は内部で SELECT 文を実行します。 pg_dump の実行に問題が発生した場合、psql などを使用して、データベースから情報を選択できるかどうか確認して下さい。

注釈

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

CREATE DATABASE foo WITH TEMPLATE template0;

pg_dump にはいくつかの制限があります。

tar アーカイブのメンバのサイズは、8 GB 未満に制限されています。 (これは tar ファイル形式が本来持っている制限です。) そのため、テーブルのテキスト表現がこのサイズを越える場合には、この形式は使用できません。 tar アーカイブとその他の出力形式の合計サイズには制限がありません ただしオペレーティングシステムによる制限がある場合があります。

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

データベースをダンプします。

$ 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_dump ユーティリティは Postgres95 リリース 0.02 から登場しました。 非プレインテキスト出力形式は、PostgreSQL リリース 7.1 で導入されました。

関連項目

pg_dumpall, pg_restore, psql