他のバージョンの文書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_basebackupPostgreSQLクラスタのベースバックアップを取得する

概要

pg_basebackup [option...]

説明

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

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

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

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

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

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

  • バックアップ履歴ファイルはバックアップされるデータベースクラスタ内に作成されません。

  • -X noneを使用している場合、バックアップ終了時にバックアップに必要なすべてのWALファイルがアーカイブされているという保証はありません。

  • オンラインバックアップ中にスタンバイがマスタに昇格した場合、バックアップは失敗します。

  • バックアップに必要なすべてのWALレコードは、必要なだけの完全ページ書き出しを含んでいなければなりません。 つまりこれは、マスタでfull_page_writesを有効にし、archive_commandとしてWALファイルから完全ページ書き出しを取り除くpg_compresslogのようなツールを使用しないことが要求されます。

オプション

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

-D directory
--pgdata=directory

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

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

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

-F format
--format=format

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

p
plain

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

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

t
tar

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

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

-r rate
--max-rate=rate

サーバから転送されるデータの最大転送速度です。 値は秒あたりのキロバイト数です。 添字Mを使うと秒あたりのメガバイト数を指定できます。 添字kを使うこともできますが、効果はありません。 有効な値は秒あたり32キロバイトから秒あたり1024メガバイトまでです。

この目的は、実行中のサーバに対するpg_basebackupの影響を制限することです。

このオプションはデータディレクトリの転送に対しては、常に影響があります。 WALファイルの転送については、収集方法がfetchの場合にのみ影響があります。

-R
--write-recovery-conf

スタンバイサーバの設定を容易にするために、出力ディレクトリ(tar形式の場合はベースアーカイブファイルの中)に最低限のrecovery.confを書き出します。 recovery.confファイルは接続設定の情報、また、指定があればpg_basebackupが使用しているレプリケーションスロットの情報を記録するので、ストリーミングレプリケーションは後で同じ設定を使用します。

-S slotname
--slot=slotname

このオプションは-X streamと一緒にのみ使用できます。 これによりWALストリーミングが指定したレプリケーションスロットを使用することになります。 ベースバックアップがレプリケーションスロットを利用したストリーミングレプリケーションのスタンバイとしての使用を意図したものであるなら、recovery.conf内で同じレプリケーションスロット名を使用すべきです。 そうすることで、ベースバックアップの終了とストリーミングレプリケーションの開始の間の時間に、サーバが必要なWALデータを一切削除しないことが保証されます。

このオプションが指定されず、サーバが一時レプリケーションスロットをサポートしている場合(バージョン10以上)、WALストリーミングには一時レプリケーションスロットが自動的に使用されます。

--no-slot

このオプションは、サーバが一時レプリケーションスロットをサポートしていたとしても、バックアップ時にそれを作らないようにします。

ログストリームを使う場合、オプション-Sでスロット名を指定しなければ、デフォルトで一時レプリケーションスロットが作られます。

このオプションの主要な目的は、サーバに空いているレプリケーションスロットがない時にベースバックアップの取得を可能にすることです。 ほぼすべての場合において、レプリケーションスロットの使用が望ましいです。 なぜなら、必要なWALがバックアップ中にサーバによって削除されることを防止できるからです。

-T olddir=newdir
--tablespace-mapping=olddir=newdir

ディレクトリolddirにあるテーブル空間を、バックアップ中にnewdirに再配置します。 これが有効であるためには、olddirが、現在のテーブル空間のパス定義と完全に一致している必要があります(ただし、バックアップに含まれるolddir内にテーブル空間がなくてもエラーにはなりません)。 olddirnewdirはいずれも絶対パスでなければなりません。 パス名に=記号が含まれるときは、バックスラッシュでエスケープしてください。 このオプションは、複数のテーブル空間に対して複数回指定することができます。 以下の例を参照してください。

この方法でテーブル空間を再配置すると、メインのデータディレクトリ内のシンボリックリンクは、新しい場所を指すように更新されます。 このため、新しいデータディレクトリは、すべてのテーブル空間が更新された場所にあり、新しいサーバインスタンスがすぐに使える状態になっています。

--waldir=waldir

先行書き込みログのディレクトリの場所を指定します。 waldirは絶対パスでなければなりません。 先行書き込みログのディレクトリは、バックアップがplainモードの場合にのみ指定できます。

-X method
--wal-method=method

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

以下の先行書き込みログを収集するための方法がサポートされます。

n
none

先行書き込みログをバックアップに含めません。

f
fetch

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

先行書き込みログファイルはbase.tarファイルに書き込まれます。

s
stream

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

先行書き込みログファイルはpg_wal.tarという名前の別のファイルに書き込まれます(サーバのバージョンが10よりも古い場合は、ファイルの名前はpg_xlog.tarになります)。

