pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。
pg_basebackup — 获取PostgreSQL集簇的基础备份
pg_basebackup [option...]
pg_basebackup用于获取正在运行的PostgreSQL数据库集簇的基础备份。备份过程不会影响数据库的其他客户端，并且该备份既可用于时间点恢复（见第 24.3 节），也可用作日志传送或流复制备库的起点（见第 25.2 节）。
pg_basebackup创建数据库集簇文件的二进制副本，同时确保系统自动进入和退出备份模式。备份始终针对整个数据库集簇；无法只备份单个数据库或数据库对象。要备份单个数据库，必须使用pg_dump之类的工具。
备份通过使用复制协议的普通PostgreSQL连接进行。建立连接时必须使用超级用户或具有REPLICATION权限（参见第 20.2 节）的用户，并且pg_hba.conf必须明确允许复制连接。服务器还必须将max_wal_senders设置得足够高，以便至少为备份保留一个可用会话。
可以同时运行多个pg_basebackup，但从性能角度来看，最好只执行一次备份，然后复制其结果。
pg_basebackup不仅可以从主库获取基础备份，也可以从备库获取。要从备库获取备份，需要将备库配置为能够接受复制连接（即设置max_wal_senders和hot_standby，并配置基于主机的认证）。还需要在主库上启用full_page_writes。
注意，从备库获取在线备份时有一些限制：
备份历史文件不会在被备份的数据库集簇中创建。
无法保证备份所需的所有 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可以是以下值之一：
pplain将输出写为普通文件，其布局与源服务器的数据目录和表空间相同。当集簇没有额外表空间时，整个数据库都会放在目标目录中。如果集簇包含额外表空间，则主数据目录会放在目标目录中，而其他所有表空间都会放在与服务器上相同的绝对路径中。
这是默认格式。
ttar将输出写为目标目录中的 tar 文件。主数据目录的内容会写入名为base.tar的文件中，而每个其他表空间都会写入一个以该表空间 OID 命名的独立 tar 文件中。
如果目标目录指定为-（短横线），tar 内容将写入标准输出，适合通过管道传给例如gzip。只有当集簇没有额外表空间时，才允许这样做。
-x--xlog使用此选项等价于使用方法为fetch的-X。
-X method--xlog-method=method在备份中包含所需的事务日志（WAL）文件。这将包括备份期间生成的所有事务日志。如果指定了此选项，就可以在解包后的目录中直接启动 postmaster，而无需查阅日志归档，从而使输出成为一个完全独立的备份。
支持以下收集事务日志的方法：
ffetch在备份结束时收集事务日志文件。因此，wal_keep_segments参数必须设置得足够高，以确保在备份结束前不会移除所需的日志数据。如果在传输这些数据之前它们已经被回收，则备份会失败并且无法使用。
sstream在创建备份的同时流式传输事务日志。这会打开与服务器的第二个连接，并在执行备份时并行开始流式传输事务日志。因此，它会占用由max_wal_senders参数配置的两个槽。只要客户端能够跟上接收到的事务日志，使用此模式就不需要在主库上额外保留事务日志。
-z--gzip启用 tar 文件输出的 gzip 压缩，使用默认压缩级别。压缩仅在使用 tar 格式时可用。
-Z level--compress=level启用 tar 文件输出的 gzip 压缩，并指定压缩级别（0 到 9，其中 0 表示不压缩，9 表示最佳压缩）。压缩仅在使用 tar 格式时可用。
以下命令行选项控制备份的生成和程序的运行。
-c fast|spread--checkpoint=fast|spread将检查点模式设置为 fast 或 spread（默认）。
-l label--label=label设置备份标签。如果未指定，则使用默认值“pg_basebackup base backup”。
-P--progress启用进度报告。打开此选项后，会在备份过程中给出一个近似的进度报告。由于数据库在备份过程中可能发生变化，因此这只是近似值，最终未必恰好结束在100%。特别是当备份中包含 WAL 时，总数据量无法预先估计；在这种情况下，一旦进度超过不含 WAL 时的总估计值，估计目标大小就会继续增加。
启用此选项后，备份会先遍历整个数据库以统计其大小，然后再返回发送实际内容。这可能使备份稍微耗时更长，尤其会使首次发送数据之前的等待时间更长。
-v--verbose启用详细模式。它会在启动和关闭过程中输出一些额外步骤；如果同时启用了进度报告，还会显示当前正在处理的确切文件名。
以下命令行选项控制数据库连接参数。
-h host--host=host指定服务器运行所在机器的主机名。如果该值以斜线开头，则它会被用作 Unix 域套接字的目录。默认值取自PGHOST环境变量（如果已设置）；否则会尝试使用 Unix 域套接字连接。
-p port--port=port指定服务器监听连接所使用的 TCP 端口，或本地 Unix 域套接字文件扩展名。默认使用PGPORT环境变量中的值（如果已设置），否则使用编译时确定的默认值。
-s interval--status-interval=interval指定向服务器回送状态包的时间间隔（秒）。如果在服务器上配置了复制超时，并且以流式传输事务日志（使用--xlog=stream），这就是必需的；同时它也更便于监视进度。值为零将完全禁用状态更新。默认值是 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支持的环境变量（见第 31.14 节）。
备份将包括数据目录和表空间中的所有文件，包括配置文件以及第三方放在这些目录中的任何额外文件。数据目录中只允许普通文件和目录，不允许符号链接和特殊设备文件。
由于 PostgreSQL 管理表空间的方式，无论何时恢复备份，所有附加表空间的路径都必须一致。不过，主数据目录可以重定位到任何位置。
要为服务器mydbserver创建一个基础备份，并将其存储到本地目录/usr/local/pgsql/data中：
$pg_basebackup -h mydbserver -D /usr/local/pgsql/data
要为本地服务器创建一个备份，为每个表空间各生成一个压缩的 tar 文件，并将其存储在目录backup中，同时在运行期间显示进度报告：
$pg_basebackup -D backup -Ft -z -P
要为一个仅包含单个表空间的本地数据库创建备份，并使用bzip2进行压缩：
$pg_basebackup -D - -Ft | bzip2 > backup.tar.bz2
（如果该数据库中有多个表空间，此命令将失败。）
译文有误、术语不当或页面显示问题，请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题，请在当前版本的对应页面向上游反馈；上游不再修订已结束维护的版本。