★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_basebackup

名前

pg_basebackup -- PostgreSQLクラスタのベースバックアップを取得

概要

pg_basebackup [option...]

説明

pg_basebackupは、稼動中のPostgreSQLデータベースクラスタのベースバックアップを取るために使用されます。 データベースへの他のクライアントに影響することなく、バックアップが取られます。 またこのバックアップはポイントインタイムリカバリ(項24.3参照)とログシッピングやストリーミングレプリケーションスタンバイサーバ用の開始点(項25.2参照)としても使用することができます。

pg_basebackupは、システムは自動的にバックアップモードにし、自動的にバックアップモードから戻ることを確実に行い、データベースクラスタファイルのバイナリコピーを作成します。 バックアップは常にデータベースクラスタ全体のバックアップを取ります。 個々のバックアップや個々のデータベースオブジェクトをバックアップすることはできません。 個々のデータベースバックアップに関してはpg_dumpなどのツールを使用しなければなりません。

バックアップは通常のPostgreSQL接続を経由して、レプリケーションプロトコルを用いて、作成されます。 この接続はスーパーユーザまたはREPLICATION権限(項20.2参照)を持つユーザが確立しなければなりません。 さらにレプリケーション用の接続にはpg_hba.confにおける明示的な権限が許されていなければなりません。 またサーバでmax_wal_sendersを、バックアップ用に少なくとも1つのセッションを残すように十分高く設定する必要があります。

同時にpg_basebackupを複数実行することができます。 しかし性能という観点からは、1つのバックアップのみを取り結果をコピーする方が優れています。

pg_basebackupは、マスタからだけではなくスタンバイからもベースバックアップを作成することができます。 スタンバイからバックアップを取得するためには、レプリケーション接続を受け付けられるようにスタンバイを設定してください(つまりmax_wal_sendershot_standbyを設定し、host-based authenticationを設定してください)。 またマスタでfull_page_writesを有効にする必要があります。

スタンバイからのオンラインバックアップではいくつかの制限があることに注意してください。

オプション

以下のコマンドラインオプションは出力の場所と書式を制御します。

-D directory
--pgdata=directory

出力を書き出すディレクトリです。 pg_basebackupは必要ならば、このディレクトリとその親ディレクトリすべてを作成します。 ディレクトリはすでに存在してもかまいませんが、存在しかつ空でない場合はエラーになります。

バックアップがtarモードであり、かつ、指定したディレクトリが-(ダッシュ)の場合、tarファイルはstdoutに書き出されます。

このオプションは必須です。

-F format
--format=format

出力書式を選択します。 formatには以下のいずれかを取ることができます。

p
plain

普通のファイルとして、現在のデータディレクトリとテーブル空間と同じレイアウトで、出力を書き出します。 クラスタがテーブル空間を追加で持たない場合、データベース全体が指定したディレクトリに格納されます。 クラスタが追加のテーブル空間を持つ場合は、主データディレクトリは指定したディレクトリ内に格納されますが、他のテーブル空間はすべて、サーバ上の同じ絶対パスに格納されます。

これがデフォルトの書式です。

t
tar

指定したディレクトリ内にtarファイルとして出力を書き出します。 主データディレクトリはbase.tarという名前のファイルに書き出され、他のテーブル空間はすべてテーブル空間のOIDに因んだ名前のファイルに書き出されます。

対象ディレクトリとして-(ダッシュ)という値が指定された場合、tarの内容は標準出力に書き出されます。 これは例えばgzipへのパイプ処理に適しています。 これはクラスタが追加テーブル空間を持たない場合のみ行うことができます。

-x
--xlog

このオプションの使用は、fetch方式の-Xの使用と同一です。

-X method
--xlog-method=method

必要なトランザクションログファイル(WALファイル)をバックアップに含めます。 これはバックアップ中に生成されたトランザクションログをすべて含めます。 このオプションが指定された場合、ログアーカイブを考慮することなく展開したディレクトリ内でそのままpostmasterを起動することができます。 つまりこれは完全なスタンドアローンバックアップを作成します。

以下のトランザクションログを収集するための方法がサポートされます。

f
fetch

トランザクションログファイルはバックアップの最後に収集されます。 したがって、wal_keep_segmentsパラメータを、バックアップの最後までログが削除されない程度に大きくさせる必要があります。 ログの転送時点でそのログがローテートされていた場合、バックアップは失敗し、使用することができません。

s
stream

バックアップを作成する時にトランザクションログをストリームします。 これは第二のサーバ接続を開き、バックアップを実行している間、並行してトランザクションログのストリーミングを始めます。 したがって、これはmax_wal_sendersで設定されるスロットを最大2つ使用します。 クライアントが受け取ったトランザクションログに追従している限り、このモードを使用すれば、マスタ上に余分に保管されるトランザクションログは必要ありません。

-z
--gzip

tarファイル出力のデフォルトの圧縮レベルによるgzip圧縮を有効にします。 tarファイルを生成する場合のみ圧縮を利用することができます。

-Z level
--compress=level

tarファイル出力のgzip圧縮を有効にします。 また圧縮レベル(1から9まで。9が最高の圧縮レベル)を指定します。 tarファイルを生成する場合のみ圧縮を利用することができます。

以下のコマンドラインオプションはバックアップの生成とこのプログラムの実行を制御します。

-c fast|spread
--checkpoint=fast|spread

チェックポイントをfastまたはspread(デフォルト)に設定します。

-l label
--label=label

バックアップのラベルを設定します。 何も指定がない場合、"pg_basebackup base backup"というデフォルト値が使用されます。

-P
--progress

進行状況報告を有効にします。 これを有効にすると、バックアップ中におおよその進行状況が報告されます。 データベースはバックアップ中に変更があるかもしれませんので、これはおおよそでしかなく100%正確に終わらないかもしれません。 実際、WALログがバックアップに含まれる場合、データ総量は前もって予測することはできません。 このためこの場合、推定対象容量はWALなしの総推定量を過ぎた後増加します。

これが有効な場合、バックアップはまずデータベース全体容量を計算し、その後実際の内容に戻り、送信します。 バックアップに要する時間はかなり長くなるかもしれません。具体的にはデータが送られるようになるまでの時間がより長くなります。

-v
--verbose

冗長モードを有効にします。 開始時および終了段階でいくつか追加の段階が出力されます。 また進行状況報告も有効な場合、現在処理中のファイル名も正しく出力されます。

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

-h host
--host=host

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

-p port
--port=port

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

-s interval
--status-interval=interval

サーバに返送する状態パケットの間隔を秒単位で指定します。 これは、サーバでレプリケーションタイムアウトが設定されている場合にトランザクションログを(--xlog=streamを用いて)ストリーミングする際に必要であり、監視をより簡単に行うことができます。 ゼロという値は状態更新を完全に無効にします。 デフォルト値は10秒です。

-U username
--username=username

接続ユーザ名です。

-w
--no-password

パスワードの入力を促しません。 サーバがパスワード認証を必要とし、かつ、.pgpassファイルなどの他の方法が利用できない場合、接続試行は失敗します。 バッチジョブやパスワードを入力するユーザが存在しない場合にこのオプションは有用かもしれません。

-W
--password

データベースに接続する前に、pg_basebackupは強制的にパスワード入力を促します。

サーバがパスワード認証を要求する場合pg_basebackupは自動的にパスワード入力を促しますので、これが重要になることはありません。 しかし、pg_basebackupは、サーバにパスワードが必要かどうかを判断するための接続試行を無駄に行います。 こうした余計な接続試行を防ぐために-Wの入力が有意となる場合もあります。

以下のその他のオプションも使用することができます。

-V
--version

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

-?
--help

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

環境

他のほとんどのPostgreSQLユーティリティと同様このユーティリティはlibpqでサポートされる環境変数(項31.14参照)を使用します。

注意

このバックアップには、設定ファイルとサードパーティによりディレクトリに格納された追加ファイルを含む、データディレクトリとテーブル空間内のすべてのファイルが含まれます。 データディレクトリ内には通常のファイルとディレクトリのみが許され、シンボリックリンクや特殊デバイスファイルは許されません。

PostgreSQLがテーブル空間を管理する方式のため、すべての追加テーブル空間のパスはバックアップをリストアした時に常に同一でなければなりません。 しかし主データディレクトリは他の場所に設置することができます。

mydbserverで稼動するサーバのベースバックアップを作成し、ローカルディレクトリに保管します。 /usr/local/pgsql/data:

$ pg_basebackup -h mydbserver -D /usr/local/pgsql/data

各テーブル空間につき圧縮したtarファイルを1つ作成するようにローカルサーバをバックアップし、backupディレクトリに保管します。 同時に実行時に進行状況を表示します。

$ pg_basebackup -D backup -Ft -z -P

単一のテーブル空間を持つローカルデータベースのバックアップを作成し、それをbzip2で圧縮します。

$ pg_basebackup -D - -Ft | bzip2 > backup.tar.bz2

(データベース内に複数のテーブル空間が存在する場合このコマンドは失敗します。)

関連項目

pg_dump