pg_basebackup — 获取PostgreSQL集簇的基础备份
pg_basebackup [option...]
pg_basebackup用于获取正在运行的PostgreSQL数据库集簇的基础备份。备份过程不会影响数据库的其他客户端，并且该备份既可用于时间点恢复（见Section 25.3），也可用作日志传送或流复制备库的起点（见Section 26.2）。
pg_basebackup创建数据库集簇文件的二进制副本，同时确保系统自动进入和退出备份模式。备份始终针对整个数据库集簇；无法只备份单个数据库或数据库对象。要备份单个数据库，必须使用pg_dump之类的工具。
备份通过使用复制协议的普通PostgreSQL连接进行。建立连接时必须使用超级用户或具有REPLICATION权限（参见Section 21.2）的用户，并且pg_hba.conf必须明确允许复制连接。服务器还必须将max_wal_senders设置得足够高，以便至少为备份保留一个可用会话，并在使用 WAL 流式传输时再为其保留一个会话。
可以同时运行多个pg_basebackup，但从性能角度来看，通常最好只执行一次备份，然后复制其结果。
pg_basebackup不仅可以从主库获取基础备份，也可以从备库获取。要从备库获取备份，需要将备库配置为能够接受复制连接（即设置max_wal_senders和hot_standby，并配置基于主机的认证）。还需要在主库上启用full_page_writes。
注意，从备库获取在线备份时有一些限制：
备份历史文件不会在被备份的数据库集簇中创建。
pg_basebackup无法强制备库在备份结束时切换到新的 WAL 文件。 当使用-X none时，如果主库上的写入活动较少， pg_basebackup可能需要长时间等待， 直到备份所需的最后一个 WAL 文件被切换并归档。在这种情况下， 可以在主库上运行pg_switch_wal，以立即触发 WAL 文件切换。
如果备库在在线备份过程中被提升为主库，则备份会失败。
备份所需的所有 WAL 记录都必须包含足够的整页写入，因此必须在主库上启用full_page_writes，并且不能把pg_compresslog之类的工具用作archive_command，从 WAL 文件中移除整页写入。
以下命令行选项控制输出的位置和格式。
-D directory--pgdata=directory设置写入输出的目标目录。如果该目录不存在， pg_basebackup会创建它（以及所有缺失的父目录）。 如果该目录已经存在，则必须为空。
当备份采用 tar 格式时，目标目录可以指定为-（短横线），从而将 tar 文件写到stdout。
此选项是必需的。
-F format--format=format选择输出格式。format可以是以下值之一：
pplain将输出写为普通文件，其布局与源服务器的数据目录和表空间相同。当集簇没有额外表空间时，整个数据库都会放在目标目录中。如果集簇包含额外表空间，则主数据目录会放在目标目录中，而其他所有表空间都会放在与源服务器上相同的绝对路径中。（如需改变这一点，见--tablespace-mapping。）
这是默认格式。
ttar将输出写为目标目录中的 tar 文件。主数据目录的内容会写入名为base.tar的文件中，而每个其他表空间都会写入一个以该表空间 OID 命名的独立 tar 文件中。
如果目标目录指定为-（短横线），tar 内容将写入标准输出，适合通过管道传给例如gzip。只有当集簇没有额外表空间且未使用 WAL 流式传输时，才允许这样做。
-r rate--max-rate=rate从服务器传输数据的最大速率。单位为每秒千字节。使用后缀M表示每秒兆字节。也接受后缀k，但它没有效果。有效值介于每秒 32 千字节和每秒 1024 兆字节之间。
目的是限制pg_basebackup对运行中的服务器的影响。
此选项始终影响数据目录的传输。只有当收集方法为fetch时，WAL 文件的传输才会受到影响。
-R--write-recovery-conf在输出目录中（使用 tar 格式时则在基础归档文件中）写入一个最小的recovery.conf，以便设置备库。recovery.conf文件会记录pg_basebackup所用的连接设置，以及复制槽（如果指定了），以便流复制以后使用相同的设置。
-S slotname--slot=slotname此选项只能与-X stream一起使用。它会使 WAL 流式传输使用指定的复制槽。如果此基础备份打算用作使用复制槽的流复制备库，那么该备库应在recovery.conf中使用同一个复制槽名称。这样可以确保服务器在基础备份结束与开始流复制之间的这段时间内，不会移除任何必需的 WAL 数据。
如果未指定此选项，并且服务器支持临时复制槽（10 及以上版本），则会自动使用临时复制槽进行 WAL 流式传输。
--no-slot即使服务器支持，此选项也会阻止在备份期间创建临时复制槽。
默认情况下，如果选择了 WAL 流式传输，但没有使用-S选项给出槽名，那么会创建一个临时复制槽。
此选项的主要目的是在服务器没有空闲复制槽时，仍然允许执行基础备份。几乎总是首选使用复制槽，因为它能防止服务器在备份期间移除所需的 WAL。
-T olddir=newdir--tablespace-mapping=olddir=newdir在备份期间，将目录olddir中的表空间重定位到newdir。要使此选项生效，olddir必须与该表空间当前定义的路径完全一致。（但如果备份中没有位于olddir中的表空间，也不算错误。）olddir和newdir都必须是绝对路径。如果路径中包含=符号，请用反斜线转义。可以多次指定此选项，以处理多个表空间。参见下文示例。
如果以这种方式重定位表空间，主数据目录中的符号链接将被更新为指向新位置。因此，新数据目录已可直接用于启动一个所有表空间都位于更新后位置的新服务器实例。
目前，此选项仅适用于 plain 输出格式；如果选择了 tar 格式，则会被忽略。
--waldir=waldir指定预写式日志目录的位置。waldir必须是绝对路径。只有在备份采用 plain 模式时，才能指定预写式日志目录。
-X method--wal-method=method在备份中包含所需的 WAL（预写式日志）文件。这将包括备份期间生成的所有预写式日志。除非指定方法none，否则就可以在解包后的目录中启动 postmaster，而无需查阅 WAL 归档，从而使输出成为一个完全独立的备份。
支持以下收集预写式日志的方法：
nnone不在备份中包含预写式日志。
ffetch在备份结束时收集预写式日志文件。因此，wal_keep_segments参数必须设置得足够高，以确保在备份结束前不会移除所需的日志数据。如果在传输这些数据之前它们已经被回收，则备份会失败并且无法使用。
当使用 tar 格式时，预写式日志文件会包含在base.tar文件中。
sstream在创建备份的同时流式传输预写式日志。这会打开与服务器的第二个连接，并在执行备份时并行开始流式传输预写式日志。因此，它会占用由max_wal_senders参数配置的两个连接。只要客户端能够跟上接收到的预写式日志，使用此模式就不需要在主库上额外保留预写式日志。
当使用 tar 格式时，预写式日志文件会写入一个名为pg_wal.tar的独立文件中（如果服务器版本早于 10，则文件名为pg_xlog.tar）。
这是默认值。
-z--gzip启用 tar 文件输出的 gzip 压缩，使用默认压缩级别。压缩仅在使用 tar 格式时可用，并且所有 tar 文件名都会自动添加.gz后缀。
-Z level--compress=level启用 tar 文件输出的 gzip 压缩，使用默认压缩级别。压缩仅在使用 tar 格式时可用，并且所有 tar 文件名都会自动添加.gz后缀。
以下命令行选项控制备份的生成和程序的运行。
-c fast|spread--checkpoint=fast|spread将检查点模式设置为 fast（立即）或 spread（默认） （见Section 25.3.3）。
-l label--label=label设置备份标签。如果未指定，则使用默认值“pg_basebackup base backup”。
-n--no-clean默认情况下，当pg_basebackup因错误中止时，它会删除在发现自己无法完成任务之前可能已创建的所有目录（例如数据目录和预写式日志目录）。此选项会禁止这种清理，因此对调试很有帮助。
请注意，无论如何表空间目录都不会被清理。
-P--progress启用进度报告。打开此选项后，会在备份过程中给出一个近似的进度报告。由于数据库在备份过程中可能发生变化，因此这只是近似值，最终未必恰好结束在100%。特别是当备份中包含 WAL 时，总数据量无法预先估计；在这种情况下，一旦进度超过不含 WAL 时的总估计值，估计目标大小就会继续增加。
启用此选项后，备份会先遍历整个数据库以统计其大小，然后再返回发送实际内容。这可能使备份稍微耗时更长，尤其会使首次发送数据之前的等待时间更长。
-N--no-sync默认情况下，pg_basebackup会等待所有文件都被安全写入磁盘。此选项会使pg_basebackup不经等待就直接返回，因此速度更快，但这意味着如果随后操作系统崩溃，基础备份可能会损坏。通常，此选项适合测试，但不应用于创建生产环境安装。
-v--verbose启用详细模式。它会在启动和关闭过程中输出一些额外步骤；如果同时启用了进度报告，还会显示当前正在处理的确切文件名。
以下命令行选项控制数据库连接参数。
-d connstr--dbname=connstr以连接字符串的形式指定用于连接服务器的参数；这些参数会覆盖任何相互冲突的命令行选项。
出于与其他客户端应用保持一致的考虑，此选项名为--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 33.14）。
在备份开始时，需要在源服务器上执行一次检查点。这可能需要一些时间（尤其是在未使用--checkpoint=fast选项时）；在此期间，pg_basebackup看起来会处于空闲状态。
备份将包括数据目录和表空间中的所有文件，包括配置文件以及第三方放在这些目录中的任何额外文件，但由 PostgreSQL 管理的某些临时文件和操作系统文件除外。不过，只有普通文件和目录会被复制，但用于表空间的符号链接会被保留。指向 PostgreSQL 已知某些目录的符号链接会被复制为空目录。其他符号链接和特殊设备文件则会被跳过。具体细节见Section 52.4。
在 plain 格式中，除非使用了--tablespace-mapping选项，否则表空间会备份到其在源服务器上的相同路径。如果不使用此选项，那么当表空间正在使用时，就无法在与服务器相同的主机上执行 plain 格式的基础备份，因为备份将不得不写入与原始表空间相同的目录位置。
使用 tar 格式时，用户有责任在启动 PostgreSQL 服务器之前解包每个 tar 文件。如果存在额外表空间，则其 tar 文件必须解包到正确的位置。在这种情况下，服务器会根据tablespace_map文件的内容，为这些表空间创建符号链接，该文件包含在base.tar文件中。
pg_basebackup可以与相同主版本或更低主版本的服务器配合工作，最低支持到 9.1。不过，WAL 流式传输模式（-X stream）仅适用于 9.3 及以上版本服务器，当前版本的 tar 格式（--format=tar）仅适用于 9.5 及以上版本服务器。
要为服务器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 -X fetch | bzip2 > backup.tar.bz2
（如果该数据库中有多个表空间，此命令将失败。）
要为本地数据库创建备份，并把位于 /opt/ts 的表空间重定位到 ./backup/ts：
$pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts