# 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)