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

当备份为 tar 格式时，目标目录可以被指定为 -（短横线），这会导致 tar 文件被写到 stdout。

此选项是必需的。

选择输出的格式。format 可以是以下几种之一：

执行一次 incremental backup。必须提供参考备份的备份清单，它将被上传到服务器，服务器将以发送所请求的增量备份作为响应。

创建一个 standby.signal 文件，并把连接设置追加到目标目录中的 postgresql.auto.conf 文件（当使用 tar 格式时则追加到基础归档文件中）。这使得使用备份的结果建立一台后备服务器变得更加容易。

postgresql.auto.conf 文件将记录连接设置，以及（如果指定了的话）pg_basebackup 正在使用的复制槽，这样流复制和 logical replication slot synchronization 稍后将使用相同的设置。只有当在连接字符串或 environment variable 中显式指定了 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 都必须是绝对路径。如果任一路径中需要包含等号（=），请在该等号前面加上一个反斜杠。对于多个表空间，可以多次指定此选项。

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

当前，此选项只对 plain 输出格式有效；如果选择了 tar 格式，它将被忽略。

设置用于写入 WAL（预写式日志）文件的目录。默认情况下，WAL 文件会被放在目标目录的 pg_wal 子目录中，但可以使用此选项把它们放到别处。waldir 必须是一个绝对路径。与主目标目录一样，waldir 不必事先存在，但如果它存在则必须为空。只有当备份为 plain 格式时才能指定此选项。

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

支持下列用于收集预写式日志的 method 方法：

以默认压缩级别启用 tar 文件输出的 gzip 压缩。只有在使用 tar 格式时压缩才可用，并且后缀 .gz 将被自动加到所有 tar 文件名上。

请求对备份进行压缩。如果包含 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 一起使用时，后缀 .gz、.lz4 或 .zst 将分别被自动加到所有 tar 文件名上。当使用 plain 格式时，不能指定客户端压缩，但仍然可以请求服务器端压缩。如果这样做了，服务器将为传输而压缩备份，客户端将把它解压并解开。

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

将检查点模式设置为 fast（立即）或 spread（默认值）（参见 Section 25.3.6）。

指定应在开始备份之前创建由 --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 会递归地打开并同步备份目录中的所有文件。当使用 plain 格式时，对文件的搜索将跟随 WAL 目录和每个已配置表空间的符号链接。

在 Linux 上，可以改用 syncfs 来要求操作系统同步包含备份目录的整个文件系统。当使用 plain 格式时，pg_basebackup 还会同步包含 WAL 文件和每个表空间的文件系统。请参见 recovery_init_sync_method 以了解使用 syncfs 时需要注意的事项。

当使用 --no-sync 时，此选项没有效果。

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

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

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

对于希望验证备份未被篡改的用户来说，使用 SHA 哈希函数可以提供每个文件在密码学上安全的摘要，而 CRC-32C 算法提供的校验和计算起来要快得多；它善于捕捉由意外改动造成的错误，但不能抵御恶意的修改。注意，为了对能够访问备份的攻击者有效，备份清单需要被安全地存储在别处，或者以其他方式验证其自备份完成以来未被修改过。

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

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

阻止服务器估计将被流式传输的备份数据总量，导致 backup_total 列（位于 pg_stat_progress_basebackup 视图中）总是为 NULL。

如果不使用此选项，备份将先枚举整个数据库的大小，然后再回过头来发送实际内容。这可能会让备份耗时略长，特别是在发送第一批数据之前会花费更长的时间。如果这种估计时间太长，此选项可用于避免它。

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

禁用备份清单的生成。如果没有指定此选项，服务器将生成并发送一个备份清单，可以使用 pg_verifybackup 来验证它。清单是备份中存在的每个文件的列表，但可能包含的任何 WAL 文件除外。它还存储每个文件的大小、最后修改时间和一个可选的校验和。

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

默认情况下，如果选择了日志流传输但没有通过 -S 选项给出槽名，则会创建一个临时复制槽（如果源服务器支持的话）。

此选项的主要目的是在服务器没有空闲复制槽时也能进行基础备份。几乎总是更推荐使用复制槽，因为它可以防止备份期间所需的 WAL 被服务器移除。

如果在取出基础备份的服务器上启用了校验和，则禁用对校验和的验证。

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

指定用于连接到服务器的参数，采用 connection string 的形式；这些参数将覆盖任何与之冲突的命令行选项。

为了与其他客户端应用保持一致，此选项被命名为 --dbname，但由于 pg_basebackup 不会连接到集群中的任何特定数据库，连接字符串中包含的任何数据库名都会被服务器忽略。不过，以这种方式提供的数据库名会覆盖默认数据库名（replication），以便在 ~/.pgpass 中查找复制连接的密码。类似地，用于连接 PostgreSQL 的中间件或代理可能会将该名称用于连接路由等目的。数据库名也可以被 logical replication slot synchronization 使用。

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

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

指定发回源服务器的状态包之间的秒数。较小的值允许从服务器更准确地监视备份进度。值为零会完全禁用周期性的状态更新，不过在服务器请求时仍会发送一次更新，以避免基于超时的断开。默认值是 10 秒。

指定连接所用的用户名。

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

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

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

打印 pg_basebackup 的版本并退出。

显示关于 pg_basebackup 命令行参数的帮助，然后退出。