pg_basebackup

设置写入输出的目标目录。如果该目录不存在，pg_basebackup会创建它（以及所有缺失的父目录）。如果该目录已经存在，则必须为空。

当备份采用 tar 格式时，目标目录可以指定为-（短横线），从而将 tar 文件写到stdout。

此选项是必需的。

选择输出格式。format可以是以下值之一：

执行增量备份。必须提供参考备份的备份清单；该文件将被上传到服务器，随后服务器会返回所请求的增量备份。

创建standby.signal 文件，并将连接设置追加到目标目录中的postgresql.auto.conf文件中（如果使用 tar 格式，则追加到基础归档文件内）。这样可以更方便地利用备份结果搭建备库。

postgresql.auto.conf文件将记录连接设置，以及（如果指定）pg_basebackup正在使用的复制槽，以便后续的流复制和逻辑复制槽同步使用相同的设置。只有当 dbname 在连接字符串或环境变量中被显式指定时，才会记录 dbname。

指示服务器将基础备份放到哪里。默认目标是client，表示备份应发送到运行pg_basebackup的那台机器。如果目标改为server:/some/path，则备份会存储在服务器运行所在机器的/some/path目录中。将备份存储在服务器上需要超级用户权限，或拥有pg_write_server_files角色的权限。如果目标设置为blackhole，则内容会被丢弃，不会存储到任何地方。这只应用于测试目的，因为最终不会得到实际备份。

由于 WAL 流式传输是由pg_basebackup而不是服务器实现的，因此此选项不能与-Xstream一起使用。由于后者是默认值，所以指定此选项时，还必须同时指定-Xfetch或-Xnone之一。

在备份期间，将目录olddir中的表空间重定位到newdir。要使此选项生效，olddir必须与源服务器上定义的该表空间路径完全一致。（但如果源服务器上在olddir中没有表空间，也不算错误。）与此同时，newdir是接收主机文件系统中的一个目录。与主目标目录一样，newdir不必事先存在，但如果存在则必须为空。olddir和newdir都必须是绝对路径。如果任一路径中需要包含等号（=），请在其前面加上反斜杠。可以多次指定此选项，以处理多个表空间。

如果以这种方式重定位表空间，主数据目录中的符号链接将被更新为指向新位置。因此，新数据目录已可直接用于启动一个所有表空间都位于更新后位置的新服务器实例。

目前，此选项仅适用于普通文件输出格式；如果选择了 tar 格式，则会被忽略。

设置写入 WAL（预写式日志）文件的目录。默认情况下，WAL 文件会放在目标目录的pg_wal子目录中，但此选项可用于将其放在其他位置。waldir必须是绝对路径。与主目标目录一样，waldir不必事先存在，但如果存在则必须为空。只有当备份采用普通文件格式时，才能指定此选项。

在备份中包含所需的 WAL（预写式日志）文件。这将包括备份期间生成的所有预写式日志。除非指定方法none，否则就可以在目标目录中启动 postmaster，而无需查阅 WAL 归档，从而使输出成为一个完全独立的备份。

支持以下用于收集预写式日志的method值：

启用 tar 文件输出的 gzip 压缩，使用默认压缩级别。压缩仅在使用 tar 格式时可用，并且所有 tar 文件名都会自动添加.gz后缀。

请求对备份进行压缩。如果包含client或server，则指定压缩执行的位置。在服务器端压缩会减少传输带宽占用，但会增加服务器 CPU 消耗。默认值是client，但使用--target时除外；此时备份不会发送到客户端，因此只有服务器端压缩才有意义。使用默认的-Xstream时，服务器端压缩不会应用于 WAL。若要压缩 WAL，请使用客户端压缩，或者指定-Xfetch。

压缩方法可以设置为gzip、lz4、zstd、none（不压缩），也可以直接指定一个整数（0 表示不压缩，大于 0 表示gzip）。还可以选择性地指定压缩细节字符串。如果细节字符串是整数，则表示压缩级别；否则，它应为逗号分隔的项目列表，每项的形式为keyword或keyword=value。目前支持的关键字有level、long和workers。当压缩方法以纯整数形式指定时，不能再使用细节字符串。

