pg_basebackup — PostgreSQLクラスタのベースバックアップを取得する
pg_basebackup [option...]
pg_basebackupは、稼動中のPostgreSQLのデータベースクラスタのベースバックアップを取るために使用されます。 データベースへの他のクライアントに影響することなく、バックアップが取られます。 またこのバックアップはポイントインタイムリカバリ（25.3. 継続的アーカイブとポイントインタイムリカバリ（PITR）参照）とログシッピングやストリーミングレプリケーションスタンバイサーバ用の開始点（26.2. ログシッピングスタンバイサーバ参照）としても使用することができます。
pg_basebackupは、システムをバックアップモードに入れ、また戻すことを自動的に行い、データベースクラスタファイルのバイナリコピーを作成します。 バックアップは常にデータベースクラスタ全体のバックアップを取ります。 個々のデータベースや個々のデータベースオブジェクトをバックアップすることはできません。 個々のデータベースバックアップに関してはpg_dumpなどのツールを使用しなければなりません。
バックアップは通常のPostgreSQL接続を経由して、レプリケーションプロトコルを用いて、作成されます。
この接続はスーパーユーザまたはREPLICATION権限（21.2. ロールの属性参照）を持つユーザが確立しなければなりません。
さらにレプリケーション用の接続にはpg_hba.confにおける明示的な権限が許されていなければなりません。
またサーバでmax_wal_sendersを、バックアップ用に少なくとも１つのセッションを残すように十分大きく設定する必要があります。
同時にpg_basebackupを複数実行することができます。
しかし性能の観点からは、１つのバックアップのみを取り結果をコピーする方が優れています。
pg_basebackupは、マスタからだけではなくスタンバイからもベースバックアップを作成することができます。
スタンバイからバックアップを取得するためには、レプリケーション接続を受け付けられるようにスタンバイを設定してください（つまりmax_wal_sendersとhot_standbyを設定し、host-based authenticationを設定してください）。
またマスタでfull_page_writesを有効にする必要があります。
スタンバイからのオンラインバックアップではいくつかの制限があることに注意してください。
バックアップ履歴ファイルはバックアップされるデータベースクラスタ内に作成されません。
バックアップの終了時点で、バックアップに必要なすべてのWALファイルがアーカイブされている保証はありません。
アーカイブリカバリ用にこのバックアップを使用する予定で、かつ、その時点で必要なファイルすべてが利用できることを確実にしたい場合、
-xオプションを使用してバックアップに含めなければなりません。
オンラインバックアップ中にスタンバイがマスタに昇格した場合、バックアップは失敗します。
バックアップに必要なすべてのWALレコードは、必要なだけの完全ページ書き出しを含んでいなければなりません。
つまりこれは、マスタでfull_page_writesを有効にし、archive_commandとしてWALファイルから完全ページ書き出しを取り除くpg_compresslogのようなツールを使用しないことが要求されます。
以下のコマンドラインオプションは出力の場所と書式を制御します。
-D directory--pgdata=directory出力を書き出すディレクトリです。 pg_basebackupは必要ならば、このディレクトリとその親ディレクトリすべてを作成します。 ディレクトリはすでに存在してもかまいませんが、存在しかつ空でない場合はエラーになります。
バックアップがtarモードであり、かつ、指定したディレクトリが-（ダッシュ）の場合、tarファイルはstdoutに書き出されます。
このオプションは必須です。
-F format--format=format出力形式を選択します。
formatには以下のいずれかを取ることができます。
pplain普通のファイルとして、現在のデータディレクトリとテーブル空間と同じレイアウトで、出力を書き出します。 クラスタがテーブル空間を追加で持たない場合、データベース全体が指定したディレクトリに格納されます。 クラスタが追加のテーブル空間を持つ場合は、主データディレクトリは指定したディレクトリ内に格納されますが、他のテーブル空間はすべて、サーバ上の同じ絶対パスに格納されます。
これがデフォルトの書式です。
ttar指定したディレクトリ内にtarファイルとして出力を書き出します。
主データディレクトリはbase.tarという名前のファイルに書き出され、他のテーブル空間はすべてテーブル空間のOIDに因んだ名前のファイルに書き出されます。
対象ディレクトリとして-（ダッシュ）という値が指定された場合、tarの内容は標準出力に書き出されます。
これは例えばgzipへのパイプ処理に適しています。
これはクラスタが追加テーブル空間を持たない場合のみ行うことができます。
-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データを一切削除しないことが保証されます。
-T olddir=newdir--tablespace-mapping=olddir=newdir
ディレクトリolddirにあるテーブル空間を、バックアップ中にnewdirに再配置します。
これが有効であるためには、olddirが、現在のテーブル空間のパス定義と完全に一致している必要があります(ただし、バックアップに含まれるolddir内にテーブル空間がなくてもエラーにはなりません)。
olddirとnewdirはいずれも絶対パスでなければなりません。
パス名に=記号が含まれるときは、バックスラッシュでエスケープしてください。
このオプションは、複数のテーブル空間に対して複数回指定することができます。
以下の例を参照してください。
この方法でテーブル空間を再配置すると、メインのデータディレクトリ内のシンボリックリンクは、新しい場所を指すように更新されます。 このため、新しいデータディレクトリは、すべてのテーブル空間が更新された場所にあり、新しいサーバインスタンスがすぐに使える状態になっています。
--xlogdir=xlogdir
トランザクションログのディレクトリの場所を指定します。
xlogdirは絶対パスでなければなりません。
トランザクションログのディレクトリは、バックアップがplainモードの場合にのみ指定できます。
-x--xlogこのオプションの使用は、fetch方式の-Xの使用と同一です。
-X method--xlog-method=method必要なトランザクションログファイル（WALファイル）をバックアップに含めます。 これはバックアップ中に生成されたトランザクションログをすべて含みます。 このオプションが指定された場合、ログアーカイブを考慮することなく展開したディレクトリ内でそのままpostmasterを起動することができます。 つまりこれは完全なスタンドアローンバックアップを作成します。
以下のトランザクションログを収集するための方法がサポートされます。
ffetchトランザクションログファイルはバックアップの最後に収集されます。 したがって、wal_keep_segmentsパラメータを、バックアップの最後までログが削除されない程度に十分大きくする必要があります。 ログの転送時点でそのログがローテートされていた場合、バックアップは失敗し、使用することができません。
sstreamバックアップを作成する時にトランザクションログをストリームします。 これは第二のサーバ接続を開き、バックアップを実行している間、並行してトランザクションログのストリーミングを始めます。 したがって、これはmax_wal_sendersで設定される接続を２つ使用します。 クライアントが受け取ったトランザクションログに追従している限り、このモードを使用すれば、マスタ上に余分に保管されるトランザクションログは必要ありません。
-z--gziptarファイル出力のデフォルトの圧縮レベルによるgzip圧縮を有効にします。 tarファイルを生成する場合のみ圧縮を利用することができます。
-Z level--compress=leveltarファイル出力のgzip圧縮を有効にします。 また圧縮レベル（0から9まで、0は圧縮なし、9が最高の圧縮レベル）を指定します。 tarファイルを生成する場合のみ圧縮を利用することができます。
以下のコマンドラインオプションはバックアップの生成とこのプログラムの実行を制御します。
-c fast|spread--checkpoint=fast|spreadチェックポイントモードをfast（即座に実行）またはspread（デフォルト）に設定します(25.3.3. 低レベルAPIを使用したベースバックアップの作成を参照してください)。
-l label--label=labelバックアップのラベルを設定します。
何も指定がない場合、「pg_basebackup base backup」というデフォルト値が使用されます。
-P--progress進行状況報告を有効にします。
これを有効にすると、バックアップ中におおよその進行状況が報告されます。
データベースはバックアップ中に変更があるかもしれませんので、これはおおよそでしかなくちょうど100%では終わらないかもしれません。
特に、WALログがバックアップに含まれる場合、データ総量は前もって予測することはできません。
このためこの場合、推定対象容量はWALなしの総推定量を過ぎた後増加します。
これが有効な場合、バックアップはまずデータベース全体容量を計算し、その後バックアップに戻り、実際の内容を送信します。 バックアップに要する時間は少し長くなるかもしれません。特に最初のデータが送られるようになるまでの時間がより長くなります。
-v--verbose冗長モードを有効にします。 開始時および終了段階でいくつか追加の段階が出力されます。 また進行状況報告も有効な場合、現在処理中のファイル名も正しく出力されます。
以下のオプションはデータベース接続パラメータを制御します。
-d connstr--dbname=connstrサーバとの接続のために使用するパラメータを、接続文字列として指定します。 詳細については32.1.1. 接続文字列を参照してください。
このオプションは他のクライアントアプリケーションとの整合性のために--dbnameと呼ばれます。
しかし、pg_basebackupはクラスタ内の何らかの特定のデータベースに接続しませんので、接続文字列内のデータベース名は無視されます。
-h host--host=hostサーバが稼働しているマシンのホスト名を指定します。
この値がスラッシュから始まる場合、Unixドメインソケット用のディレクトリとして使用されます。
デフォルトは、設定されていれば環境変数PGHOSTから取得されます。
設定されていなければ、Unixドメインソケット接続とみなされます。
-p port--port=portサーバが接続を監視するTCPポートもしくはローカルUnixドメインソケットファイルの拡張子を指定します。
デフォルトは、設定されている場合、環境変数PGPORTの値となります。設定されていなければ、コンパイル時のデフォルト値となります。
-s interval--status-interval=interval状態パケットがサーバに返送される間隔を秒単位で指定します。 これにより簡単にサーバから進行状況を監視することができます。 ゼロという値は定期的な状態更新を完全に無効にします。 しかし、タイムアウトによる切断を防止するために、サーバにより要求された場合に更新は送信されます。 デフォルト値は１０秒です。
-U username--username=username接続ユーザ名です。
-w--no-passwordパスワードの入力を促しません。
サーバがパスワード認証を必要とし、かつ、.pgpassファイルなどの他の方法が利用できない場合、接続試行は失敗します。
バッチジョブやスクリプトなどパスワードを入力するユーザが存在しない場合にこのオプションは有用かもしれません。
-W--passwordデータベースに接続する前に、pg_basebackupは強制的にパスワード入力を促します。
サーバがパスワード認証を要求する場合pg_basebackupは自動的にパスワード入力を促しますので、これが重要になることはありません。
しかし、pg_basebackupは、サーバにパスワードが必要かどうかを判断するための接続試行を無駄に行います。
こうした余計な接続試行を防ぐために-Wの入力が有意となる場合もあります。
以下のその他のオプションも使用することができます。
-V--versionpg_basebackupのバージョンを表示し終了します。
-?--helppg_basebackupコマンドライン引数の使用方法を表示し、終了します。
他のほとんどのPostgreSQLユーティリティと同様このユーティリティはlibpqでサポートされる環境変数（32.14. 環境変数参照）を使用します。
バックアップの開始時に、バックアップを取得するサーバ上でチェックポイントを書き込む必要があります。
特にオプション --checkpoint=fast を使用していない場合、これには少し時間を要する場合があり、その間 pg_basebackup はアイドル状態であるように見えます。
このバックアップには、設定ファイルやサードパーティによりディレクトリに格納された追加ファイルを含め、データディレクトリとテーブル空間内のすべてのファイルが含まれます。 しかし、通常ファイルとディレクトリのみがコピーされます。 シンボリックリンク(テーブル空間で利用されているものを除く)および特殊デバイスファイルはスキップされます。 (正確な詳細については51.3. ストリーミングレプリケーションプロトコルを参照してください。)
オプション--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 | bzip2 > backup.tar.bz2
（データベース内に複数のテーブル空間が存在する場合このコマンドは失敗します。）
/opt/tsにあるテーブル空間を./backup/tsに再配置してローカルデータベースのバックアップを作成します。
$pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts