2025年9月25日: PostgreSQL 18 釋出!
支援的版本: 當前 (18) / 17 / 16 / 15 / 14 / 13
開發版本: devel
不支援的版本: 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1

pg_restore

pg_restore — 從 PostgreSQL 資料庫的一個由 pg_dump 建立的歸檔檔案中恢復資料庫

概要

pg_restore [連線選項...] [選項...] [檔名]

描述

pg_restore 是一個實用程式,用於從 pg_dump 以非純文字格式之一建立的歸檔檔案中恢復 PostgreSQL 資料庫。它將發出重建資料庫到儲存時狀態所需的命令。歸檔檔案還允許 pg_restore 選擇要恢復的內容,甚至在恢復之前重新排序專案。歸檔檔案被設計為可在不同架構之間移植。

pg_restore 可以以兩種模式執行。如果指定了資料庫名稱,pg_restore 將連線到該資料庫並將歸檔內容直接恢復到該資料庫中。否則,將建立一個包含重建資料庫所需的 SQL 命令的指令碼,並將其寫入檔案或標準輸出。此指令碼輸出等同於 pg_dump 的純文字輸出格式。因此,一些控制輸出的選項類似於 pg_dump 的選項。

顯然,pg_restore 無法恢復歸檔檔案中不存在的資訊。例如,如果歸檔是使用 將資料轉儲為 INSERT 命令 選項建立的,pg_restore 將無法使用 COPY 語句載入資料。

警告

恢復轉儲會導致目標執行源超級使用者選擇的任意程式碼。部分轉儲和部分恢復不限制這一點。如果源超級使用者不受信任,則必須在恢復之前檢查轉儲的 SQL 語句。可以使用 pg_restore--file 選項檢查非純文字轉儲。請注意,執行轉儲和恢復的客戶端不必信任源或目標超級使用者。

選項

pg_restore 接受以下命令列引數。

filename

指定要恢復的歸檔檔案(或目錄,如果是目錄格式歸檔)的位置。如果未指定,則使用標準輸入。

-a
--data-only

僅恢復資料,不恢復模式(資料定義)或統計資訊。如果歸檔中存在,則恢復表資料、大型物件和序列值。

此選項與指定 --section=data 類似,但由於歷史原因並不完全相同。

-c
--clean

在恢復資料庫物件之前,發出命令以 DROP 所有將被恢復的物件。此選項對於覆蓋現有資料庫非常有用。如果目標資料庫中不存在任何物件,將報告可忽略的錯誤訊息,除非還指定了 --if-exists

-C
--create

在恢復到資料庫之前先建立該資料庫。如果同時指定了 --clean,則在連線到目標資料庫之前先刪除並重新建立該資料庫。

使用 --create 時,pg_restore 還會恢復資料庫的註釋(如果存在),以及特定於該資料庫的任何配置變數設定,即任何提及該資料庫的 ALTER DATABASE ... SET ...ALTER ROLE ... IN DATABASE ... SET ... 命令。資料庫本身的訪問許可權也會被恢復,除非指定了 --no-acl

當使用此選項時,用 -d 指定的資料庫僅用於發出初始的 DROP DATABASECREATE DATABASE 命令。所有資料都恢復到歸檔中出現的資料庫名稱。

-d dbname
--dbname=dbname

連線到資料庫 dbname 並直接恢復到該資料庫。 dbname 可以是一個 連線字串。如果是,連線字串引數將覆蓋任何衝突的命令列選項。

-e
--exit-on-error

在向資料庫傳送 SQL 命令時遇到錯誤時退出。預設情況下,將繼續執行並顯示恢復結束時錯誤的計數。

-f filename
--file=filename

指定生成的指令碼的輸出檔案,或與 -l 一起使用時的列表檔案。使用 - 表示 stdout

-F format
--format=format

指定歸檔的格式。沒有必要指定格式,因為 pg_restore 會自動確定格式。如果指定,它可以是以下之一:

c
custom

pg_dump 的歸檔格式是自定義格式。

d
directory

歸檔是目錄歸檔。

t
tar

歸檔是 tar 歸檔。

-I index
--index=index

僅恢復命名索引的定義。可以使用多個 -I 開關指定多個索引。

-j number-of-jobs
--jobs=number-of-jobs

併發執行 pg_restore 中耗時最多的步驟 — 即載入資料、建立索引或建立約束 — 使用最多 number-of-jobs 個併發會話。此選項可以大大縮短在多處理器計算機上執行的伺服器上恢復大型資料庫的時間。在生成指令碼而不是直接連線到資料庫伺服器時,將忽略此選項。

