设置要写入输出的目标目录。如果不存在，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，否则可以在不需要查阅 WAL 存档的情况下在目标目录中启动后主，从而使输出成为完全独立的备份。

支持采用以下 method 来收集预写日志

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

请求对备份压缩。如果包括 client 或 server，则说明压缩操作执行的位置。在服务器中压缩会降低传输带宽，但会增加服务器 CPU 占用。除非使用 --target，默认值为 client。在此情况下，备份不会发送到客户端，因此仅适合服务器压缩。当使用默认值 -Xstream 时，不会对 WAL 应用服务器端压缩。要压缩 WAL，请使用客户端压缩或指定 -Xfetch。

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

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

当 tar 格式与 gzip、lz4 或 zstd 配合使用时，后缀 .gz、.lz4 或 .zst 会分别自动添加到所有 tar 文件名。当使用 plain 格式时，可能不会指定客户端压缩，但仍然可以请求服务器端压缩。如果执行此操作，服务器将压缩备份以进行传输，客户端将解压缩并提取它。

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

设置检查点模式为快速（立即）或分布（默认）（请参见第 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 文件和每个表空间的文件系统。请参阅 recovery_init_sync_method 了解使用 syncfs 时需要注意的事项。

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

启用详细模式。如果启用了进度报告，详细模式将在启动和关闭期间输出一些额外步骤，并显示当前正在处理的确切文件名。

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

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

对希望验证备份未被篡改的用户来说，使用 SHA 哈希函数针对每个文件提供了加密安全摘要，而 CRC32C 算法提供了计算速度更快的校验和；它善于检测由于意外更改导致的错误，但对恶意修改却没有抵抗力。请注意，为了对抗有权访问备份的对手，备份清单需要在别处安全存储或以其他方式验证自采取备份以来未被修改过。

pg_verifybackup 可用于检查备份与备份清单的完整性。

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

阻止服务器估计将要流式传输的备份数据的总量，导致 pg_stat_progress_basebackup 视图中的 backup_total 列始终为 NULL。

如果没有此选项，备份将从枚举整个数据库的大小开始，然后返回并发送实际内容。这可能会使备份花费更长的时间，尤其是发送第一条数据之前需要的时间更长。如果估计时间太长，可以使用此选项来避免此类估计时间。

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

禁用备份清单的生成。如果未指定此选项，服务器将生成并发送一个备份清单，该清单可以使用 pg_verifybackup 进行验证。清单是备份中所有文件的列表，但包括任何可能包含的 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 命令行参数的帮助，并退出。