# pg_restore ## Name pg_restore --  从pg_dump创建的备份文件中恢复PostgreSQL数据库 ## Synopsis `pg_restore` [`_connection-option_`...] [`_option_`...] [`_filename_`] ## 描述 pg_restore用于恢复由[pg_dump](#calibre_link-437) 转储的任何非纯文本格式中的PostgreSQL数据库。 它将发出必要的命令重建数据库，并把它恢复成转储时的样子。 归档(备份)文件还允许pg_restore有选择地进行恢复， 甚至在恢复前重新排列条目的顺序。归档的文件设计成可以在不同的硬件体系之间移植。 pg_restore可以按照两种模式操作。如果声明了数据库名字， 那么pg_restore连接到那个数据库并直接恢复归档内容到数据库里。 否则，先创建一个包含重建数据库所必须的 SQL 命令的脚本，并且写入到一个文件或者标准输出。 这个脚本输出等效于pg_dump的纯文本输出格式。因此， 一些控制输出的选项就是模拟pg_dump的选项设置的。 显然，pg_restore无法恢复那些不存在归档文件中的信息；比如， 如果归档是用"把数据转储为`INSERT`命令"选项制作的， 那么pg_restore将不能使用`COPY`语句加载数据。 ## 选项 pg_restore接受下列命令行参数： `_filename_` 要恢复的备份文件（或目录，对于目录格式归档）的位置。如果没有声明，则使用标准输入。 `-a``--data-only` 只恢复数据，而不恢复表模式(数据定义)。恢复表数据、大对象和序列值，如果在档案中存在。 这个选项类似于，但是由于历史原因不等于声明`--section=data`。 `-c` `--clean` 创建数据库对象前先清理(删除)它们。（如果任一对象不在目标数据库中， 这可能会产生一些无害的错误信息。） `-C` `--create` 在恢复数据库之前先创建它。如果也声明了`--clean`， 那么在连接到数据库之前删除并重建目标数据库。 如果出现了这个选项，和`-d`在一起的数据库名只是用于发出最初的 `DROP DATABASE`和`CREATE DATABASE`命令。 所有数据都恢复到名字出现在归档中的数据库中去。 `-d` `_dbname_` `--dbname=``_dbname_` 与数据库`_dbname_`连接并且直接恢复到该数据库中。 `-e` `--exit-on-error` 如果在向数据库发送 SQL 命令的时候碰到错误，则退出。 缺省是继续执行并且在恢复结束时显示一个错误计数。 `-f` `_filename_` `--file=``_filename_` 指定生成的脚本的输出文件，或者出现`-l`选项时用于列表的文件， 缺省是标准输出。 `-F` `_format_` `--format=``_format_` 指定备份文件的格式。因为pg_restore会自动判断格式， 所以如果一定要指定的话，它可以是下面之一： `c` `custom` 备份的格式是来自pg_dump的自定义格式。 `d` `directory` 备份是一个目录归档。 `t` `tar` 备份是一个`tar`归档。 `-i` `--ignore-version` 一个现在已经忽略了的已废弃的选项。 `-I` `_index_` `--index=``_index_` 只恢复命名的索引。 `-j` `_number-of-jobs_` `--jobs=``_number-of-jobs_` 运行pg_restore耗时最多的部分，该部分使用多重并发工作加载数据、 创建索引或创建约束。这个选项可以显著的减少恢复一个大数据库到一个运行多重处理器服务器的时间。 每个工作是一个过程或一个线程，取决于操作系统，并使用一个单独到服务器的连接。 该选项的最佳值依赖于服务器、客户端和网络的硬件设置。因素包含CPU内核的数量和磁盘设置。 良好的开端是服务器上CPU内核的数量，但是较大的值在许多情况下也可以更快的恢复。 当然，太高的值因为超负荷将会导致性能降低。 该选项只支持自定义和目录归档格式。输入必须是有规律的文件或目录（例如不是通道）。 发出一个脚本而不是连接目录到一个数据库服务器时忽略该选项。还有， 多重工作不能与`--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`，那么任何用户都可以用于初始的连接， 并且这个用户将拥有所有创建出来的对象。 `-P` `_function-name(argtype [, ...])_` `--function=``_function-name(argtype [, ...])_` 只恢复指定的命名函数。请注意仔细拼写函数名及其参数，应该和转储的内容列表中的完全一样。 `-R` `--no-reconnect` 这个选项已经废弃了，但是为了保持向下兼容仍然接受。 `-s` `--schema-only` 只恢复表结构(数据定义)，不恢复数据，在这个意义上来说在归档里有模式的记录。 这个选项是`--data-only`的相反。它类似于，但是因为历史原因不等于声明 `--section=pre-data --section=post-data`。 请不要和`--schema`选项混淆，那里使用了"模式"(schema)的其它含义。 `-S` `_username_` `--superuser=``_username_` 设置关闭触发器时使用的超级用户的用户名。只有在设置了`--disable-triggers` 的时候才有用。 `-t` `_table_` `--table=``_table_` 只恢复指定的表的定义和/或数据。可以声明多个`-t`指定多个表。 可以和`-n`选项组合以声明一个模式。 `-T` `_trigger_` `--trigger=``_trigger_` 只恢复指定的触发器。 `-v` `--verbose` 声明冗余模式。 `-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。 `--no-data-for-failed-tables` 缺省时，即使创建表的命令因为该表已经存在而失败了，表中的数据仍将被恢复。 使用这个选项之后，这些表的数据就将跳过恢复操作。 如果目标数据库已经包含所需恢复的某些表的内容时，该选项就很有用处了。 比如，用于PostgreSQL扩展的辅助表(例如PostGIS) 就可能已经在目标数据库中恢复过了， 使用该选项就可以防止多次恢复以致重复或者覆盖了已经恢复的数据。 该选项仅在直接向一个数据库中恢复的时候有效，在生成 SQL 脚本输出时无效。 `--no-security-labels` 不要输出恢复安全标签的命令，即使归档包含它们。 `--no-tablespaces` 不要输出选择表空间的命令。有这个选项，在恢复期间所有的对象都将在缺省表空间中创建。 `--section=``_sectionname_` 值恢复指定的章节。章节名可以是`pre-data`, `data`, 或 `post-data`。可以多次声明这个选项以选择多个章节。缺省是恢复所有章节。 数据章节包含实际的表数据和大对象定义。原始数据项包含索引、触发器、规则和约束 （除了验证检查约束）的定义。先前的数据项包含所有其他数据定义项。 `--use-set-session-authorization` 输出 SQL 标准的`SET SESSION AUTHORIZATION`命令，而不是 `ALTER OWNER`命令来确定对象的所有权。这样令转储与标准兼容的更好， 但是根据转储中对象的历史，这个转储可能不能恰当地恢复。 `-?` `--help` 显示关于pg_restore命令行参数的帮助然后退出。 pg_restore还接受下面的命令行参数做为连接参数： `-h` `_host_` `--host=``_host_` 指定运行服务器的主机名。如果数值以斜杠开头，则被用作到 Unix 域套接字的路径。 缺省从`PGHOST`环境变量中获取(如果设置了的话)，否则， 尝试一个 Unix 域套接字连接。 `-p` `_port_` `--port=``_port_` 指定服务器正在侦听的 TCP 端口或本地 Unix 域套接字文件的扩展(描述符)。 缺省使用`PGPORT`环境变量(如果设置了的话)，否则，编译时的缺省值。 `-U` `_username_` `--username=``_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` 缺省连接参数。 这个功用，类似大多数其他PostgreSQL实用工具， 也使用由libpq支持的环境变量（参阅[Section 31.14](#calibre_link-39)）。 不过，当没有提供数据库名字时，并不读取`PGDATABASE`。 ## 诊断 当使用`-d`选项声明了直接数据库连接时， pg_restore在内部执行SQL语句。 如果你运行pg_restore出了毛病， 请确保你能用类似[psql](#calibre_link-23)这样的东西从数据库中选取信息。 还有，将会应用libpq前端库使用的任何缺省连接设置和环境变量。 ## 注意 如果你的安装给`template1`数据库增加了任何你自己的东西， 那么请注意把pg_restore的输出恢复到一个真正空的数据库中； 否则你可能会收到因为重复定义所追加的对象而造成的错误信息。 要制作一个没有任何本地附属物的数据库，可以从`template0`而不是 `template1`拷贝，比如： ``` CREATE DATABASE foo WITH TEMPLATE template0; ``` pg_restore的局限如下： * 当向一个已经存在的表恢复数据，并且还使用了`--disable-triggers`选项时， pg_restore在插入数据前放出一些查询关闭用户表上的触发器， 在数据插入完成后重新打开它们。如果恢复的中途停止，那么系统表可能处于错误状态。 * pg_restore不能选择性的的恢复大对象。 例如，只恢复指定的表。如果一个归档包含大对象，那么所有大对象都将被恢复， 或如果他们通过`-L`、`-t`或其他选项排除则一个也不恢复。 参阅[pg_dump](#calibre_link-437)的文挡获取有关pg_dump的局限的细节。 一旦完成恢复，最好在每个恢复的对象上运行`ANALYZE`， 以便给优化器有用的统计。参阅[Section 23.1.3](#calibre_link-446) 和[Section 23.1.6](#calibre_link-77)获取更多信息。 ## 例子 假定我们已经转储了`mydb`数据库到一个自定义格式的文件中： ``` <samp class="literal">$</samp> <kbd class="literal">pg_dump -Fc mydb > db.dump</kbd> ``` 删除该数据库并从转储中重建： ``` <samp class="literal">$</samp> <kbd class="literal">dropdb mydb</kbd> <samp class="literal">$</samp> <kbd class="literal">pg_restore -C -d postgres db.dump</kbd> ``` 在`-d`中指定的数据库可以是当前集群中的任意数据库；pg_restore 仅用该名字来为`mydb`发出`CREATE DATABASE`命令。 使用`-C`可以确保数据总是会被恢复到转储文件中指定名字的数据库里面。 将转储出来的数据重新加载到一个新建的数据库`newdb`中： ``` <samp class="literal">$</samp> <kbd class="literal">createdb -T template0 newdb</kbd> <samp class="literal">$</samp> <kbd class="literal">pg_restore -d newdb db.dump</kbd> ``` 注意，这里没有使用`-C`选项，而是直接链接到将要恢复的数据库上。 还要注意的是，我们从`template0`而不是`template1` 创建了新数据库以确保干净。 要对项目重新排序，首先必须转储归档的目录： ``` <samp class="literal">$</samp> <kbd class="literal">pg_restore -l db.dump > db.list</kbd> ``` 这个文件由一行头和每个条目一行组成，比如： ``` ; ; 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 (以这个顺序)： ``` <samp class="literal">$</samp> <kbd class="literal">pg_restore -L db.list db.dump</kbd> ``` ## 又见 [pg_dump](#calibre_link-437), [pg_dumpall](#calibre_link-439), [psql](#calibre_link-23)