每個作業都是一個程序或一個執行緒,具體取決於作業系統,並使用單獨的伺服器連線。

此選項的最佳值取決於伺服器、客戶端和網路的硬體配置。因素包括 CPU 核心數和磁碟設定。一個好的起點是伺服器上的 CPU 核心數,但在許多情況下,大於此值的值也能帶來更快的恢復時間。當然,值太高會導致效能下降,因為會發生顛簸。

此選項僅支援自定義和目錄歸檔格式。輸入必須是常規檔案或目錄(例如,不能是管道或標準輸入)。此外,多個作業不能與 --single-transaction 選項一起使用。

-l
--list

列出歸檔的內容表。此操作的輸出可以用作 -L 選項的輸入。請注意,如果與 -l 一起使用諸如 -n-t 之類的過濾開關,它們將限制列出的專案。

-L list-file
--use-list=list-file

僅恢復 list-file 中列出的歸檔元素,並按它們在檔案中出現的順序恢復。請注意,如果與 -L 一起使用諸如 -n-t 之類的過濾開關,它們將進一步限制恢復的專案。

list-file 通常是透過編輯先前 -l 操作的輸出來建立的。行可以被移動或刪除,也可以透過在行開頭放置分號(;)來註釋掉。有關示例,請參見下文。

-n schema
--schema=schema

僅恢復命名模式中的物件。可以使用多個 -n 開關指定多個模式。此選項可以與 -t 選項結合使用,以僅恢復特定表。

-N schema
--exclude-schema=schema

不要恢復命名模式中的物件。可以使用多個 -N 開關指定要排除的多個模式。

當為相同的模式名稱同時給出 -n-N 時,-N 開關優先,該模式將被排除。

-O
--no-owner

不要輸出設定物件所有權的命令以匹配原始資料庫。預設情況下,pg_restore 會發出 ALTER OWNERSET SESSION AUTHORIZATION 語句來設定建立的模式元素的所有權。除非資料庫的初始連線由超級使用者(或指令碼中所有物件的相同使用者)建立,否則這些語句將失敗。使用 -O 時,可以使用任何使用者名稱進行初始連線,該使用者將擁有所有建立的物件。

-P function-name(argtype [, ...])
--function=function-name(argtype [, ...])

僅恢復命名函式。請務必將函式名稱和引數拼寫得與轉儲檔案內容表中的完全一致。可以使用多個 -P 開關指定多個函式。

-R
--no-reconnect

此選項已廢棄,但為了向後相容仍然接受。

-s
--schema-only

僅恢復模式(資料定義),不恢復資料,只要模式條目存在於歸檔中。

此選項不能與 --data-only--statistics-only 一起使用。它與指定 --section=pre-data --section=post-data --no-statistics 類似,但由於歷史原因並不完全相同。

(請不要將其與 --schema 選項混淆,該選項以不同含義使用“schema”一詞。)

-S username
--superuser=username

指定停用觸發器時要使用的超級使用者名稱稱。這僅在使用了 --disable-triggers 時才相關。

-t table
--table=table

僅恢復命名錶的定義和/或資料。為此,“表”包括檢視、物化檢視、序列和外部表。可以透過編寫多個 -t 開關來選擇多個表。此選項可以與 -n 選項結合使用,以指定特定模式中的表。

注意

當指定 -t 時,pg_restore 不會嘗試恢復所選表可能依賴的任何其他資料庫物件。因此,無法保證在乾淨的資料庫中進行特定表恢復能夠成功。

注意

此標誌的行為與 pg_dump-t 標誌不完全相同。目前 pg_restore 中沒有萬用字元匹配的機制,也不能在 -t 中包含模式名稱。而且,雖然 pg_dump-t 標誌還會轉儲所選表的相關物件(如索引),但 pg_restore-t 標誌不包括此類相關物件。

注意

PostgreSQL 9.6 之前的版本中,此標誌僅匹配表,而不匹配任何其他型別的關係。

-T trigger
--trigger=trigger

僅恢復命名觸發器。可以使用多個 -T 開關指定多個觸發器。

-v
--verbose

啟用詳細模式。這將導致 pg_restore 將詳細的物件註釋和開始/停止時間輸出到輸出檔案,並將進度訊息輸出到標準錯誤。重複此選項會在標準錯誤上顯示額外的除錯級別訊息。

