Postgresql 中文操作指南

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

当备份采用 tar 格式时，可以将目标目录指定为 - （连字符），导致 tar 文件被写入 stdout 。

This option is required.

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

创建 standby.signal 文件并将连接设置附加到目标目录中的 postgresql.auto.conf 文件（或在使用 tar 格式时附加到基本归档文件）。这简化了使用备份结果设置备用服务器。

postgresql.auto.conf 文件将记录连接设置，如果指定，还将记录 pg_basebackup 正在使用的复制槽，以便流复制稍后使用相同设置。

指示服务器存储基本备份的位置。默认目标是 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 存档的情况下在目标目录中启动主控，从而使输出成为完全独立的备份。

支持以下收集预写日志的_方法_：

启用 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 文件名中。使用普通格式时，可能无法指定客户端压缩，但仍然可以请求服务器端压缩。如果这样做，服务器将压缩备份以进行传输，客户端将解压缩并解压。

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

以普通文件形式编写输出，布局与源服务器的数据目录和表空间相同。当集群没有其他表空间时，整个数据库将放在目标目录中。如果集群包含其他表空间，主数据目录将放在目标目录中，但所有其他表空间将放在与它们在源服务器上相同的绝对路径中。（请参见 —​tablespace-mapping 进行更改。）

这是默认格式。

将输出作为 tar 文件写入目标目录。主数据目录的内容将写入名为 base.tar 的文件，每个其他表空间将写入一个单独的 tar 文件，该文件以该表空间的 OID 命名。

如果将目标目录指定为 - （破折号），则 tar 内容将写入标准输出，适合于管道传输（例如）gzip。仅当集群没有其他表空间且不使用 WAL 流时才允许这样做。

在备份中不要包含预写日志。

预写日志文件在备份结束时会被收集。因此，必须将源服务器的 wal_keep_size 参数设置得足够高，以便在备份结束之前不会删除所需的日志数据。如果所需的日志数据在将其传输之前已被回收，则备份将失败且不可用。

当使用 tar 格式时，预写日志文件将包含在 base.tar 文件中。

在进行备份时流式传输预写日志数据。此方法将打开与服务器的第二个连接，并在运行备份的同时并行开始流式传输预写日志。因此，它只需要两个复制连接，而不仅仅是一个。只要客户端可以跟上预写日志数据，使用此方法就不需要在源服务器上保存额外的预写日志。

当使用 tar 格式时，预写日志文件将被写入名为 pg_wal.tar 的单独文件（如果服务器版本早于 10，则该文件将被命名为 pg_xlog.tar ）。

此值为默认值。

将检查点模式设置为快速（立即）或展开（默认）（请参见 Section 26.3.3 ）。

指定在开始备份之前应创建由 —​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 流式传输。

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

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

如果选择了 NONE ，备份清单将不包含任何校验和。否则，它将使用指定的算法包含备份中每个文件的校验和。此外，清单将始终包含其自己内容的 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 视图中还将报告校验和验证故障。

指定连接到服务器时使用的参数，作为 connection string ；这些参数将覆盖任何冲突的命令行选项。

该选项称为 —​dbname ，以便与其他客户端应用程序保持一致，但由于 pg_basebackup 不会连接到集群中的任何特定数据库，因此连接字符串中的任何数据库名称都将被忽略。

指定运行服务器的计算机的主机名。如果值以斜杠开头，则将其用作 Unix 域套接字的目录。如果已设置，则默认值取自 PGHOST 环境变量，否则尝试建立 Unix 域套接字连接。

指定服务器侦听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。如果没有设置，则默认为 PGPORT 环境变量，或编译时默认值。

指定发送回源服务器的状态数据包之间的秒数。较小的值允许从服务器更准确地监视备份进度。值为零会完全禁用定期状态更新，尽管会在服务器请求时持续发送更新，以避免基于超时的断开连接。默认值为 10 秒。

指定要连接的用户名。

防止发出密码提示。如果服务器需要密码验证并且无法通过其他方式（例如 .pgpass 文件）获取密码，则连接尝试将失败。此选项在没有用户输入密码的分批作业和脚本中很有用。

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

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

打印 pg_basebackup 版本并退出。

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