PostgreSQL pg_basebackup

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

当备份处于 tar 模式中，目标目录可以被指定为-（破折号），从而将 tar 文件写入stdout。

这个选项是必需的。

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

创建一个standby.signal文件，并将连接设置附加到目标目录（或使用tar格式的基本存档文件中）的postgresql.auto.conf文件中。 这样可以简化使用备份结果设置备用服务器的过程。

postgresql.auto.conf文件将记录连接设置（如果有）以及pg_basebackup所使用的复制槽，这样流复制后面就会使用相同的设置。

在备份期间将目录olddir中的表空间重定位到newdir中。为使之有效，olddir必须与源服务器上定义的表空间的路径规范完全匹配。（但如果备份中没有包含olddir中的表空间也不是错误）。同时， newdir 是接收主机文件系统中的目录。与主目标目录一样，newdir不必已经存在，但是如果确实存在，则必须为空。olddir和newdir必须是绝对路径。如果一个路径凑巧包含了一个=符号，可用反斜线对它转义。对于多个表空间可以多次使用这个选项。

如果以这种方法重定位一个表空间，主数据目录中的符号链接会被更新成指向新位置。因此新数据目录已经可以被一个所有表空间位于更新后位置的新服务器实例使用。

指定用于预写式日志目录的位置。waldir必须是绝对路径。只有当备份是平面文件模式时才能指定事务日志目录。 设置要写入WAL（预写日志）文件的目录。 默认情况下，WAL文件将放置在目标目录的pg_wal子目录中，但是此选项可用于将它们放置在其他位置。waldir必须是绝对路径。与主目标目录一样， waldir 不必已经存在，但是如果确实存在，则必须为空。只有当备份是平面文件模式时才可以指定此选项。

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

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

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

启用对 tar 文件输出的 gzip 压缩，并且制定压缩机别（0 到 9，0 是不压缩，9 是最佳压缩）。只有使用 tar 格式时压缩才可用，并且会在所有tar文件名后面自动加上后缀.gz。

将检查点模式设置为 fast（立刻）或 spread（默认）（见第 25.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视图中。

指定用于连接到服务器的参数，比如连接字符串；这些将覆盖所有冲突的命令行选项。

为了和其他客户端应用一致，该选项被称为--dbname。但是因为pg_basebackup并不连接到集簇中的任何特定数据库，连接字符串中的任何数据库名将被忽略。

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

指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。默认用PGPORT环境变量中的值（如果设置），或者一个编译在程序中的默认值。

指定发送回源服务器的状态包之间的秒数。较小的值可以更准确地监视服务器的备份进度。一个零值完全禁用这种周期性的状态更新，不过当服务器需要时还是会有一个更新会被发送来避免超时导致的断开连接。默认值是 10 秒。

指定连接的用户名。

防止发出口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个.pgpass文件），那儿连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。

强制pg_basebackup在连接到源服务器之前提示要求一个口令。

这个选项不是必不可少的，因为如果服务器要求口令认证，pg_basebackup将自动提示要求一个口令。但是，pg_basebackup将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用-W来避免额外的连接尝试。

打印pg_basebackup版本并退出。

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