-V
--version

列印 pg_restore 版本並退出。

-x
--no-privileges
--no-acl

阻止恢復訪問許可權(GRANT/REVOKE 命令)。

-1
--single-transaction

將恢復作為單個事務執行(即,將發出的命令包裝在 BEGIN/COMMIT 中)。這確保了要麼所有命令都成功完成,要麼不應用任何更改。此選項意味著 --exit-on-error

--disable-triggers

此選項僅在執行不帶模式的恢復時相關。它指示 pg_restore 在恢復資料時執行命令以暫時停用目標表上的觸發器。如果存在引用完整性檢查或其他觸發器,並且您不希望在資料恢復期間觸發它們,請使用此選項。

目前,為 --disable-triggers 發出的命令必須以超級使用者身份執行。因此,您還應該使用 -S 指定超級使用者名稱稱,或者最好將 pg_restore 作為 PostgreSQL 超級使用者執行。

--enable-row-security

此選項僅在恢復具有行安全性的表內容時相關。預設情況下,pg_restore 會將 row_security 設定為 off,以確保所有資料都恢復到表中。如果使用者沒有繞過行安全性的足夠許可權,則會引發錯誤。此引數指示 pg_restorerow_security 設定為 on,允許使用者嘗試在啟用行安全性的情況下恢復表內容。如果使用者沒有將轉儲中的行插入表的許可權,這仍然可能會失敗。

請注意,此選專案前還需要轉儲為 INSERT 格式,因為 COPY FROM 不支援行安全性。

--filter=filename

指定一個檔名,從中讀取要從恢復中排除或包含的物件的模式。模式的解釋遵循與 -n/--schema(用於包含模式中的物件)、-N/--exclude-schema(用於排除模式中的物件)、-P/--function(用於恢復命名函式)、-I/--index(用於恢復命名索引)、-t/--table(用於恢復命名錶)或 -T/--trigger(用於恢復觸發器)相同的規則。要從 STDIN 讀取,請使用 - 作為檔名。--filter 選項可以與上述列出的包含或排除物件的選項結合使用,也可以為多個篩選檔案指定多次。

檔案每行列出一個數據庫模式,格式如下:

{ include | exclude } { function | index | schema | table | trigger } PATTERN

第一個關鍵字指定要過濾的物件是否應被包含或排除。第二個關鍵字指定要使用模式過濾的物件型別:

  • function:函式,功能與 -P/--function 選項相同。此關鍵字只能與 include 關鍵字一起使用。

  • index:索引,功能與 -I/--indexes 選項相同。此關鍵字只能與 include 關鍵字一起使用。

  • schema:模式,功能與 -n/--schema-N/--exclude-schema 選項相同。

  • table:表,功能與 -t/--table 選項相同。此關鍵字只能與 include 關鍵字一起使用。

  • trigger:觸發器,功能與 -T/--trigger 選項相同。此關鍵字只能與 include 關鍵字一起使用。

# 開頭的行被視為註釋並被忽略。註釋也可以放在物件模式行之後。空行也被忽略。有關如何在模式中進行引用的資訊,請參見 模式

--if-exists

使用 DROP ... IF EXISTS 命令來刪除 --clean 模式中的物件。這會抑制可能報告的“不存在”錯誤。此選項僅在也指定了 --clean 時才有效。

--no-comments

即使歸檔包含註釋,也不輸出恢復註釋的命令。

--no-data

即使歸檔包含資料,也不輸出恢復資料的命令。

--no-data-for-failed-tables

預設情況下,即使表的建立命令失敗(例如,因為它已存在),也會恢復表資料。使用此選項,將跳過此類表的某些資料。如果目標資料庫已包含所需的表內容,此行為很有用。例如,PostgreSQL 擴充套件(如 PostGIS)的輔助表可能已載入到目標資料庫中;指定此選項可防止將重複或過時的資料載入到這些表中。

此選項僅在直接恢復到資料庫時有效,在生成 SQL 指令碼輸出時無效。

--no-policies

即使歸檔包含行安全策略,也不輸出恢復它們的命令。

--no-publications

即使歸檔包含釋出,也不輸出恢復它們的命令。

--no-schema

即使歸檔包含模式(資料定義),也不輸出恢復它們的命令。

--no-security-labels

即使歸檔包含安全標籤,也不輸出恢復它們的命令。

--no-statistics