如果未指定压缩级别，将使用默认级别。如果只指定级别而未指定算法，则级别大于 0 时使用 gzip 压缩，级别为 0 时不压缩。

当 tar 格式配合gzip、lz4或zstd使用时，所有 tar 文件名都会分别自动加上.gz、.lz4或.zst后缀。使用普通文件格式时，不能指定客户端压缩，但仍可以请求服务器端压缩。这样做时，服务器会先压缩备份再传输，而客户端会对其进行解压并提取。

当此选项与-Xstream组合使用时，如果选择了客户端 gzip 压缩，则pg_wal.tar会使用gzip压缩；但如果选择了其他压缩算法，或者选择了服务器端压缩，则不会被压缩。

将检查点模式设置为 fast（立即）或 spread（默认）（见第 25.3.4 节）。

指定在开始备份之前，应创建由--slot选项指定名称的复制槽。如果该槽已经存在，则会报错。

设置备份标签。如果未指定，则使用默认值“pg_basebackup base backup”。

默认情况下，当pg_basebackup因错误中止时，它会删除在发现自己无法完成任务之前可能已创建的所有目录（例如目标目录和预写式日志目录）。此选项会禁止这种清理，因此对调试很有帮助。

请注意，无论是否使用此选项，表空间目录都不会被清理。

默认情况下，pg_basebackup会等待所有文件都被安全写入磁盘。此选项会使pg_basebackup不经等待就直接返回，因此速度更快，但这意味着如果随后操作系统崩溃，基础备份可能会损坏。通常，此选项适合测试，但不应用于创建生产环境安装。

启用进度报告。打开此选项后，会在备份过程中给出一个近似的进度报告。由于数据库在备份过程中可能发生变化，因此这只是近似值，最终未必恰好结束在100%。特别是当备份中包含 WAL 时，总数据量无法预先估计；在这种情况下，一旦进度超过不含 WAL 时的总估计值，估计目标大小就会继续增加。

设置从源服务器收集数据时允许的最大传输速率。这有助于限制pg_basebackup对服务器的影响。取值单位为每秒千字节。使用后缀M表示每秒兆字节。也接受后缀k，但没有实际影响。有效取值范围为每秒 32 千字节到每秒 1024 兆字节。

此选项始终影响数据目录的传输。只有当收集方法为fetch时，WAL 文件的传输才会受到影响。

此选项只能与-X stream一起使用。它会使 WAL 流式传输使用指定的复制槽。如果此基础备份打算用作使用复制槽的流复制备库，那么该备库应将同一个复制槽名称用作primary_slot_name的值。这样可以确保主库在基础备份结束与新备库开始流复制之间的这段时间内，不会移除任何必需的 WAL 数据。

指定的复制槽必须已经存在，除非还同时使用了-C。

如果未指定此选项，并且服务器支持临时复制槽（10 及以上版本），则会自动使用临时复制槽进行 WAL 流式传输。

设置为fsync（默认）时，pg_basebackup会递归打开并同步备份目录中的所有文件。使用普通文件格式时，查找文件会跟随 WAL 目录和各已配置表空间的符号链接。

在 Linux 上，也可以使用syncfs，让操作系统同步包含备份目录的整个文件系统。使用普通文件格式时，pg_basebackup还会同步包含 WAL 文件和各表空间的文件系统。关于使用syncfs时需要注意的事项，见recovery_init_sync_method。

使用--no-sync时，此选项无效。

启用详细模式。它会在启动和关闭过程中输出一些额外步骤；如果同时启用了进度报告，还会显示当前正在处理的确切文件名。

指定应用到备份清单中每个文件的校验和算法。目前可用的算法有NONE、CRC32C、SHA224、SHA256、SHA384和SHA512。默认值为CRC32C。

如果选择NONE，备份清单将不包含任何校验和。否则，它将包含使用指定算法为备份中每个文件计算的校验和。此外，清单始终会包含其自身内容的SHA256校验和。SHA算法明显比CRC32C更耗费 CPU，因此选择其中一种可能会增加完成备份所需的时间。

