pg_basebackupは、稼動中のPostgreSQLデータベースクラスタのベースバックアップを取るために使用されます。 データベースへの他のクライアントに影響することなく、バックアップが取られます。 またこのバックアップはポイントインタイムリカバリ（項24.3参照）とログシッピングやストリーミングレプリケーションスタンバイサーバ用の開始点（項25.2参照）としても使用することができます。
pg_basebackupは、システムは自動的にバックアップモードにし、自動的にバックアップモードから戻ることを確実に行い、データベースクラスタファイルのバイナリコピーを作成します。 バックアップは常にデータベースクラスタ全体のバックアップを常に取ります。 個々のバックアップや個々のデータベースオブジェクトをバックアップすることはできません。 個々のデータベースバックアップに関してはpg_dumpなどのツールを使用しなければなりません。
バックアップは通常のPostgreSQL接続を経由して、レプリケーションプロトコルを用いて、作成されます。 この接続はREPLICATION権限（項20.2参照）を持つユーザが確立しなければなりません。 さらにユーザにはpg_hba.confにおける明示的な権限が許されていなければなりません。 またサーバでmax_wal_sendersを、バックアップ用に少なくとも１つのセッションを残すように十分高く設定する必要があります。
同時にpg_basebackupを複数実行することができます。 しかし性能という観点からは、１つのバックアップのみを取り結果をコピーする方が優れています。
以下のコマンドラインオプションは出力の場所と書式を制御します。
出力を書き出すディレクトリです。
バックアップがtarモードであり、かつ、指定したディレクトリが-（ダッシュ）の場合、tarファイルはstdoutに書き出されます。
このパラメータは必須です。
出力書式を選択します。 formatには以下のいずれかを取ることができます。
普通のファイルとして、現在のデータディレクトリとテーブル空間と同じレイアウトで、出力を書き出します。 クラスタがテーブル空間を追加で持たない場合、データベース全体が指定したディレクトリに格納されます。 クラスタが追加のテーブル空間を持つ場合は、主データディレクトリは指定したディレクトリ内に格納されますが、他のテーブル空間はすべて、サーバ上の同じ絶対パスに格納されます。
これがデフォルトの書式です。
指定したディレクトリ内にtarファイルとして出力を書き出します。 主データディレクトリはbase.tarという名前のファイルに書き出され、他のテーブル空間はすべてテーブル空間のOIDに因んだ名前のファイルに書き出されます。
対象ディレクトリとして-（ダッシュ）という値が指定された場合、tarの内容は標準出力に書き出されます。 これは例えばgzipへのパイプ処理に適しています。 これはクラスタが追加テーブル空間を持たない場合のみ行うことができます。
必要なトランザクションログファイル（WALファイル）をバックアップに含めます。 これはバックアップ中に生成されたトランザクションログをすべて含めます。 このオプションが指定された場合、ログアーカイブを考慮することなく展開したディレクトリ内でそのままpostmasterを起動することができます。 つまりこれは完全なスタンドアローンバックアップを作成します。
注意: トランザクションログファイルはバックアップ終了時点で集められます。 従い、wal_keep_segmentsパラメータが、バックアップが終わる前にログファイルが削除されないように、十分大きいことが必要です。 ログが転送時にすでにローテートされた場合、バックアップは失敗し使用することはできません。
tarファイル出力のデフォルトの圧縮レベルによるgzip圧縮を有効にします。 tarファイルを生成する場合のみ圧縮を利用することができます。
tarファイル出力のgzip圧縮を有効にします。 また圧縮レベル（1から9まで。9が最高の圧縮レベル）を指定します。 tarファイルを生成する場合のみ圧縮を利用することができます。
以下のコマンドラインオプションはバックアップの生成とこのプログラムの実行を制御します。
チェックポイントをfastまたはspread（デフォルト）に設定します。
バックアップのラベルを設定します。 何も指定がない場合、pg_basebackup base backupというデフォルト値が使用されます。
進行状況報告を有効にします。 これを有効にすると、バックアップ中におおよその進行状況が報告されます。 データベースはバックアップ中に変更があるかもしれませんので、これはおおよそでしかなく100%正確に終わらないかもしれません。 実際、WALログがバックアップに含まれる場合、データ総量は前もって予測することはできません。 このためこの場合、推定対象容量はWALなしの総推定量を過ぎた後増加します。
これが有効な場合、バックアップはまずデータベース全体容量を計算し、その後実際の内容に戻り、送信します。 バックアップに要する時間はかなり長くなるかもしれません。具体的にはデータが送られるようになるまでの時間がより長くなります。
冗長モードを有効にします。 開始時および終了段階でいくつか追加の段階が出力されます。 また進行状況報告も有効な場合、現在処理中のファイル名も正しく出力されます。
以下のオプションはデータベース接続パラメータを制御します。
サーバが稼働しているマシンのホスト名を指定します。 この値がスラッシュから始まる場合、Unixドメインソケット用のディレクトリとして使用されます。 デフォルトは、設定されていればPGHOST環境変数から取得されます。 設定されていなければ、Unixドメインソケット接続と仮定されます。
サーバが接続を監視するTCPポートもしくはローカルUnixドメインソケットファイルの拡張子を指定します。 デフォルトは、設定されている場合、PGPORT環境変数の値となります。設定されていなければ、コンパイル時のデフォルト値となります。
接続ユーザ名です。
パスワードの入力を促しません。 サーバがパスワード認証を必要とし、かつ、.pgpassファイルなどの他の方法が利用できない場合、接続試行は失敗します。 バッチジョブやパスワードを入力するユーザが存在しない場合にこのオプションは有用かもしれません。
データベースに接続する前に、pg_basebackupは強制的にパスワード入力を促します。
サーバがパスワード認証を要求する場合pg_basebackupは自動的にパスワード入力を促しますので、これが重要になることはありません。 しかし、pg_basebackupは、サーバにパスワードが必要かどうかを判断するための接続試行を無駄に行います。 こうした余計な接続試行を防ぐために-Wの入力が有意となる場合もあります。
その他、あまり使われませんが以下のパラメータも使用可能です。
pg_basebackupのバージョンを表示し終了します。
pg_basebackupコマンドライン引数の使用方法を表示し、終了します。
このバックアップには、設定ファイルとサードパーティによりディレクトリに格納された追加ファイルを含む、データディレクトリとテーブル空間内のすべてのファイルが含まれます。 データディレクトリ内には通常のファイルとディレクトリのみが許され、シンボリックリンクや特殊デバイスファイルは許されません。
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
（データベース内に複数のテーブル空間が存在する場合このコマンドは失敗します。）