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。只有当集簇没有额外表空间时，才允许这样做。
-r rate--max-rate=rate从服务器传输数据的最大速率。单位为每秒千字节。使用后缀M表示每秒兆字节。也接受后缀k，但它没有效果。有效值介于每秒 32 千字节和每秒 1024 兆字节之间。
目的是限制pg_basebackup对运行中的服务器的影响。
此选项始终影响数据目录的传输。只有当收集方法为fetch时，WAL 文件的传输才会受到影响。
-R--write-recovery-conf在输出目录中（使用 tar 格式时则在基础归档文件中）写入一个最小的recovery.conf，以便于设置备库。
-T olddir=newdir--tablespace-mapping=olddir=newdir在备份期间，将目录olddir中的表空间重定位到newdir。要使此选项生效，olddir必须与该表空间当前定义的路径完全一致。（但如果备份中没有位于olddir中的表空间，也不算错误。）olddir和newdir都必须是绝对路径。如果路径中包含=符号，请用反斜线转义。可以多次指定此选项，以处理多个表空间。参见下文示例。
如果以这种方式重定位表空间，主数据目录中的符号链接将被更新为指向新位置。因此，新数据目录已可直接用于启动一个所有表空间都位于更新后位置的新服务器实例。
--xlogdir=xlogdir指定事务日志目录的位置。xlogdir必须是绝对路径。只有在备份采用 普通文件 模式时，才能指定事务日志目录。
-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（默认） （见第 24.3.3 节）。
-l label--label=label设置备份标签。如果未指定，则使用默认值“pg_basebackup base backup”。
-P--progress启用进度报告。打开此选项后，会在备份过程中给出一个近似的进度报告。由于数据库在备份过程中可能发生变化，因此这只是近似值，最终未必恰好结束在100%。特别是当备份中包含 WAL 时，总数据量无法预先估计；在这种情况下，一旦进度超过不含 WAL 时的总估计值，估计目标大小就会继续增加。
启用此选项后，备份会先遍历整个数据库以统计其大小，然后再返回发送实际内容。这可能使备份稍微耗时更长，尤其会使首次发送数据之前的等待时间更长。
-v--verbose启用详细模式。它会在启动和关闭过程中输出一些额外步骤；如果同时启用了进度报告，还会显示当前正在处理的确切文件名。
以下命令行选项控制数据库连接参数。
-d connstr--dbname=connstr以连接字符串的形式指定用于连接服务器的参数。更多信息参见第 31.1.1 节。
出于与其他客户端应用保持一致的考虑，此选项名为--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支持的环境变量（见第 31.14 节）。
在备份开始时，需要在源服务器上执行一次检查点。这可能需要一些时间（尤其是在未使用--checkpoint=fast选项时）；在此期间，pg_basebackup看起来会处于空闲状态。
备份将包括数据目录和表空间中的所有文件，包括配置文件以及第三方放在这些目录中的任何额外文件。不过，只有普通文件和目录会被复制。除用于表空间的符号链接外，其他符号链接和特殊设备文件都会被跳过。（具体细节见第 49.3 节。）
在 普通文件 格式中，除非使用了--tablespace-mapping选项，否则表空间会备份到其在源服务器上的相同路径。如果不使用此选项，那么当表空间正在使用时，就无法在与服务器相同的主机上执行 普通文件 格式的基础备份，因为备份将不得不写入与原始表空间相同的目录位置。
pg_basebackup可以与相同主版本或更低主版本的服务器配合工作，最低支持到 9.1。不过，WAL 流式传输模式（-X stream）仅适用于 9.3 及以上版本的服务器。
要为服务器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
（如果该数据库中有多个表空间，此命令将失败。）
要为本地数据库创建备份，并把位于 /opt/ts 的表空间重定位到 ./backup/ts：
$pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts
译文有误、术语不当或页面显示问题，请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题，请在当前版本的对应页面向上游反馈；上游不再修订已结束维护的版本。