この値がデフォルトです。

-z
--gzip

tarファイル出力のデフォルトの圧縮レベルによるgzip圧縮を有効にします。 tarファイルを生成する場合のみ圧縮を利用することができ、すべてのtarファイルの名前に拡張子.gzが自動的に付加されます。

-Z level
--compress=level

tarファイル出力のgzip圧縮を有効にします。 また圧縮レベル(0から9まで、0は圧縮なし、9が最高の圧縮レベル)を指定します。 tarファイルを生成する場合のみ圧縮を利用することができ、すべてのtarファイルの名前に拡張子.gzが自動的に付加されます。

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

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

チェックポイントモードをfast(即座に実行)またはspread(デフォルト)に設定します(25.3.3を参照してください)。

-l label
--label=label

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

-n
--no-clean

デフォルトでは、pg_basebackupがエラーでアボートするとき、ジョブを完了できないことがわかるより前に作成したすべてのディレクトリ(例えば、データディレクトリと先行書き込みログのディレクトリ)を削除します。 このオプションはきれいに片付けることを禁止するので、デバッグのために有用です。

テーブル空間のディレクトリはいずれにせよ削除されないことに注意してください。

-P
--progress

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

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

-N
--no-sync

デフォルトでは、pg_basebackupは全てのファイルがディスクに安全に書き込まれるまで待機します。 このオプションは、pg_basebackupが待機せずに戻るようにするため、より高速になりますが、その後でOSがクラッシュするとベースバックアップの破損に繋がるかもしれません。 一般的に言って、このオプションはテスト用には有用ですが、実運用の環境を作成するときには使わない方が良いでしょう。

-v
--verbose

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

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

-d connstr
--dbname=connstr

サーバとの接続のために使用するパラメータを、接続文字列として指定します。 詳細については33.1.1を参照してください。

このオプションは他のクライアントアプリケーションとの整合性のために--dbnameと呼ばれます。 しかし、pg_basebackupはクラスタ内の何らかの特定のデータベースに接続しませんので、接続文字列内のデータベース名は無視されます。

-h host
--host=host

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

-p port
--port=port

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

-s interval
--status-interval=interval

状態パケットがサーバに返送される間隔を秒単位で指定します。 これにより簡単にサーバから進行状況を監視することができます。 ゼロという値は定期的な状態更新を完全に無効にします。 しかし、タイムアウトによる切断を防止するために、サーバにより要求された場合に更新は送信されます。 デフォルト値は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でサポートされる環境変数(33.14参照)を使用します。

注意

バックアップの開始時に、バックアップを取得するサーバ上でチェックポイントを書き込む必要があります。 特にオプション --checkpoint=fast を使用していない場合、これには少し時間を要する場合があり、その間 pg_basebackup はアイドル状態であるように見えます。

このバックアップには、設定ファイルやサードパーティによりディレクトリに格納された追加ファイルを含め、データディレクトリとテーブル空間内のすべてのファイルが含まれますが、PostgreSQLによって管理される一部の一時ファイルは含まれません。 ただし、テーブル空間に使われるシンボリックリンクが保存されることを除くと、通常のファイルとディレクトリのみがコピーされます。 PostgreSQLが認識している一部のディレクトリを指すシンボリックリンクは空のディレクトリとしてコピーされます。 その他のシンボリックリンクおよび特殊デバイスファイルはスキップされます。 (正確な詳細については52.4を参照してください。)

オプション--tablespace-mappingが使われなければ、テーブル空間はデフォルトでサーバ上のと同じパスでplain形式でバックアップされます。 このオプションがないと、サーバと同じホスト上でのplain形式のベースバックアップの実行は動作しません、というのは、バックアップを元のテーブル空間と同じディレクトリに書き込まなければならないからです。

tar形式モードを使う場合、PostgreSQLサーバを起動する前に各tarファイルを解凍するのはユーザの責任です。 追加のテーブル空間がある場合、それについてのtarファイルは、正しい場所に解凍される必要があります。 この場合、テーブル空間へのシンボリックリンクは、base.tarファイルに含まれるtablespace_mapファイルの内容に基づいて、サーバが作成します。

pg_basebackupは同じまたは9.1以降のより古いメジャーバージョンのサーバで動作します。 しかしWALストリーミングモード(-X stream)はバージョン9.3およびそれ以降のサーバでのみ動作します。 また、現在のバージョンのtar形式モード(--format=tarはバージョン9.5およびそれ以降のサーバでのみ動作します。

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 -X fetch | bzip2 > backup.tar.bz2

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

/opt/tsにあるテーブル空間を./backup/tsに再配置してローカルデータベースのバックアップを作成します。

$ pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts

関連項目

pg_dump