©
This document uses PHP Chinese website manual Release
pg_restore
Name
pg_restore -- 从pg_dump创建的备份文件中恢复数据库。Synopsis
pg_restore [connection-option...] [option...] [filename]
描述
pg_restore用于恢复由pg_dump转储的任何非纯文本格式中的PostgreSQL数据库。 它将发出必要的命令重建数据库，并把它恢复成转储时的样子。 归档(备份)文件还允许pg_restore有选择地进行恢复，甚至在恢复前重新排列条目的顺序。 归档的文件设计成可以在不同的硬件体系之间移植。
pg_restore可以按照两种模式操作。如果声明了数据库名字， pg_restore直接连在数据库里以及归档是直接恢复到数据库里。 否则，先创建一个包含重建数据库所必须的SQL命令的脚本，并且写入到一个文件或者标准输出。 等效于pg_dump输出纯文本格式的时候创建的那种脚本。 因此，一些控制输出的选项就是模拟pg_dump的选项设置的。
显然，pg_restore无法恢复那些不存在归档文件中的信息； 比如，如果归档是用"把数据转储为INSERT命令"选项制作的， 那么pg_restore将不能使用COPY语句加载数据。
选项
pg_restore接受下列命令行参数：
- filename
要恢复的备份文件的位置。如果没有声明，则使用标准输入。
-
-a
--data-only 只恢复数据，而不恢复表模式(数据定义)。
-
-c
--clean 创建数据库对象前先清理(删除)它们。
-
-C
--create 在恢复数据库之前先创建它。如果出现了这个选项， 和-d在一起的数据库名只是用于发出最初的CREATE DATABASE命令。所有数据都恢复到名字出现在归档中的数据库中去。
-
-d dbname
--dbname=dbname 与数据库dbname连接并且直接恢复到该数据库中。
-
-e
--exit-on-error 如果在向数据库发送SQL命令的时候碰到错误，则退出。缺省是继续执行并且在恢复结束时显示一个错误计数。
-
-f filename
--file=filename 指定生成的脚本的输出文件，或者出现-l选项时用于列表的文件，缺省是标准输出。
-
-F format
--format=format -
指定备份文件的格式。因为pg_restore会自动判断格式，所以如果一定要指定的话，它可以是下面之一：
-
t
tar 备份是一个 tar 归档。
-
c
custom 备份的格式是来自pg_dump的自定义格式。这是最灵活的格式，因为它允许重新对数据排序，也允许重载表模式元素。缺省时这个格式是压缩的。
-
t
-
-i
--ignore-version 一个现在被忽略的弃用选项。
-
-I index
--index=index 只恢复命名的索引。
-
-j number-of-jobs
--jobs=number-of-jobs -
运行pg_restore —的最耗时部分；这些加载护具、创建索引或者创建 约束 —使用多个并发作业。该选项可以显著减少将大型数据库存储到一个运行在一个多 处理器机上的服务器所用的时间。
每个工作是一个进程或一个线程，根据操作系统，并使用一个岛服务器的单独连接。
该选项的最优值取决于服务器、客户和网络的硬件设置。因素包括CPU内核的数量和磁盘设置。 良好的开端是在服务器上的CPU内核的数量，但在许多情况下更大的数值也能导致更快的恢复时间。 当然，值过高会因为抖动降低性能。
仅支持有用户定义的格式支持该选项。输入文件必须是一个常规文件（像一个pipe就不是）。 在发射一个脚本而不是直接连接到一个数据库服务器时，该选项会被忽略。同时， 并发作业不能与--single-transaction选项一起使用。
-
-l
--list 列出归档文件的内容。该操作的输出可以用作输入-L选项。 请注意如果过滤选项（如-n或-t）与-l一同使用， 他们将会限制列出的项。
-
-L list-file
--use-list=list-file -
仅恢复那些在list-file中列出的归档元素， 并按他们在文件中出现的顺序恢复他们。请注意，如果像-n或者-t这样的 过滤开关与-L一起使用，他们将进一步限制物品恢复。
list-file通常通过编辑一个先前的-l 操作来创建。可以移动或删除行，并且也可以通过在行前放置一个分号(;) 注释掉该行。请看下面的例子。
-
-n namespace
--schema=schema 只恢复指定名字的模式里面的定义和/或数据。 这个选项可以和-t选项一起使用，实现只转储一个表的数据。
-
-O
--no-owner 不要输出设置与最初数据库对象权限匹配的命令。缺省时，pg_restore发出ALTER OWNER 或SET SESSION AUTHORIZATION语句设置创建出来的模式元素的所有者权限。 如果最初的数据库连接不是由超级用户(或者是拥有所有创建出来的对象的同一个用户)发起的， 那么这些语句将失败。如果使用-O，那么任何用户都可以用于初始的连接， 并且这个用户将拥有所有创建出来的对象。
- --no-tablespaces
不要输出命令来选择表空间。使用该选项，在恢复数据时的默认表空间中所有的对象将会被创建。
-
-P function-name(argtype [, ...])
--function=function-name(argtype [, ...]) 只恢复指定的命名函数。请注意仔细拼写函数名及其参数，应该和转储的内容列表中的完全一样。
-
-R
--no-reconnect 这个选项已经废弃了，但是为了保持向下兼容仍然接受。
-
-s
--schema-only 只恢复表结构(数据定义)。不恢复数据(数据表内容)。序列的当前值也不会得到恢复。 请不要和--schema选项混淆，那里使用了"模式"(schema)的其它含义。
-
-S username
--superuser=username 设置关闭触发器时声明超级用户的用户名。只有在设置了--disable-triggers的时候才有用。
-
-t table
--table=table 只恢复指定的表的定义和/或数据。 This can be combined with the -n option to specify a schema.
-
-T trigger
--trigger=trigger 只恢复指定的触发器。
-
-v
--verbose 声明冗余模式。
-
-V
--version 输出pg_restore 版本并退出。
-
-x
--no-privileges
--no-acl 禁止恢复访问权限(grant/revoke命令)。
- --disable-triggers
-
这个选项只有在执行仅恢复数据的时候才相关。 它告诉pg_restore在加载数据的时候执行一些命令临时关闭在目标表上的触发器。 如果你在表上有完整性检查或者其它触发器，而你又不希望在加载数据的时候激活它们，那么可以使用这个选项。
目前，为--disable-triggers发出的命令必须以超级用户发出。 因此，你应该也要用-S声明一个超级用户名，或者更好是以超级用户身份运行PostgreSQL。
- --use-set-session-authorization
输出SQL标准的SET SESSION AUTHORIZATION命令，而不是ALTER OWNER命令。 这样令转储与标准兼容的更好，但是根据转储中对象的历史，这个转储可能不能恰当地恢复。
- --no-data-for-failed-tables
-
缺省时，即使创建表的命令因为该表已经存在而失败了，表中的数据仍将被恢复。 使用这个选项之后，这些表的数据就将跳过恢复操作。当目标数据库可能已经包含所需恢复的某些表的内容时， 该选项就很有用处了。比如，用于PostgreSQL扩展的辅助表(例如PostGIS)就可能已经在目标数据库中恢复过了，使用该选项就可以防止多次恢复以致重复或者覆盖了已经恢复的数据。
该选项仅在直接向一个数据库中恢复的时候有效，在生成SQL脚本输出时无效。
-
-1
--single-transaction 作为一个单独事务来存储（也就是在BEGIN/COMMIT)中封装发射命令。） 这确保了：要么所有的命令成功完成，要么没有申请修改。该选项蕴含--exit-on-error。
-
-?
--help 显示关于pg_restore命令行参数的帮助并退出。
pg_restore还接受下面的命令行参数做为连接参数：
-
-h host
--host=host 指定运行服务器的主机名。如果数值以斜杠开头，则被用作到Unix域套接字的路径。缺省从PGHOST环境变量中获取(如果设置了的话)，否则，尝试一个Unix域套接字连接。
-
-p port
--port=port 指定服务器正在侦听的TCP端口或本地Unix域套接字文件的扩展(描述符)。 缺省使用PGPORT环境变量(如果设置了的话)，否则，编译时的缺省值。
-
-U username
--username=username User name to connect as.
-
-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 缺省连接参数。
该使用程序，跟大部分其他PostgreSQL实用程序一样，也使用libpq 支持的环境变量。（请参阅Section 31.13）。
诊断
当使用-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的局限的细节。
一旦完成恢复，最好在每个恢复的对象上运行ANALYZE， 以便给优化器有用的统计；更多信息请参考Section 23.1.3， Section 23.1.5。
例子
假定我们已经转储了mydb数据库到一个自定义格式的文件中：
$ pg_dump -Fc mydb > db.dump
删除该数据库并从转储中重建：
$ dropdb mydb $ pg_restore -C -d postgres db.dump
在-d中指定的数据库可以是当前集群中的任意数据库；pg_restore 仅用该名字来为mydb发出CREATE DATABASE命令。 使用-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