# pg_basebackup ## Name pg_basebackup?--?做一個PostgreSQL 集群的基礎備份 ## Synopsis `pg_basebackup` [`_選項_`...] ## 描述 pg_basebackup用來給一個運行的PostgreSQL 數據庫集群進行基礎備份。進行時不會影響到連接到數據庫的客戶端，并且同時可以用于時間點恢復 （參閱[Section 24.3](#calibre_link-466)）和日志傳輸或流復制備用服務器的起始點 （參閱[Section 25.2](#calibre_link-1133)）。 pg_basebackup做一個數據庫集群文件的二進制拷貝， 同時確保系統自動進出自動備份模式。備份總是使用整個的數據庫集群， 不可能只備份單個的數據庫或數據庫對象。對于單個數據庫備份，必須使用如 [pg_dump](#calibre_link-437)的工具。 備份時通過一個普通的PostgreSQL連接制作的，并且使用復制協議。 該連接必須由超級用戶或一個擁有`REPLICATION`權限的用戶完成 （參閱[Section 20.2](#calibre_link-469)），并且`pg_hba.conf` 必須明確允許復制連接。該服務器也必須由[max_wal_senders](#calibre_link-470)配置， 設置足夠高的級別，對于備份至少有一個會話可用。 在同一時刻可能有多個`pg_basebackup`運行，但是從性能來說最好只采取一個備份，然后復制結果。 pg_basebackup不止可以從主機備份還可以從備機備份。要從備機備份， 設置備機以使其可以接受復制連接（也就是，設置`max_wal_senders` 和 [hot_standby](#calibre_link-1134)，并且配置[host-based authentication](#calibre_link-656)）。 也需要在主機上啟用[full_page_writes](#calibre_link-1135)。 請注意，這里有幾個從備機在線備份的限制： * 備份歷史文件不是在數據庫集群備份時創建的。 * 不保證所有需要備份的WAL文件在備份的最后歸檔。如果你計劃使用備份作為歸檔恢復， 并希望保證此刻所有需要的文件都可以使用，你需要通過使用`-x`選項將他們包含到備份中。 * 如果備機在在線備份期間被提升為主機，則備份失敗。 * 所有需要備份的WAL記錄必須包含足夠的全版書寫，這需要你在主機上啟用`full_page_writes` 并且不使用類似pg_compresslog這樣的工具作為`archive_command` 從WAL文件中刪除全版書寫。 ## 選項 下列的命令行選項控制輸出的位置和格式。 `-D` `_directory_``--pgdata=``_directory_` 寫輸出的目錄。pg_basebackup將創建目錄和任何父目錄（如果需要）。 該目錄可能已經存在，但是如果該目錄已經存在并且不為空則是一個錯誤。 當備份在tar模式，并且目錄以`-`（破折號）聲明，那么tar文件將寫入`stdout`。 這個選項是必需的。 `-F` `_format_` `--format=``_format_` 選擇輸出格式。`_format_`可以是下列之一： `p` `plain` 將輸出寫作普通的文件，該文件與當前數據目錄和表空間有相同的布局。當集群沒有額外的表空間時， 整個數據庫將被放入目標目錄中。如果集群包含額外的表空間，那么主數據目錄將被放入目標目錄中， 但是所有其他表空間將被放入與它們在服務器上相同的絕對路徑中。 這是缺省的格式。 `t` `tar` 將輸出寫作目標目錄中的tar文件。主數據目錄將被寫成一個命名為`base.tar` 的文件，所有其他表空間將以表空間OID命名。 如果值`-`（破折號）被聲明為目標目錄，那么tar內容將被寫成標準輸出， 適合于管道如gzip。只有集群沒有額外的表空間時這才是可能的。 `-R` `--write-recovery-conf` 在輸出目錄（或使用tar格式時為基礎歸檔文件）中寫一個最小的`recovery.conf` 以減輕設置一個備用服務器。 `-x` `--xlog` 使用這個選項等同于使用方法`fetch`的`-X`。 `-X` `_method_` `--xlog-method=``_method_` 在備份中包含所需的事務日志文件（WAL文件）。這將包括所有在備份期間產生的事務日志。 如果聲明了這個選項，那么直接在提取出的目錄（不需要參考日志歸檔）中啟動一個主進程是可能的。 因此使其成為一個完全獨立的備份。 支持下列收集事務日志的方法： `f` `fetch` 事務日志文件在備份結束時收集。因此，[wal_keep_segments](#calibre_link-1136) 參數有必要設置的足夠高，使日志在備份結束之前不會被刪除。如果日志在要被轉移的時候已經轉動了， 那么備份將失敗并且不能使用。 `s` `stream` 當備份創建時流事務日志。這將在運行備份時打開又一個到服務器的連接并并行啟動流事務日志。 因此，它將使用兩個[max_wal_senders](#calibre_link-470)參數配置的插槽。 只要客戶端可以跟上接收到的事務日志，使用這個方法需要沒有額外的事務日志在主機上保存。 `-z` `--gzip` 啟用tar文件輸出的gzip壓縮，使用缺省的壓縮級別。只有使用tar模式的時候可用壓縮。 `-Z` `_level_` `--compress=``_level_` 啟用tar文件輸出的gzip壓縮，并聲明壓縮級別（1到9，9為頂級壓縮）。只有使用tar模式的時候可用壓縮。 下列的命令行選項控制備份的生成和程序的運行。 `-c` `_fast|spread_` `--checkpoint=``_fast|spread_` 設置檢查點模式為fast或spread（缺省）。 `-l` `_label_` `--label=``_label_` 為備份設置標簽。如果沒有聲明，將使用"`pg_basebackup 基礎備份`"的默認值。 `-P` `--progress` 啟用進展報告。啟用這個選項將會在備份期間發送一個大概的進展報告。因為數據庫可能會在備份期間改變， 所以這只是一個大概并且可能不正好是`100%`結束。特別是， 當在備份中包含WAL日志時，數據的總量不能提前估計，并且這種情況下一旦它傳遞的總估計不包含WAL， 那么估計的目標大小還會增加。 當啟用這個選項時，備份將從枚舉整個數據庫的大小開始，然后返回并發送實際的內容。 這樣可能會導致備份時間稍長一些，尤其是在發送第一個數據之前的時間稍長。 `-v` `--verbose` 啟用冗長模式。將在啟動和關閉時輸出一些額外的步驟，如果也啟用了進度報告， 則也顯示當前正在被處理的準確的文件名。 下列的命令行選項控制數據庫連接參數。 `-d` `_connstr_` `--dbname=``_connstr_` 聲明用來連接到服務器的參數，作為一個連接字符串。參閱[Section 31.1.1](#calibre_link-458)獲取更多信息。 該選項被稱為`--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支持的環境變量（參閱[Section 31.14](#calibre_link-39)）。 ## 注意 備份將包含數據目錄和表空間中的所有文件，包括配置文件和任何第三方放置在目錄中的額外文件。 數據目錄中只允許普通的文件和目錄，不允許符號鏈接或特殊設備文件。 當恢復一個備份時，PostgreSQL管理表空間的方式， 所有額外表空間的路徑必須完全相同。不過，主數據目錄可以重新定位任意位置。 pg_basebackup可以作用于相同版本或更老版本的服務器（最低9.1）， 不過，WAL流模式（-X流）只能是服務器版本9.3。 ## 例子 在`mydbserver`創建一個服務器的基礎備份，并存儲到本地目錄 `/usr/local/pgsql/data`中： ``` <samp class="literal">$</samp> <kbd class="literal">pg_basebackup -h mydbserver -D /usr/local/pgsql/data</kbd> ``` 創建一個本地服務器的備份，用一個為每個表空間壓縮的tar文件，并存儲到目錄`backup`里， 運行時顯示進度報告： ``` <samp class="literal">$</samp> <kbd class="literal">pg_basebackup -D backup -Ft -z -P</kbd> ``` 創建一個單表空間本地數據庫的備份并使用bzip2壓縮： ``` <samp class="literal">$</samp> <kbd class="literal">pg_basebackup -D - -Ft | bzip2 > backup.tar.bz2</kbd> ``` 如果數據庫中有多個表空間那么這個命令將會失敗。 ## 又見 [pg_dump](#calibre_link-437)