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

概要

pg_basebackup [option...]

説明

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

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

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

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

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

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

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

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

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

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

pg_basebackupがベースバックアップを取るときには必ず、サーバのpg_stat_progress_basebackupはバックアップの進行状況を報告します。 詳細は27.4.5を参照してください。

オプション

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

-D directory
--pgdata=directory

出力を書き出す対象のディレクトリを設定します。 pg_basebackupは、存在していなければこのディレクトリ(とその親ディレクトリのうち存在していないものすべて)を作成します。 ディレクトリはすでに存在してもかまいませんが、空でなければなりません。

バックアップがtar形式であり、かつ、対象のディレクトリが-(ダッシュ)の場合、tarファイルをstdoutに書き出します。

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

-F format
--format=format

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

p
plain

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

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

t
tar

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

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

-R
--write-recovery-conf

standby.signalを作成し、対象のディレクトリ(tar形式の場合はベースアーカイブファイルの中)にあるpostgresql.auto.confに接続設定を追加します。 これにより、バックアップの結果を利用するスタンバイサーバの設定が容易になります。

postgresql.auto.confファイルは接続設定の情報、また、指定があればpg_basebackupが使用しているレプリケーションスロットの情報を記録するので、ストリーミングレプリケーションは後で同じ設定を使用します。

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

ディレクトリolddirにあるテーブル空間を、バックアップ中にnewdirに再配置します。 これが有効であるためには、olddirが、ソースサーバでのテーブル空間のパス定義と完全に一致している必要があります。 (ただし、ソースサーバのolddir内にテーブル空間がなくてもエラーにはなりません。) 一方、newdirは受け取るホストのファイルシステム内のディレクトリです。 主対象ディレクトリと同様に、newdirは既に存在している必要はありませんが、存在している場合には空でなければなりません。 olddirnewdirはいずれも絶対パスでなければなりません。 パス名に等号(=)を含む必要がある場合には、バックスラッシュをその前に付けてください。 このオプションは、複数のテーブル空間に対して複数回指定することができます。

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

--waldir=waldir

WAL(先行書き込みログ)ファイルを書き込むディレクトリを設定します。 デフォルトでは、WALファイルは対象のpg_walサブディレクトリに置かれますが、どこか他の場所に置くためにこのオプションが使えます。 waldirは絶対パスでなければなりません。 主対象ディレクトリと同様に、waldirは既に存在している必要はありませんが、存在している場合には空でなければなりません。 このオプションは、バックアップがplain形式の場合にのみ指定できます。

-X method
--wal-method=method

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

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

n
none

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

f
fetch

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

tar形式が使われれば、先行書き込みログファイルはbase.tarファイルに含まれます。

s
stream

バックアップを取る時に先行書き込みログデータをストリームします。 この方法は第2のサーバ接続を開き、バックアップを実行している間、並行して先行書き込みログのストリーミングを始めます。 したがって、レプリケーション接続を、1つではなく2つ使用します。 クライアントが先行書き込みログデータに追従している限り、このモードを使用すれば、ソースサーバ上に余分に保管される先行書き込みログは必要ありません。

tar形式が使われれば、先行書き込みログファイルは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を参照してください)。

-C
--create-slot

バックアップ開始前に--slotオプションで名づけられたレプリケーションスロットを作成することを指定します。 スロットが既に存在する場合、エラーが生じます。

-l label
--label=label

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

-n
--no-clean

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

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

-N
--no-sync

デフォルトではpg_basebackupは全てのファイルがディスクに安全に書き出されるのを待ちます。 このオプションでpg_basebackupは待つことなく返ります。これは高速ですが、その後のオペレーションシステムのクラッシュでベースバックアップの破損が残るかもしれないことを意味します。 一般にこのオプションはテスト用に有用なのであって、本番導入の際に使うべきではありません。

-P
--progress

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

-r rate
--max-rate=rate

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

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

-S slotname
--slot=slotname

このオプションは-X streamと一緒でのみ使用できます。 これはWALストリーミングに指定したレプリケーションスロットを使用させます。 レプリケーションスロットを使うストリーミングレプリケーションのスタンバイとしてベースバックアップを使用するつもりであるなら、スタンバイはprimary_slot_nameと同じレプリケーションスロット名を使うべきです。 これにより、ベースバックアップ終了と新しいスタンバイでのストリーミングレプリケーション開始の間の時間にプライマリサーバが必要なWALデータを削除しないことが確実になります。

