設定要寫入輸出的目標目錄。pg_basebackup 將建立此目錄（以及任何遺失的父目錄）（如果該目錄不存在）。如果它已存在，則必須為空。

當備份採用 tar 格式時，目標目錄可以指定為 - (dash)，導致 tar 檔案寫入到 stdout。

此選項為必填項。

選擇輸出的格式。格式 可以是以下之一

執行增量備份。必須提供參考備份的備份資訊清單 (manifest)，並上傳到伺服器，伺服器會傳送要求的增量備份做為回應。

建立一個 standby.signal 檔案，並將連線設定附加到目標目錄中的 postgresql.auto.conf 檔案（或在使用 tar 格式時，附加到基本封存檔案中）。這簡化了使用備份結果設定待機伺服器的流程。

postgresql.auto.conf 檔案會記錄連線設定，如果已指定，也會記錄 pg_basebackup 正在使用的複製槽，以便串流複製和邏輯複製槽同步稍後使用相同的設定。只有在連線字串或 環境變數中明確指定 dbname 時，才會記錄 dbname。

指示伺服器將基本備份放置在哪裡。預設目標為 client，表示應將備份傳送到執行 pg_basebackup 的機器。如果目標改為設定為 server:/some/path，則備份將儲存在執行伺服器的機器上的 /some/path 目錄中。將備份儲存在伺服器上需要超級使用者權限或具有 pg_write_server_files 角色的權限。如果目標設定為 blackhole，則會捨棄內容且不會儲存在任何地方。這僅應用於測試目的，因為最終不會得到實際的備份。

由於 WAL 串流是由 pg_basebackup 而不是由伺服器實現的，因此此選項不能與 -Xstream 一起使用。由於這是預設值，因此指定此選項時，還必須指定 -Xfetch 或 -Xnone。

在備份期間將目錄 olddir 中的表空間重新定位到 newdir。為了生效，olddir 必須完全符合表空間在來源伺服器上定義的路徑規格。（但如果來源伺服器中沒有 olddir 中的表空間，則不會出錯。）同時，newdir 是接收主機檔案系統中的目錄。與主要目標目錄一樣，newdir 不必已存在，但如果確實存在，則必須為空。 olddir 和 newdir 都必須是絕對路徑。如果任一路徑需要包含等號 (=)，請在其前面加上反斜線。可以多次指定此選項以用於多個表空間。

如果以這種方式重新定位表空間，則會更新主資料目錄內的符號連結，以指向新的位置。因此，新的資料目錄已準備好用於具有更新位置的所有表空間的新伺服器執行個體。

目前，此選項僅適用於 plain 輸出格式；如果選擇 tar 格式，則會忽略它。

設定寫入 WAL（預寫式日誌）檔案的目錄。預設情況下，WAL 檔案將放置在目標目錄的 pg_wal 子目錄中，但可以使用此選項將它們放置在其他位置。waldir 必須是絕對路徑。與主要目標目錄一樣，waldir 不必已存在，但如果確實存在，則必須為空。只有在備份採用 plain 格式時，才能指定此選項。

在備份中包含所需的 WAL（預寫式日誌）檔案。這將包含備份期間產生的所有預寫式日誌。除非指定了方法 none，否則可以在目標目錄中啟動 postmaster，而無需查閱 WAL 封存，從而使輸出成為完全獨立的備份。

支援以下收集預寫式日誌的 method：

使用預設壓縮等級啟用 tar 檔案輸出的 gzip 壓縮。壓縮僅在使用 tar 格式時可用，並且後綴 .gz 將自動新增到所有 tar 檔案名稱。

請求壓縮備份。如果包含 client 或 server，則指定在哪裡執行壓縮。在伺服器上壓縮會減少傳輸頻寬，但會增加伺服器 CPU 的消耗。預設值為 client，除非使用了 --target。在這種情況下，備份不會發送到客戶端，因此只有伺服器壓縮才合理。當使用預設的 -Xstream 時，伺服器端壓縮不會應用於 WAL。要壓縮 WAL，請使用客戶端壓縮，或指定 -Xfetch。

壓縮方法可以設定為 gzip、lz4、zstd、none (不壓縮)，或一個整數（0 表示不壓縮，大於 0 表示 gzip）。可以選擇性地指定壓縮詳情字串。如果詳情字串是一個整數，則指定壓縮等級。否則，它應該是一個逗號分隔的項目列表，每個項目的格式為 keyword 或 keyword=value。目前，支援的關鍵字有 level、long 和 workers。當壓縮方法指定為純整數時，不能使用詳情字串。

如果未指定壓縮等級，將使用預設的壓縮等級。如果僅指定等級而未提及演算法，則如果等級大於 0，將使用 gzip 壓縮；如果等級為 0，則不使用壓縮。

當 tar 格式與 gzip、lz4 或 zstd 一起使用時，後綴 .gz、.lz4 或 .zst 將自動新增到所有 tar 檔案名稱。當使用純格式時，可能無法指定客戶端壓縮，但仍然可以請求伺服器端壓縮。如果這樣做，伺服器將壓縮備份以進行傳輸，而客戶端將解壓縮並提取它。

當此選項與 -Xstream 結合使用時，如果選擇了客戶端 gzip 壓縮，則 pg_wal.tar 將使用 gzip 壓縮，但如果選擇了任何其他壓縮演算法，或選擇了伺服器端壓縮，則不會壓縮。

設定檢查點模式為快速（立即）或分散（預設）（請參閱第 25.3.4 節）。

指定應在開始備份之前建立由 --slot 選項命名的複製槽。如果該插槽已存在，則會引發錯誤。

設定備份的標籤。如果未指定，將使用預設值 “pg_basebackup 基本備份”。

預設情況下，當 pg_basebackup 因錯誤中止時，它會刪除在發現無法完成作業之前可能已建立的任何目錄（例如，目標目錄和預寫日誌目錄）。此選項禁止清理，因此對於偵錯很有用。

請注意，表空間目錄無論如何都不會被清理。

預設情況下，pg_basebackup 將等待所有檔案安全地寫入磁碟。此選項導致 pg_basebackup 在不等待的情況下返回，這更快，但意味著隨後的作業系統崩潰可能會使基本備份損壞。通常，此選項對於測試很有用，但不應在建立生產安裝時使用。

啟用進度報告。開啟此功能將在備份期間提供近似的進度報告。由於資料庫可能會在備份期間發生變化，因此這僅是一個近似值，並且可能不會正好結束於 100%。特別是，當 WAL 日誌包含在備份中時，無法預先估計資料總量，在這種情況下，一旦超過不含 WAL 的總估計值，估計的目標大小將會增加。

設定從來源伺服器收集資料的最大傳輸速率。這可用於限制 pg_basebackup 對伺服器的影響。值以每秒千位元組為單位。使用 M 後綴表示每秒兆位元組。也接受 k 後綴，但沒有任何影響。有效值介於每秒 32 千位元組和每秒 1024 兆位元組之間。

此選項始終影響資料目錄的傳輸。 WAL 檔案的傳輸僅在收集方法為 fetch 時才會受到影響。

此選項只能與 -X stream 一起使用。它會使 WAL 串流使用指定的複製槽。如果基本備份旨在用作使用複製槽的串流複製備援伺服器，則備援伺服器應使用與 primary_slot_name 相同的複製槽名稱。這可確保主要伺服器不會在基本備份結束和新備援伺服器上開始串流複製之間的這段時間內刪除任何必要的 WAL 資料。

除非同時使用 -C 選項，否則指定的複製槽必須存在。

如果未指定此選項且伺服器支援臨時複製槽（版本 10 及更高版本），則會自動使用臨時複製槽進行 WAL 串流。

設定為 fsync（預設值）時，pg_basebackup 將遞迴地開啟並同步備份目錄中的所有檔案。當使用純格式時，搜尋檔案將會追蹤 WAL 目錄和每個設定的表空間的符號連結。

在 Linux 上，可以使用 syncfs 來要求作業系統同步包含備份目錄的整個檔案系統。當使用純格式時，pg_basebackup 也會同步包含 WAL 檔案和每個表空間的檔案系統。有關使用 syncfs 時需要注意的注意事項，請參閱recovery_init_sync_method。

當使用 --no-sync 時，此選項無效。

啟用詳細模式。將在啟動和關閉期間輸出一些額外的步驟，並且如果也啟用了進度報告，則會顯示目前正在處理的確切檔案名稱。

指定應該應用於備份清單中包含的每個檔案的檢查碼演算法。目前，可用的演算法有 NONE、CRC32C、SHA224、SHA256、SHA384 和 SHA512。預設值為 CRC32C。

如果選擇 NONE，則備份清單將不包含任何檢查碼。否則，它將包含備份中每個檔案的檢查碼，使用的演算法為指定的演算法。此外，清單始終包含其自身內容的 SHA256 檢查碼。SHA 演算法比 CRC32C 更消耗 CPU 資源，因此選擇其中一個可能會增加完成備份所需的時間。

