pgBackRest 2.59.1 ドキュメント

• 1: コマンドリファレンス
  • 1.1: ヘルプ コマンド (help)
  • 1.2: バージョン コマンド (version)
• 2: よくある質問
• 3: プロジェクトの指標

1 - コマンドリファレンス

導入

コマンドは、さまざまな pgBackRest 関数を実行するために使用されます。ここでは、コマンド オプションが網羅的にリストされています。つまり、コマンドに適用される各オプションは、1 つ以上の他のコマンドに適用される場合でも、そのコマンドとともにリストされます。これには、pgbackrest.conf で構成できるすべてのオプションが含まれます。

pgbackrest.conf で構成された非ブール型オプションは、reset- プレフィックスを使用してコマンドラインでデフォルトにリセットできます。この機能は、バックアップをリポジトリ ホストに直接復元するために使用できます。通常、pgBackRest はデータベース ホストがリモートにあり、復元をリモートで実行できないことがわかるため、エラーが発生します。コマンドラインに --reset-pg1-host を追加すると、pgBackRest はリモート データベース ホストを無視し、ローカルに復元します。特定のパス (データベース ホストで使用されているパスではない) で復元を強制的に実行するには、新しい --pg1-path を渡すことが必要な場合があります。

no- プレフィックスは、コマンドラインでブール型オプションを false に設定するために使用できます。

PGBACKREST_ プレフィックスと、- を _ に置き換えるすべて大文字のオプション名を使用して、任意のオプションを環境変数に設定できます。 pg1-path は PGBACKREST_PG1_PATH になり、stanza は PGBACKREST_STANZA になります。ブール値オプションは、設定ファイル内にあるものと同じように表現されます。 PGBACKREST_COMPRESS="n" および reset-* のバリアントは許可されません。コマンドラインまたは構成ファイルで複数回指定できるオプションは、値をコロンで区切ることで表すことができます。 PGBACKREST_DB_INCLUDE="db1:db2"。

コマンドライン オプションは、構成ファイル オプションをオーバーライドする環境オプションをオーバーライドします。

オプションの種類については、構成の概要 を参照してください。

コマンド

1.1 - ヘルプ コマンド (help)

3 つのレベルのヘルプが用意されています。コマンドが指定されない場合は、一般のヘルプが表示されます。コマンドが指定された場合（例：pgbackrest help backup）、そのコマンドの詳細な説明と有効なオプションの一覧が表示されます。コマンドに加えてオプションが指定された場合（例：pgbackrest help backup type）、そのオプションがコマンドに適用される際の詳細な説明が表示されます。

コマンドオプション

ヘルプオプションの表示 (--help)

ヘルプを表示します。

ヘルプを表示します。help コマンドが指定されていなくても同様に機能し、--version オプションを上書きします。

default: n
example: --help

バージョンオプションの表示 (--version)

バージョンを表示します。

バージョン情報を表示します。version または help コマンドが指定されていなくても同様です。

default: n
example: --version

1.2 - バージョン コマンド (version)

pgBackRest のインストール済みバージョンを表示します。

コマンドオプション

出力オプション (--output)

出力形式。

次の出力形式がサポートされています：

• text - インストールされた pgBackRest のバージョンをテキスト形式で表示します。
• num - pgBackRest のインストール済みバージョンを整数で表示します。

default: text
example: --output=num

2 - よくある質問

はじめに

よくある質問では、ユーザーガイド、構成リファレンス、コマンドリファレンスで説明されている場合も、されていない場合もある個別の疑問について、詳しく説明します。ここで問題に関する情報が見つからない場合は、pgBackRestのGitHubのIssue一覧 も有用な情報源です。

「could not find WAL segment」エラーが発生した場合はどうすればよいですか。

このエラーはさまざまな問題によって発生する可能性があります。たとえば、次のような原因が考えられます。

• archive_commandの設定ミス
• pgBackRest構成ファイルの設定ミス
• ネットワークまたは権限の問題
• サードパーティー製品（S3、Swift、Minioなど）の設定の問題
• アーカイブ待ちのWALが大量にキューにたまっている

次の確認を推奨します。

• PostgreSQLのarchive_commandを確認する
• 各ホストのpgBackRest構成設定を確認する（たとえば、リポジトリホストにpg*の設定、pgホストにrepo*の設定が指定されているか）
• --archive-timeoutをpgBackRest構成ファイル内の値（またはデフォルト値）より大きくしてcheckコマンドを実行し、WALキューを処理し終えるまでにより長い時間が必要かどうかを確認する。システムで大量のWALを生成している場合は、非同期アーカイブ の構成を検討する

バックアップセットを手動で削除するにはどうすればよいですか。

コマンドリファレンス：Expire で説明しているとおり、--setオプションを使用してフルバックアップセットを期限切れとして削除できます。

コマンドごとにオプションを個別に設定するにはどうすればよいですか。

pgBackRestでは、構成ファイル内でコマンドごとにオプションを個別に設定できます。クラスターのstanzaの構成 で、この機能とオプションの優先順位を詳しく説明しています。

たとえば、コマンドごとにprocess-maxオプションを最適化できます。

[global]
# used where not overridden
process-max=2

[global:backup]
# more cores for backup
process-max=4

[global:restore]
# all the cores for restore
process-max=8

[global:archive-push]
# more cores for archive-push
process-max=3

[global:archive-get]
# fewer cores for archive-get
process-max=1

S3バケット名にドット（ピリオド）を使用できますか。

RFC-2818では、ワイルドカードをドット（.）に一致させることを認めていないため、S3バケット名にドットを含めてはなりません。S3バケット名にドットが含まれると、「unable to find hostname ‘my.backup.bucket.s3.amazonaws.com’ in certificate common name or subject alternative names」などのエラーが発生します。