对于希望验证备份未被篡改的用户，使用 SHA hash 函数可以为每个文件提供具有密码学安全性的摘要；而 CRC-32C 算法提供的校验和计算速度要快得多，虽然它很适合发现由于意外改动造成的错误，但并不能抵御恶意修改。请注意，要想对能够访问备份的攻击者形成防护，备份清单就需要安全地保存在其他地方，或者以其他方式确认自备份完成后未被修改。

可以使用pg_verifybackup根据备份清单检查备份的完整性。

强制将备份清单中的所有文件名编码为十六进制。如果未指定此选项，则只对非 UTF8 文件名进行十六进制编码。此选项主要用于测试读取备份清单文件的工具是否能正确处理这种情况。

禁止服务器估算将要流式传输的备份数据总量，因此 pg_stat_progress_basebackup 视图中的 backup_total 列始终为 NULL。

如果不使用此选项，备份会先枚举整个数据库的大小，然后再回过头来发送实际内容。这可能会让备份耗时略长，特别是在发送第一批数据之前所需时间会更久。如果这种估算耗时过长，此选项就很有用，因为它可以避免这段估算时间。

使用--progress时，不允许使用此选项。

禁止生成备份清单。如果未指定此选项，服务器将生成并发送一个备份清单，可使用pg_verifybackup进行验证。该清单列出了备份中的每一个文件，但不包括可能包含在其中的任何 WAL 文件。它还会保存每个文件的大小、最后修改时间以及可选的校验和。

防止为备份创建临时复制槽。

默认情况下，如果选择了 WAL 流式传输，但没有使用-S选项给出槽名，那么会创建一个临时复制槽（如果源服务器支持）。

此选项的主要目的是在服务器没有空闲复制槽时，仍然允许执行基础备份。几乎总是首选使用复制槽，因为它能防止服务器在备份期间移除所需的 WAL。

如果获取基础备份的服务器启用了校验和，则禁用对这些校验和的验证。

默认情况下，会验证校验和；校验和验证失败将导致非零退出状态。不过，在这种情况下，基础备份不会被删除，就像使用了--no-clean一样。校验和验证失败也会在pg_stat_database视图中报告。

以连接字符串的形式指定用于连接服务器的参数；这些参数会覆盖任何相互冲突的命令行选项。

出于与其他客户端应用保持一致的考虑，此选项名为--dbname；但由于pg_basebackup并不连接到集簇中的某个特定数据库，连接字符串中包含的数据库名会被服务器忽略。不过，以这种方式提供的数据库名会覆盖默认数据库名（replication），从而用于在~/.pgpass中查找复制连接的密码。类似地，连接PostgreSQL时使用的中间件或代理，也可能出于连接路由等目的使用该名称。该数据库名也可供逻辑复制槽同步使用。

指定服务器运行所在机器的主机名。如果该值以斜线开头，则它会被用作 Unix 域套接字的目录。默认值取自PGHOST环境变量（如果已设置）；否则会尝试使用 Unix 域套接字连接。

指定服务器监听连接所使用的 TCP 端口，或本地 Unix 域套接字文件扩展名。默认使用PGPORT环境变量中的值（如果已设置），否则使用编译时确定的默认值。

指定发送回源服务器的状态包之间相隔的秒数。较小的值可以让服务器端对备份进度的监控更精确。值为零时会完全禁用周期性状态更新，不过当服务器请求时仍会发送更新，以避免因超时而断开连接。默认值是 10 秒。

指定连接时使用的用户名。

禁止发出密码提示。如果服务器要求密码认证，而又无法通过其他方式（例如.pgpass文件）获得密码，则连接尝试将失败。此选项对于批处理作业和脚本很有用，因为那种场景下通常没有用户在场输入密码。

强制pg_basebackup在连接源服务器之前提示输入密码。

此选项绝非必需，因为如果服务器要求密码认证，pg_basebackup会自动提示输入密码。不过，pg_basebackup会浪费一次连接尝试来发现服务器需要密码。在某些情况下，输入-W以避免额外的连接尝试是值得的。

输出pg_basebackup的版本并退出。

显示pg_basebackup命令行参数的帮助并退出。