即使歸檔包含統計資訊,也不輸出恢復它們的命令。

--no-subscriptions

即使歸檔包含訂閱,也不輸出恢復它們的命令。

--no-table-access-method

不輸出用於選擇表訪問方法的命令。使用此選項,所有物件都將使用恢復期間的預設表訪問方法建立。

--no-tablespaces

不輸出用於選擇表空間的命令。使用此選項,所有物件都將在恢復期間的預設表空間中建立。

--restrict-key=restrict_key

將提供的字串用作轉儲輸出中的 psql \restrict 鍵。這隻能為 SQL 指令碼輸出指定,即使用 --file 選項時。如果未指定限制鍵,pg_restore 將根據需要生成一個隨機的限制鍵。鍵只能包含字母數字字元。

此選項主要用於測試目的和其他需要可重複輸出(例如,比較轉儲檔案)的場景。不建議常規使用,因為帶有金鑰預知能力的惡意伺服器可能能夠注入任意程式碼,這些程式碼將在執行 psql 並使用轉儲輸出的機器上執行。

--section=sectionname

僅恢復命名部分。部分名稱可以是 pre-datadatapost-data。可以多次指定此選項以選擇多個部分。預設是恢復所有部分。

資料部分包含實際的表資料以及大型物件定義。後資料項由索引、觸發器、規則和其他除已驗證檢查約束之外的約束的定義組成。預資料項由所有其他資料定義項組成。

--statistics

輸出恢復統計資訊的命令,如果歸檔包含它們。這是預設值。

--statistics-only

僅恢復統計資訊,不恢復模式(資料定義)或資料。

--strict-names

要求每個模式(-n/--schema)和表(-t/--table)限定符至少匹配要恢復的檔案中的一個模式/表。

--transaction-size=N

將恢復作為一系列事務執行,每個事務處理最多 N 個數據庫物件。此選項意味著 --exit-on-error

--transaction-size 在預設行為(每個 SQL 命令一個事務)和 -1/--single-transaction(所有恢復物件一個事務)之間提供了一箇中間選擇。雖然 --single-transaction 的開銷最小,但對於大型資料庫來說可能不切實際,因為事務將鎖定每個恢復的物件,可能會耗盡伺服器的鎖定表空間。使用 --transaction-size 並設定數千個物件的範圍,可以獲得幾乎相同的效能優勢,同時限制所需的鎖定表空間。

--use-set-session-authorization

輸出 SQL 標準 SET SESSION AUTHORIZATION 命令,而不是 ALTER OWNER 命令來確定物件所有權。這使得轉儲更符合標準,但根據轉儲中物件的歷史記錄,可能無法正確恢復。

-?
--help

顯示有關 pg_restore 命令列引數的幫助,然後退出。

pg_restore 還接受以下用於連線引數的命令列引數:

-h 主機
--host=主機

指定伺服器執行所在計算機的主機名。如果值以斜槓開頭,則將其用作 Unix 域套接字的目錄。預設值取自 PGHOST 環境變數(如果已設定),否則嘗試 Unix 域套接字連線。

-p
--port=

指定伺服器正在監聽連線的 TCP 埠或本地 Unix 域套接字副檔名。預設值為 PGPORT 環境變數(如果已設定),或者編譯時預設值。

-U 使用者名稱
--username=使用者名稱

要連線的使用者。:

-w
--no-password

絕不發出密碼提示。如果伺服器需要密碼身份驗證且密碼不可用(例如透過 .pgpass 檔案),則連線嘗試將失敗。此選項在沒有使用者在場輸入密碼的批處理作業和指令碼中很有用。

-W
--password

強制 pg_restore 在連線到資料庫之前提示輸入密碼。

此選項絕非必需,因為如果伺服器要求密碼身份驗證,pg_restore 會自動提示輸入密碼。但是,pg_restore 會浪費一次連線嘗試來發現伺服器需要密碼。在某些情況下,鍵入 -W 以避免額外的連線嘗試是值得的。

--role=rolename

指定一個角色名,用於執行恢復。此選項會導致 pg_restore 在連線到資料庫後發出 SET ROLE rolename 命令。當經過身份驗證的使用者(由 -U 指定)缺乏 pg_restore 所需的許可權,但可以切換到具有所需許可權的角色時,此選項非常有用。一些安裝策略禁止直接以超級使用者身份登入,使用此選項可以執行恢復而不違反策略。

環境變數

PGHOST
PGOPTIONS
PGPORT
PGUSER