例外はrepo-s3-uri-style=pathです。これは、バケットをホストではなくURIの先頭に付加します。バケットがホスト名の一部ではないため、証明書はエンドポイントのみと照合され、バケット名内のドットは問題になりません。ただし、すべてのS3互換オブジェクトストアがパス形式のURIをサポートしているわけではありません。

以前のバージョンのpgBackRestのパッケージはどこにありますか。

apt.postgresql.org リポジトリでは、以前のバージョンのアーカイブ を管理しています。Debianでも、すべてのテストビルドのスナップショット を管理しています。

backup-standby=yでスタンバイデータベースが停止していると、バックアップが失敗するのはなぜですか。

スタンバイからのバックアップを構成する主な目的は、プライマリーの負荷を減らすことです。そのため、スタンバイが停止したときにバックアップをプライマリーへ切り替えると、多くの場合、その目的を果たせなくなります。システムですでに障害が発生している状況で、プライマリーにさらに負荷をかけることは推奨しません。比較的新しいバックアップがあれば、バックアップ取得は緊急の作業ではありません。重要なのは、WALのアーカイブを遅れずに続けることです。システムが再び安定してからバックアップを取得する時間は十分にあります。

どうしてもバックアップが必要であれば、スタンバイを増やすか、backup-standbyを削除することが解決策になります。コマンドラインで--no-backup-standbyを指定すれば上書きできるため、一度だけのバックアップのために構成を変更する必要はありません。

リポジトリはスタンバイホストに配置すべきですか。

いいえ。プライマリーとスタンバイのデータベースを構成する場合、フェイルオーバーをシームレスに処理できるように、pgBackRestの構成ファイルは対称にすることを推奨します。そうでなければ、フェイルオーバー時に構成を変更する必要があり、さらに問題が生じる可能性もあります。

詳しくは、ユーザーガイドの専用リポジトリホスト のセクションを参照してください。

時刻を指定したポイントインタイムリカバリーが動作しないように見えるのはなぜですか。

時刻を指定したポイントインタイムリカバリーで最もよくある間違いは、目標時刻より前のバックアップセットを選び忘れることです。--setオプションを指定していない場合、pgBackRestは--target=で指定した時刻に向けて再生できるバックアップを見つけようとします。バックアップセットが見つからなければ、デフォルトで最新のバックアップをリストアします。ただし、最新のバックアップが目標時刻より後の場合、PostgreSQLは--target=を有効なものとみなさず無視するため、利用可能な最新時刻までWALリカバリーが進みます。

--setオプションを使用するには、infoコマンドを実行し、終了タイムスタンプが目標時刻より前のバックアップを見つけてバックアップセットを選択します。リストアを実行するときに、--set=BACKUP_LABELオプションを指定します。BACKUP_LABELは選択したバックアップセットです。

詳しくは、ユーザーガイドのポイントインタイムリカバリー のセクションを参照してください。

WALアーカイブの接尾辞は何を意味しますか。

接尾辞は、ファイルの整合性を検証するためのSHA1チェックサムです。省略する方法はありません。

バックアップの種類（フル、差分、増分）によってリストアにかかる時間は長くなりますか。

どの種類のバックアップも、リストアに必要な時間は同じです。リストアではバックアップマニフェストに基づいてファイルを取得します。増分バックアップや差分バックアップの場合、マニフェストが以前のバックアップ内のファイルを参照することがあります。バックアップの種類によって、バックアップの作成にかかる時間には差が生じることがありますが、ディスクI/O、ネットワークI/Oなどが同じであれば、リストア時間を決めるのはデータベースのサイズです。

ネットワークから隔離された環境で使用するために、バックアップをエクスポートするにはどうすればよいですか。

pgBackRestは、バックアップやWALアーカイブの保存だけでなく、圧縮、暗号化、ファイルのバンドル化といった機能に必要な重要なメタデータの維持にもリポジトリを使用します。このため、非常に限定的で厳しい条件を満たさない限り、バックアップとWALファイルの一部を単純にコピーするだけでは、通常は動作しません。

ただし、データベースを単独で利用できる形でエクスポートし、USBなどで転送することが目的であれば、回避策があります。--archive-copy オプションを有効にしてバックアップを作成し、必要なWALセグメントがバックアップとともに保存されるようにします。その後、--type=none --pg1-path=/your/target/pathを使用してリストアします。これにより、必要なWALファイルがすべてpg_walに配置された、リストア済みのPostgreSQLデータディレクトリが生成されます。これはpg_basebackupで作成されるものと似ています。

このディレクトリを別のシステムにコピーすれば、PostgreSQLはpgBackRestリポジトリにアクセスせずにリカバリーできるはずです。

このバックアップのリカバリーではタイムラインの切り替えが発生しないため、このクラスターはエクスポート元のリポジトリにWALを送信すべきではないことに注意してください。新しいクラスターがネットワークから隔離された環境にある場合、これは問題にならないはずです。

3 - プロジェクトの指標

コードカバレッジ

pgBackRest は、/src のコア C コードを完全に function/branch/line カバーすることを目指しています。

関数/行は例外なく完全にカバーされています。

ブランチ カバレッジでは、マクロ内のブランチと assert() 呼び出しは除外されます。マクロには独自の単体テストがあるため、マクロが出現するすべての場所でテストする必要はありません。アサートは常に true であるべきケースをテストするため、完全な分岐カバレッジを持つことは期待されていません。

/test/src/module の C 単体テスト モジュールにも完全な関数/行が含まれていますが、レポートには含まれていません。