使用 SHA 雜湊函數可為每個檔案提供密碼學上安全的摘要，供希望驗證備份是否未被竄改的使用者使用，而 CRC32C 演算法提供的檢查碼計算速度更快；它擅長捕獲由於意外更改而導致的錯誤，但無法抵抗惡意修改。請注意，為了有效地對抗可以存取備份的攻擊者，備份清單需要安全地儲存在其他地方，或者以其他方式驗證自備份以來未被修改。

可以使用 pg_verifybackup 來檢查備份的完整性，並與備份清單進行比較。

強制備份清單中的所有檔案名稱都進行十六進位編碼。如果未指定此選項，則只有非 UTF8 檔案名稱才會進行十六進位編碼。此選項主要用於測試讀取備份清單檔案的工具是否正確處理此情況。

阻止伺服器估計將要串流傳輸的備份資料總量，導致 backup_total 欄位在 pg_stat_progress_basebackup 檢視中始終為 NULL。

如果沒有這個選項，備份會先列舉整個資料庫的大小，然後再回去傳送實際的內容。這可能會使備份花費稍長的時間，特別是會花更長的時間才傳送第一筆資料。如果這個估計時間太長，這個選項可以避免這個估計時間。

使用 --progress 時，不允許使用此選項。

禁用備份清單的產生。如果未指定此選項，伺服器將產生並傳送一個可以使用 pg_verifybackup 驗證的備份清單。該清單是備份中存在的每個檔案的列表，除了可能包含的任何 WAL 檔案。它還儲存每個檔案的大小、上次修改時間和一個可選的檢查碼。

防止為備份建立臨時複製槽。

預設情況下，如果選擇了日誌串流但未使用 -S 選項提供槽名稱，則會建立一個臨時複製槽（如果源伺服器支援）。

此選項的主要目的是允許在伺服器沒有空閒複製槽時進行基礎備份。使用複製槽幾乎總是首選，因為它可以防止伺服器在備份期間移除所需的 WAL。

禁用檢查碼驗證，如果它們在從中取得基礎備份的伺服器上啟用。

預設情況下，會驗證檢查碼，並且檢查碼驗證失敗將導致非零的退出狀態。但是，在這種情況下不會移除基礎備份，就像使用了 --no-clean 選項一樣。檢查碼驗證失敗也會在 pg_stat_database 檢視中報告。

指定用於連線到伺服器的參數，作為 連線字串；這些參數將覆蓋任何衝突的命令列選項。

為了與其他客戶端應用程式保持一致，此選項稱為 --dbname，但由於 pg_basebackup 不會連線到叢集中任何特定的資料庫，因此連線字串中包含的任何資料庫名稱都會被伺服器忽略。但是，以這種方式提供的資料庫名稱會覆寫預設資料庫名稱 (replication)，以便在 ~/.pgpass 中查詢複製連線的密碼。同樣，用於連線到 PostgreSQL 的中介軟體或代理程式可能會使用該名稱來進行連線路由等目的。資料庫名稱也可以被 邏輯複製槽同步使用。

指定伺服器正在執行的機器的 hostname。如果值以斜線開頭，則將其用作 Unix 域套接字的目錄。預設值取自 PGHOST 環境變數（如果已設定），否則將嘗試 Unix 域套接字連線。

指定伺服器正在監聽連線的 TCP port 或本機 Unix 域套接字檔案擴充功能。預設為 PGPORT 環境變數（如果已設定）或編譯到程式中的預設值。

指定傳回給來源伺服器的狀態封包之間的秒數。較小的值允許從伺服器更準確地監控備份進度。值為零會完全禁用定期狀態更新，儘管在伺服器請求時仍會傳送更新，以避免基於超時的斷開連線。預設值為 10 秒。

指定要連線的使用者名稱。

防止發出密碼提示。如果伺服器需要密碼驗證，並且無法透過其他方式（例如 .pgpass 檔案）取得密碼，則連線嘗試將失敗。在批次作業和沒有使用者存在的腳本中，此選項可能很有用。

強制 pg_basebackup 在連線到來源伺服器之前提示輸入密碼。

這個選項並非總是必要的，因為如果伺服器要求密碼驗證，pg_basebackup 會自動提示輸入密碼。但是，pg_basebackup 會浪費一次連線嘗試，以找出伺服器需要密碼。在某些情況下，值得輸入 -W 以避免額外的連線嘗試。

印出 pg_basebackup 版本並結束。

顯示 pg_basebackup 命令列引數的說明，然後結束。