預設連線引數

PG_COLOR

指定是否在診斷訊息中使用顏色。可能的值為 alwaysautonever

與大多數其他 PostgreSQL 實用程式一樣,此實用程式還使用 libpq 支援的環境變數(參見 第 32.15 節)。但是,當未提供資料庫名稱時,它不讀取 PGDATABASE

診斷

當使用 -d 選項指定直接資料庫連線時,pg_restore 內部執行SQL語句。如果您在執行 pg_restore 時遇到問題,請確保您能夠使用例如 psql 從資料庫中選擇資訊。此外,libpq 前端庫使用的任何預設連線設定和環境變數都將適用。

註釋

如果您的安裝在 template1 資料庫中存在任何本地新增項,請小心將 pg_restore 的輸出載入到一個真正空的資料庫中;否則,由於新增物件的定義重複,您很可能會收到錯誤。要建立一個沒有本地新增項的空資料庫,請從 template0 而不是 template1 複製,例如:

CREATE DATABASE foo WITH TEMPLATE template0;

pg_restore 的限制將在下面詳細說明。

  • 當將資料恢復到預先存在的表並且使用了 --disable-triggers 選項時,pg_restore 會發出命令以在插入資料之前停用使用者表上的觸發器,然後在插入資料後發出命令以重新啟用它們。如果恢復在中間停止,系統目錄可能會處於錯誤狀態。

  • pg_restore 無法選擇性地恢復大型物件;例如,僅恢復特定表的。如果歸檔包含大型物件,則將恢復所有大型物件,或者如果透過 -L-t 或其他選項將其排除,則不恢復任何大型物件。

有關 pg_dump 的限制的詳細資訊,請參閱 pg_dump 文件。

預設情況下,pg_restore 將恢復最佳化器統計資訊(如果包含在轉儲檔案中)。如果並非所有統計資訊都已恢復,則最好在每個恢復的表上執行 ANALYZE,以便最佳化器擁有有用的統計資訊;有關更多資訊,請參見 第 24.1.3 節第 24.1.6 節

示例

假設我們已將名為 mydb 的資料庫轉儲到一個自定義格式的轉儲檔案中

$ pg_dump -Fc mydb > db.dump

要刪除資料庫並從轉儲中重新建立它

$ dropdb mydb
$ pg_restore -C -d postgres db.dump

-d 開關中命名的資料庫可以是叢集中存在的任何資料庫;pg_restore 僅使用它來發出 CREATE DATABASE 命令以建立 mydb。使用 -C 時,資料始終恢復到轉儲檔案中出現的資料庫名稱。

要將轉儲恢復到名為 newdb 的新資料庫中

$ createdb -T template0 newdb
$ pg_restore -d newdb db.dump

請注意,我們不使用 -C,而是直接連線到要恢復的資料庫。還要注意,我們是從 template0 而不是 template1 克隆新資料庫,以確保它最初是空的。

要重新排序資料庫項,首先需要轉儲歸檔的內容表

$ pg_restore -l db.dump > db.list

列表檔案包含一個標題和每行的內容,例如:

;
; Archive created at Mon Sep 14 13:55:39 2009
;     dbname: DBDEMOS
;     TOC Entries: 81
;     Compression: 9
;     Dump Version: 1.10-0
;     Format: CUSTOM
;     Integer: 4 bytes
;     Offset: 8 bytes
;     Dumped from database version: 8.3.5
;     Dumped by pg_dump version: 8.3.8
;
;
; Selected TOC Entries:
;
3; 2615 2200 SCHEMA - public pasha
1861; 0 0 COMMENT - SCHEMA public pasha
1862; 0 0 ACL - public pasha
317; 1247 17715 TYPE public composite pasha
319; 1247 25899 DOMAIN public domain0 pasha

分號開始一個註釋,行開頭的數字指的是分配給每個專案的內部歸檔 ID。

檔案中的行可以被註釋掉、刪除和重新排序。例如:

10; 145433 TABLE map_resolutions postgres
;2; 145344 TABLE species postgres
;4; 145359 TABLE nt_header postgres
6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres

可以用作 pg_restore 的輸入,並且只按指定的順序恢復專案 10 和 6

$ pg_restore -L db.list db.dump

另請參閱

pg_dump, pg_dumpall, psql

提交更正

如果您在文件中發現任何不正確、與您對特定功能的經驗不符或需要進一步澄清的內容,請使用 此表單 報告文件問題。