pg_dumpall — 將一個 PostgreSQL 資料庫叢集匯出為指令碼檔案
pg_dumpall [連線選項...] [選項...]
pg_dumpall 是一個實用程式,用於將叢集中的所有 PostgreSQL 資料庫匯出(“轉儲”)到一個指令碼檔案中。指令碼檔案包含SQL可用於 psql 輸入以恢復資料庫的命令。它透過為叢集中的每個資料庫呼叫 pg_dump 來實現。 pg_dumpall 還匯出對所有資料庫通用的全域性物件,即資料庫角色、表空間以及配置引數的許可權授予。(pg_dump 不儲存這些物件。)
由於 pg_dumpall 讀取所有資料庫的表,因此您很可能需要以資料庫超級使用者的身份連線才能生成完整的轉儲。此外,您還需要超級使用者許可權來執行儲存的指令碼,以便允許新增角色並建立資料庫。
SQL 指令碼將寫入標準輸出。使用 -f/--file 選項或 shell 運算子將其重定向到檔案。
pg_dumpall 需要多次連線到 PostgreSQL 伺服器(每個資料庫一次)。如果您使用密碼認證,它將每次都要求輸入密碼。在這種情況下,擁有一個 ~/.pgpass 檔案會很方便。有關更多資訊,請參閱 第 32.16 節。
恢復轉儲會導致目標執行源超級使用者選擇的任意程式碼。部分轉儲和部分恢復不能限制這一點。如果源超級使用者不受信任,則在恢復之前必須檢查轉儲的 SQL 語句。請注意,執行轉儲和恢復的客戶端不需要信任源或目標超級使用者。
以下命令列選項控制輸出的內容和格式。
-a--data-only僅轉儲資料,不轉儲模式(資料定義)或統計資訊。
-c--clean發出 SQL 命令以在重新建立所有轉儲的資料庫、角色和表空間之前 DROP 它們。當恢復將覆蓋現有叢集時,此選項很有用。如果目標叢集中不存在任何物件,則在恢復期間將報告可忽略的錯誤訊息,除非還指定了 --if-exists。
-E 編碼--encoding=編碼以指定的字元集編碼建立轉儲。預設情況下,轉儲以資料庫編碼建立。(另一種獲得相同結果的方法是將 PGCLIENTENCODING 環境變數設定為所需的轉儲編碼。)
-f filename--file=filename將輸出傳送到指定的檔案。如果省略,則使用標準輸出。
-g--globals-only僅轉儲全域性物件(角色和表空間),不轉儲資料庫。
-O--no-owner不輸出命令來設定物件的屬主以匹配原始資料庫。預設情況下,pg_dumpall 會發出 ALTER OWNER 或 SET SESSION AUTHORIZATION 語句來設定建立的模式元素的所有權。除非指令碼由超級使用者(或指令碼中所有物件的同一使用者)啟動,否則在執行時執行這些語句將失敗。要建立任何使用者都可以恢復但會賦予該使用者所有物件所有權的指令碼,請指定 -O。
-r--roles-only僅轉儲角色,不轉儲資料庫或表空間。
-s--schema-only僅轉儲物件定義(模式),不轉儲資料。
-S username--superuser=username指定在停用觸發器時要使用的超級使用者名稱。僅當使用 --disable-triggers 時才相關。(通常,最好省略此項,而是將生成的指令碼以超級使用者身份啟動。)
-t--tablespaces-only僅轉儲表空間,不轉儲資料庫或角色。
-v--verbose指定詳細模式。這將導致 pg_dumpall 將開始/停止時間輸出到轉儲檔案,並將進度訊息輸出到標準錯誤。重複該選項將導致其他除錯級別的訊息出現在標準錯誤上。該選項也會傳遞給 pg_dump。
-V--version列印 pg_dumpall 版本並退出。
-x--no-privileges--no-acl阻止轉儲訪問許可權(GRANT/REVOKE 命令)。
--binary-upgrade此選項供就地升級實用程式使用。不建議或不支援將其用於其他目的。該選項的行為可能在未來的版本中更改,恕不另行通知。
--column-inserts--attribute-inserts將資料轉儲為帶有顯式列名的 INSERT 命令(INSERT INTO )。這將導致恢復非常緩慢;它主要用於生成可以載入到非 PostgreSQL 資料庫中的轉儲。table (column, ...) VALUES ...
--disable-dollar-quoting此選項停用函式體使用美元引用,並強制使用 SQL 標準字串語法進行引用。
--disable-triggers此選項僅在建立包含資料但不包含模式的轉儲時相關。它指示 pg_dumpall 在恢復資料時包含暫時停用目標表上的觸發器的命令。如果您有引用完整性檢查或其他觸發器,並且不希望在資料恢復期間觸發它們,請使用此選項。
目前,為 --disable-triggers 發出的命令必須以超級使用者身份執行。因此,您還應該使用 -S 指定超級使用者名稱,或者最好注意將生成的指令碼以超級使用者身份啟動。
--exclude-database=模式不轉儲名稱與 模式 匹配的資料庫。可以透過編寫多個 --exclude-database 開關來排除多個模式。 模式 引數根據 psql 的 \d 命令使用的相同規則(請參閱 模式)進行解釋,因此透過在模式中使用萬用字元字元也可以排除多個數據庫。使用萬用字元時,請務必根據需要引用該模式,以防止 shell 萬用字元展開。
--extra-float-digits=數字在轉儲浮點資料時使用指定的 extra_float_digits 值,而不是可用的最大精度。用於備份目的的常規轉儲不應使用此選項。
--filter=filename指定一個檔名,從中讀取要從轉儲中排除的資料庫的模式。模式的解釋與 --exclude-database 的規則相同。要從 STDIN 讀取,請使用 - 作為檔名。 --filter 選項可以與 --exclude-database 結合使用以排除資料庫,也可以指定多次以使用多個篩選器檔案。
該檔案每行列出一個數據庫模式,格式如下:
exclude database PATTERN
以 # 開頭的行被視為註釋並被忽略。註釋也可以放在物件模式行之後。空行也被忽略。有關如何在模式中進行引用的資訊,請參見 模式。
--if-exists使用 DROP ... IF EXISTS 命令來刪除 --clean 模式中的物件。這會抑制可能報告的“不存在”錯誤。此選項僅在也指定了 --clean 時才有效。
--inserts將資料轉儲為 INSERT 命令(而不是 COPY)。這將導致恢復非常緩慢;它主要用於生成可以載入到非 PostgreSQL 資料庫中的轉儲。請注意,如果您重新排列了列順序,恢復可能會完全失敗。--column-inserts 選項更安全,但速度更慢。
--load-via-partition-root在轉儲表分割槽的時,將 COPY 或 INSERT 語句的目標設為包含該分割槽的分層結構的根,而不是分割槽本身。這將導致在載入資料時為每一行重新確定適當的分割槽。當在行不一定能落入與原始伺服器相同的分割槽中的伺服器上恢復資料時,這可能很有用。例如,如果分割槽列是 text 型別,並且兩個系統對用於排序分割槽列的排序規則有不同的定義,則可能會發生這種情況。
--lock-wait-timeout=超時在轉儲開始時不要永遠等待獲取共享表鎖。相反,如果無法在指定的 超時 內鎖定表,則失敗。超時可以以 SET statement_timeout 接受的任何格式指定。
--no-comments不轉儲 COMMENT 命令。
--no-data不轉儲資料。
--no-policies不轉儲行安全策略。
--no-publications不轉儲出版物。
--no-role-passwords不轉儲角色的密碼。恢復時,角色將具有 null 密碼,並且密碼認證將始終失敗,直到設定密碼為止。由於在指定此選項時不需要密碼值,因此從 catalog 檢視 pg_roles 而不是 pg_authid 讀取角色資訊。因此,如果 pg_authid 的訪問受到某些安全策略的限制,此選項也有助於解決此問題。
--no-schema不轉儲模式(資料定義)。
--no-security-labels不轉儲安全標籤。
--no-statistics不轉儲統計資訊。這是預設行為。
--no-subscriptions不轉儲訂閱。
--no-sync預設情況下,pg_dumpall 將等待所有檔案安全寫入磁碟。此選項會導致 pg_dumpall 在不等待的情況下返回,這樣速度更快,但這意味著後續的作業系統崩潰可能會導致轉儲損壞。通常,此選項對於測試很有用,但不應用於從生產環境轉儲資料。
--no-table-access-method不輸出用於選擇表訪問方法的命令。使用此選項,所有物件都將使用恢復期間的預設表訪問方法建立。
--no-tablespaces不輸出建立表空間的命令,也不為物件選擇表空間。使用此選項,所有物件將在恢復期間的預設表空間中建立。
--no-toast-compression不輸出設定TOAST壓縮方法的命令。使用此選項,所有列將以預設壓縮設定進行恢復。
--no-unlogged-table-data不轉儲未記錄表的(unlogged tables)內容。此選項對是否轉儲表定義(模式)沒有影響;它僅阻止轉儲表資料。
--on-conflict-do-nothing向 INSERT 命令新增 ON CONFLICT DO NOTHING。除非還指定了 --inserts 或 --column-inserts,否則此選項無效。
--quote-all-identifiers強制引用所有識別符號。當從主 PostgreSQL 版本與 pg_dumpall 不同的伺服器轉儲資料庫,或當輸出旨在載入到不同主版本的伺服器中時,推薦使用此選項。預設情況下,pg_dumpall 僅引用其自身主版本中是保留字(reserved words)的識別符號。這有時會導致與其他版本(可能具有略微不同的保留字集合)的伺服器互動時出現相容性問題。使用 --quote-all-identifiers 可以避免此類問題,但代價是轉儲指令碼更難讀。
--restrict-key=restrict_key使用提供的字串作為轉儲輸出中的 psql \restrict 鍵。如果未指定 restrict 鍵,pg_dumpall 將在需要時生成一個隨機鍵。鍵只能包含字母數字字元。
此選項主要用於測試目的和其他需要可重複輸出(例如,比較轉儲檔案)的場景。不建議常規使用,因為帶有金鑰預知能力的惡意伺服器可能能夠注入任意程式碼,這些程式碼將在執行 psql 並使用轉儲輸出的機器上執行。
--rows-per-insert=行數將資料轉儲為 INSERT 命令(而不是 COPY)。控制每個 INSERT 命令的最大行數。指定的值必須是大於零的數字。恢復期間的任何錯誤只會導致屬於有問題 INSERT 的行丟失,而不是整個表內容丟失。
--statistics轉儲統計資訊。
--statistics-only僅轉儲統計資訊,不轉儲模式(資料定義)或資料。轉儲表、物化檢視、外部表和索引的統計資訊。
--sequence-data在轉儲中包含序列資料。這是預設行為,除非指定了 --no-data、--schema-only 或 --statistics-only。
--use-set-session-authorization輸出 SQL 標準 SET SESSION AUTHORIZATION 命令而不是 ALTER OWNER 命令來確定物件所有權。這使得轉儲更符合標準,但根據轉儲中物件的歷史,可能無法正確恢復。
-?--help顯示有關 pg_dumpall 命令列引數的幫助,然後退出。
以下命令列選項控制資料庫連線引數。
-d connstr--dbname=connstr指定用於連線伺服器的引數,作為連線字串;這些將覆蓋任何衝突的命令列選項。
為了與其他客戶端應用程式保持一致,該選項名為 --dbname,但由於 pg_dumpall 需要連線到多個數據庫,因此連線字串中的資料庫名稱將被忽略。使用 -l 選項指定用於初始連線的資料庫的名稱,該連線將轉儲全域性物件並發現應該轉儲的其他資料庫。
-h 主機--host=主機指定資料庫伺服器執行所在計算機的主機名。如果值以斜槓開頭,則用作 Unix 域套接字目錄。預設值取自 PGHOST 環境變數(如果已設定),否則嘗試進行 Unix 域套接字連線。
-l dbname--database=dbname指定用於連線以轉儲全域性物件並發現應轉儲的其他資料庫的資料庫名稱。如果未指定,將使用 postgres 資料庫,如果該資料庫不存在,則使用 template1。
-p 埠--port=埠指定伺服器正在監聽連線的 TCP 埠或本地 Unix 域套接字副檔名。預設值為 PGPORT 環境變數(如果已設定),或者編譯時預設值。
-U 使用者名稱--username=使用者名稱要連線的使用者。:
-w--no-password絕不發出密碼提示。如果伺服器需要密碼身份驗證且密碼不可用(例如透過 .pgpass 檔案),則連線嘗試將失敗。此選項在沒有使用者在場輸入密碼的批處理作業和指令碼中很有用。
-W--password強制 pg_dumpall 在連線到資料庫之前提示輸入密碼。
此選項並非總是必需的,因為如果伺服器要求密碼認證,pg_dumpall 會自動提示輸入密碼。但是,pg_dumpall 會浪費一次連線嘗試來發現伺服器需要密碼。在某些情況下,鍵入 -W 以避免額外的連線嘗試是值得的。
請注意,對於要轉儲的每個資料庫,密碼提示將再次出現。通常,最好設定一個 ~/.pgpass 檔案,而不是依賴手動輸入密碼。
--role=rolename指定一個角色名,用於建立轉儲。此選項會導致 pg_dumpall 在連線到資料庫後發出 SET ROLE rolename 命令。當經過身份驗證的使用者(由 -U 指定)缺乏 pg_dumpall 所需的許可權,但可以切換到具有所需許可權的角色時,此選項很有用。一些安裝有禁止直接以超級使用者身份登入的策略,使用此選項可以在不違反該策略的情況下進行轉儲。
PGHOSTPGOPTIONSPGPORTPGUSER預設連線引數
PG_COLOR指定是否在診斷訊息中使用顏色。可能的值為 always、auto 和 never。
此實用程式以及大多數其他 PostgreSQL 實用程式也使用 libpq 支援的環境變數(請參閱 第 32.15 節)。
由於 pg_dumpall 內部呼叫 pg_dump,因此一些診斷訊息會引用 pg_dump。
即使您的目的是將轉儲指令碼恢復到全新的叢集,--clean 選項也可能很有用。使用 --clean 允許指令碼刪除並重新建立內建的 postgres 和 template1 資料庫,從而確保這些資料庫保留與源叢集相同的屬性(例如,區域設定和編碼)。如果不使用該選項,這些資料庫將保留其現有的資料庫級別屬性以及任何預先存在的物件。
如果指定了 --statistics,pg_dumpall 將在生成的轉儲檔案中包含大多數最佳化器統計資訊。但是,某些統計資訊可能不會包含,例如使用 CREATE STATISTICS 顯式建立的統計資訊或擴充套件新增的自定義統計資訊。因此,在從轉儲檔案恢復後,對每個資料庫執行 ANALYZE 以確保最佳效能可能很有用。您還可以執行 vacuumdb -a -z 來分析所有資料庫。
轉儲指令碼不應期望完全無錯誤地執行。特別是,由於指令碼將為源叢集中存在的每個角色發出 CREATE ROLE,因此除非目標叢集使用不同的引導超級使用者名稱稱進行了初始化,否則它一定會遇到“角色已存在”錯誤。此錯誤無害,應忽略。使用 --clean 選項可能會產生有關不存在物件的其他無害錯誤訊息,儘管您可以透過新增 --if-exists 來儘量減少這些訊息。
pg_dumpall 在恢復之前需要所有必需的表空間目錄都存在;否則,非預設位置的資料庫建立將失敗。
在從 pg_dumpall 指令碼恢復資料庫時,通常建議使用 -X(--no-psqlrc)選項,以確保乾淨的恢復過程並防止與非預設 psql 配置發生潛在衝突。此外,由於 pg_dumpall 指令碼可能包含 psql 元命令,因此它可能與 psql 以外的客戶端不相容。
轉儲所有資料庫
$pg_dumpall > db.out
要從該檔案恢復資料庫,您可以使用
$psql -X -f db.out -d postgres
連線到哪個資料庫在此處並不重要,因為 pg_dumpall 建立的指令碼檔案將包含建立和連線到已儲存資料庫的適當命令。一個例外是,如果您指定了 --clean,您必須最初連線到 postgres 資料庫;指令碼將立即嘗試刪除其他資料庫,而這對於您正在連線的資料庫將失敗。
有關可能的錯誤條件,請參閱 pg_dump。
如果您在文件中看到任何不正確、與您對特定功能的使用經驗不符或需要進一步闡明的內容,請使用 此表單 報告文件問題。