pg_basebackup

pg_basebackup — 获取PostgreSQL集群的基本备份

概要

pg_basebackup[option...]

描述

pg_basebackup用于获取正在运行的PostgreSQL数据库集群的基本备份。获取备份时不会影响数据库的其他客户端，并且可以用于时间点恢复（请参阅第 26.3 节）以及作为日志传输或流复制备用服务器的起点（请参阅第 27.2 节）。

pg_basebackup会制作数据库集群文件的精确副本，同时确保服务器自动进入和退出备份模式。备份始终针对整个数据库集群进行；无法备份单个数据库或数据库对象。对于选择性备份，必须使用另一个工具，例如pg_dump。

备份通过使用复制协议的常规PostgreSQL连接进行。必须使用具有REPLICATION权限（请参见第 22.2 节）或为超级用户的用户 ID 建立连接，并且pg_hba.conf必须允许复制连接。还必须将服务器配置为将max_wal_senders设置得足够高，以提供至少一个用于备份的 walsender 和一个用于 WAL 流传输（如果使用）的 walsender。

可以同时运行多个pg_basebackup，但从性能角度来看，通常最好只进行一次备份，然后复制结果。

pg_basebackup不仅可以从主服务器进行基本备份，还可以从备用服务器进行基本备份。要从备用服务器进行备份，请设置备用服务器，以便它可以接受复制连接（即，设置max_wal_senders和hot_standby，并适当地配置其pg_hba.conf）。您还需要在主服务器上启用full_page_writes。

请注意，从备用服务器进行备份时有一些限制

• 备份历史文件不会在备份的数据库集群中创建。

• pg_basebackup 无法在备份结束时强制备用服务器切换到新的 WAL 文件。当您使用 -X none 时，如果主服务器上的写入活动较少，pg_basebackup 可能需要等待很长时间，才能切换并归档备份所需的最后一个 WAL 文件。在这种情况下，在主服务器上运行 pg_switch_wal 以触发立即 WAL 文件切换可能很有用。

• 如果在备份期间将备用服务器提升为主服务器，备份将失败。

• 备份所需的所有 WAL 记录都必须包含足够的全页写入，这需要您在主服务器上启用 full_page_writes。

每当pg_basebackup正在进行基础备份时，服务器的pg_stat_progress_basebackup视图将报告备份进度。有关详细信息，请参见第 28.4.6 节。

选项

以下命令行选项控制输出的位置和格式

-D directory
--pgdata=directory

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

当备份为 tar 格式时，目标目录可以指定为 -（破折号），导致 tar 文件被写入 stdout。

此选项是必需的。

-F format
--format=format

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

p
plain

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

这是默认格式。

t
tar

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

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

-R
--write-recovery-conf

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

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

-t target
--target=target

指示服务器放置基础备份的位置。默认目标是 client，它指定应将备份发送到运行 pg_basebackup 的计算机。如果目标改为设置为 server:/some/path，备份将存储在运行服务器的计算机的 /some/path 目录中。在服务器上存储备份需要超级用户权限或具有 pg_write_server_files 角色的权限。如果目标设置为 blackhole，内容将被丢弃，不会存储在任何地方。这仅应出于测试目的而使用，因为你最终不会获得实际备份。

由于 WAL 流是通过 pg_basebackup 而不是通过服务器实现的，因此此选项不能与 -Xstream 一起使用。由于这是默认值，因此在指定此选项时，还必须指定 -Xfetch 或 -Xnone。

-T olddir=newdir
--tablespace-mapping=olddir=newdir

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

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

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

--waldir=waldir

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

-X method
--wal-method=method

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

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

n
none

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

f
fetch

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

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

s
stream

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

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

此值为默认值。

-z
--gzip

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

-Z level
-Z [{client|server}-]method[:detail]
--compress=level
--compress=[{client|server}-]method[:detail]

请求压缩备份。如果包含 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 压缩，但如果选择了任何其他压缩算法或选择了服务器端压缩，则不会压缩。

下列命令行选项控制备份的生成和程序的调用

-c {fast|spread}
--checkpoint={fast|spread}

将检查点模式设置为快速（立即）或分散（默认）（请参阅 第 26.3.3 节）。

-C
--create-slot

指定应在启动备份之前创建 --slot 选项命名的复制槽。如果槽已存在，则会引发错误。

-l label
--label=label

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

-n
--no-clean

默认情况下，当 pg_basebackup 因错误而中止时，它会删除在发现无法完成作业之前可能已创建的任何目录（例如，目标目录和预写日志目录）。此选项禁止清理，因此对于调试很有用。

请注意，无论哪种方式，表空间目录都不会被清理。

-N
--no-sync

默认情况下，pg_basebackup 将等待所有文件安全写入磁盘。此选项导致 pg_basebackup 在不等待的情况下返回，这更快，但意味着随后的操作系统崩溃可能会损坏基本备份。通常，此选项对于测试很有用，但不应在创建生产安装时使用。

-P
--progress

启用进度报告。打开此选项将在备份期间提供近似进度报告。由于数据库在备份期间可能会发生变化，因此这只是一个近似值，可能不会完全以 100% 结束。特别是，当 WAL 日志包含在备份中时，无法预先估计数据总量，在这种情况下，一旦超过不含 WAL 的总估计值，估计的目标大小就会增加。