指定されたレプリケーションスロットは、オプション-Cも使われている場合を除き、存在していなければなりません。

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

-v
--verbose

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

--manifest-checksums=algorithm

バックアップマニフェストに含まれる各ファイル適用されるチェックサムアルゴリズムを指定します。 現在利用できるアルゴリズムはNONECRC32CSHA224SHA256SHA384SHA512です。 デフォルトはCRC32Cです。

NONEが選択されれば、バックアップマニフェストはチェックサムを含みません。 それ以外の場合、バックアップ内の各ファイルの指定したアルゴリズムを使ったチェックサムを含みます。 さらに、マニフェストは自身の内容のSHA256チェックサムを常に含みます。 SHAアルゴリズムはCRC32CよりもかなりCPU集約的なため、そのどれかを1つを選択するとバックアップの完了に掛かる時間が増えるでしょう。

SHAハッシュ関数を使うと、バックアップが変更されていないことを検証したい利用者にとっては暗号学的に安全な各ファイルのダイジェストが提供されますが、一方、CRC32Cアルゴリズムでは計算がずっと速いチェックサムが提供されます。偶発的な変更によるエラーを補足するのには良いですが、悪意のある修正に抵抗力はありません。 バックアップにアクセスした敵に対抗するのに有用なように、バックアップマニフェストは、どこか他のところに安全に保管するか、バックアップが取られて以来変更されたことがないのを検証する必要があることに注意してください。

pg_verifybackupを使ってバックアップマニフェストに対するバックアップの完全性を検査できます。

--manifest-force-encode

バックアップマニフェスト内のファイル名をすべて強制的に16進数でエンコードします。 このオプションが指定されなければ、UTF8でないファイル名だけが16進数でエンコードされます。 このオプションは主に、バックアップマニフェストファイルを読むツールが、この場合を正しく扱うか試験することを意図しています。

--no-estimate-size

ストリームされるバックアップデータの総量をサーバが評価しないようにします。その結果、pg_stat_progress_basebackupビューのbackup_total列は常にNULLになります。

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

--progressを使う場合には、このオプションは認められません。

--no-manifest

バックアップマニフェストを生成しないようにします。 このオプションが指定されなければ、サーバはpg_verifybackupを使って検証できるバックアップマニフェストを生成し送信します。 マニフェストは、含まれるかもしれないWALファイルを除いて、バックアップの中にある各ファイルの一覧です。 各ファイルの大きさや最終修正時刻、省略可能なチェックサムも保存されます。

--no-slot

バックアップ時に一時レプリケーションスロットを作成しないようにします。

デフォルトでは、ログストリーミングが選択されたものの-Sオプションでスロット名が与えられなかった場合、(ソースサーバがサポートしていれば)一時レプリケーションスロットが作成されます。

このオプションの主な目的は、サーバにレプリケーションスロットの空きが無いときにベースバックアップを取得できるようにすることです。 レプリケーションスロットを使うことは、必要とされるWALがバックアップ中のサーバにより削除されることを防止するため、ほとんどの場合に好ましいです。

--no-verify-checksums

ベースバックアップ取得元のサーバでチェックサムの検証が有効になっている場合に、チェックサムの検証を無効化します。

デフォルトでは、チェックサムは検証され、チェックサムエラーは非ゼロの終了ステータスをもたらします。 とはいえ、このような場合には、--no-cleanオプションが使われていたかのように、ベースバックアップは削除されません。 チェックサム検証の失敗はpg_stat_databaseビューでも報告されます。

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

-d connstr
--dbname=connstr

サーバとの接続のために使用するパラメータを、接続文字列として指定します。 衝突するコマンドラインオプションよりも優先します。

このオプションは他のクライアントアプリケーションとの整合性のために--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参照)を使用します。

環境変数PG_COLORは診断メッセージで色を使うかどうかを指定します。 可能な値はalwaysautoneverです。

注意

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

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

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

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

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

pg_basebackupは、ソースのクラスタでグループパーミッションが有効になっている場合、データファイルに対するグループパーミッションを維持します。

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