-r rate
--max-rate=rate

设置从源服务器收集数据的最大传输速率。这有助于限制 pg_basebackup 对服务器的影响。值以每秒千字节为单位。使用后缀 M 表示每秒兆字节。后缀 k 也可以接受，并且没有效果。有效值介于每秒 32 千字节和每秒 1024 兆字节之间。

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

-S slotname
--slot=slotname

此选项只能与 -X stream 结合使用。它使 WAL 流使用指定的复制槽。如果基本备份打算使用复制槽作为流复制备用，则备用应使用与 primary_slot_name 相同的复制槽名称。这可确保主服务器在基本备份结束和在新备用上开始流复制之间的时间内不会删除任何必要的 WAL 数据。

除非同时使用了选项 -C，否则指定的复制槽必须存在。

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

-v
--verbose

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

--manifest-checksums=algorithm

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

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

对于希望验证备份未被篡改的用户来说，使用 SHA 哈希函数可以提供每个文件的加密安全摘要，而 CRC32C 算法提供的校验和计算速度要快得多；它擅长捕获因意外更改而导致的错误，但无法抵抗恶意修改。请注意，为了对抗有权访问备份的攻击者，备份清单需要安全地存储在其他地方，或以其他方式验证自备份以来未被修改。

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

--manifest-force-encode

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

--no-estimate-size

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

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

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

--no-manifest

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

--no-slot

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

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

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

--no-verify-checksums

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

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

以下命令行选项控制与源服务器的连接

-d connstr
--dbname=connstr

指定用于连接到服务器的参数，作为 连接字符串；这些参数将覆盖任何冲突的命令行选项。

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

-h host
--host=host

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

-p port
--port=port

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

-s interval
--status-interval=interval

指定发送回源服务器的状态数据包之间的秒数。值越小，服务器对备份进度的监控越准确。零值会完全禁用定期状态更新，但当服务器请求时仍会发送更新，以避免基于超时的断开连接。默认值为 10 秒。

-U 用户名
--username=用户名

指定要连接的用户名。

-w
--no-password

禁止发出密码提示。如果服务器需要密码身份验证，并且无法通过 .pgpass 文件等其他方式获得密码，则连接尝试将失败。此选项在没有用户输入密码的批处理作业和脚本中非常有用。

-W
--password

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

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

还有其他选项

-V
--version

打印 pg_basebackup 版本并退出。

-?
--help

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

环境

此实用程序与大多数其他PostgreSQL实用程序一样，使用libpq支持的环境变量（请参阅第 34.15 节）。

环境变量PG_COLOR指定是否在诊断消息中使用颜色。可能的值有always、auto和never。

备注

在备份开始时，需要在源服务器上执行检查点。这可能需要一些时间（特别是如果未使用--checkpoint=fast选项），在此期间pg_basebackup似乎处于空闲状态。

备份将包括数据目录和表空间中的所有文件，包括配置文件和第三方放置在该目录中的任何附加文件，但 PostgreSQL 管理的某些临时文件除外。但是，只复制常规文件和目录，但用于表空间的符号链接除外。指向 PostgreSQL 已知某些目录的符号链接将复制为空目录。其他符号链接和特殊设备文件将被跳过。有关确切详细信息，请参见第 55.4 节。

在普通格式中，表空间将备份到源服务器上的相同路径，除非使用选项--tablespace-mapping。如果没有此选项，在与服务器相同的主机上运行普通格式基本备份将不起作用（如果表空间正在使用），因为备份必须写入与原始表空间相同的目录位置。

当使用 tar 格式时，用户有责任在启动使用数据的 PostgreSQL 服务器之前解压缩每个 tar 文件。如果有其他表空间，则需要将它们的 tar 文件解压缩到正确的位置。在这种情况下，服务器将根据base.tar文件中包含的tablespace_map文件的内容创建这些表空间的符号链接。

pg_basebackup与相同或较旧主要版本的服务器配合使用，最低版本为 9.1。但是，WAL 流模式 (-X stream) 仅适用于服务器版本 9.3 及更高版本，而 tar 格式 (--format=tar) 仅适用于服务器版本 9.5 及更高版本。

如果在源集群上启用了组权限，pg_basebackup将保留数据文件的组权限。

示例

要在mydbserver上创建服务器的基本备份并将其存储在本地目录/usr/local/pgsql/data中

$ pg_basebackup -h mydbserver -D /usr/local/pgsql/data

要使用每个表空间的一个压缩 tar 文件创建本地服务器的备份，并将其存储在目录backup中，同时在运行时显示进度报告

$ pg_basebackup -D backup -Ft -z -P

要创建单表空间本地数据库的备份并使用bzip2对其进行压缩

$ pg_basebackup -D - -Ft -X fetch | bzip2 > backup.tar.bz2

（如果数据库中有多个表空间，此命令将失败。）

要创建本地数据库的备份，其中/opt/ts中的表空间重新定位到./backup/ts

$ pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts

要创建本地服务器的备份，其中每个表空间使用gzip在级别 9 上压缩一个 tar 文件，存储在目录backup中

$ pg_basebackup -D backup -Ft --compress=gzip:9

另请参阅

pg_dump，第 28.4.6 节