2025年9月25日: PostgreSQL 18 发布!
支持的版本: 当前 (18) / 17 / 16 / 15 / 14 / 13
开发版本: devel
不支持的版本: 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1

pg_basebackup

pg_basebackup — 备份 PostgreSQL 集群的基线备份

概要

pg_basebackup [选项...]

描述

pg_basebackup 用于备份正在运行的 PostgreSQL 数据库集群的基线备份。备份操作不会影响数据库的其他客户端,可用于时间点恢复(参见 第 25.3 节)以及作为日志传输或流复制备用服务器的起点(参见 第 26.2 节)。

pg_basebackup 可以进行完全基线备份或增量基线备份。当用于完全备份时,它会复制数据库集群文件的精确副本。当用于增量备份时,某些原本会包含在完全备份中的文件可能会被替换为同一文件的增量版本,仅包含自参考备份以来已修改的块。增量备份不能直接使用;而是必须先使用 pg_combinebackup 将其与它所依赖的先前备份合并。有关增量备份的更多信息,请参见 第 25.3.3 节,有关从备份恢复的步骤,请参见 第 25.3.5 节

在任何模式下,pg_basebackup 都会自动将服务器置于备份模式并从中退出。备份始终针对整个数据库集群进行;无法备份单个数据库或数据库对象。对于选择性备份,必须使用另一个工具,例如 pg_dump

备份通过使用复制协议的常规 PostgreSQL 连接进行。连接必须使用具有 REPLICATION 权限(参见 第 21.2 节)或超级用户的用户 ID 进行,并且 pg_hba.conf 必须允许复制连接。服务器还必须配置 max_wal_senders 以提供足够的 walsender(至少一个用于备份,一个用于 WAL 流式传输(如果使用))。

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

pg_basebackup 不仅可以从主服务器,还可以从备用服务器进行基线备份。要从备用服务器备份,请将备用服务器设置为可以接受复制连接(即,设置 max_wal_sendershot_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 视图将报告备份的进度。有关详细信息,请参见 第 27.4.6 节

选项

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

-D directory
--pgdata=directory

设置输出目标目录。如果该目录不存在,pg_basebackup 将创建该目录(以及任何缺失的父目录)。如果该目录已存在,则必须为空。

当备份为 tar 格式时,目标目录可以指定为 -(连字符),这会将 tar 文件写入 stdout

此选项是必需的。

-F format
--format=format

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

p
plain

将输出写入普通文件,其布局与源服务器的数据目录和表空间相同。当集群没有额外的表空间时,整个数据库将放在目标目录中。如果集群包含额外的表空间,则主数据目录将放在目标目录中,但所有其他表空间将放在源服务器上具有的相同绝对路径中。(有关更改,请参见 --tablespace-mapping。)

这是默认格式。

t
tar

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

如果目标目录指定为 -(连字符),则 tar 内容将写入标准输出,适合通过管道传输到(例如)gzip。仅当集群没有额外的表空间并且未使用 WAL 流式传输时,才允许这样做。

-i old_manifest_file
--incremental=old_manifest_file

执行增量备份。必须提供参考备份的备份清单,并将其上传到服务器,服务器将响应发送请求的增量备份。

-R
--write-recovery-conf

在目标目录(或使用 tar 格式时的基础存档文件内)中创建 standby.signal 文件,并将连接设置追加到 postgresql.auto.conf 文件。这有助于使用备份结果设置备用服务器。

postgresql.auto.conf 文件将记录连接设置,如果指定,还将记录 pg_basebackup 使用的复制槽,以便流复制和逻辑复制槽同步之后可以使用相同的设置。仅当在连接字符串或环境变量中显式指定了 dbname 时,才会记录 dbname。

-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 不需要预先存在,但如果存在,则必须为空。 olddirnewdir 都必须是绝对路径。如果任一路径需要包含等号(=),则在其前面加上反斜杠。此选项可以多次指定用于多个表空间。

如果以这种方式重新定位表空间,主数据目录中的符号链接将被更新以指向新位置。因此,新的数据目录已准备好用于新的服务器实例,所有表空间都位于更新后的位置。

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

--waldir=waldir

设置写入 WAL(预写日志)文件的目录。默认情况下,WAL 文件将放置在目标目录的 pg_wal 子目录中,但此选项可用于将它们放在其他位置。 waldir 必须是绝对路径。与主目标目录一样,waldir 不需要预先存在,但如果存在,则必须为空。此选项只能在备份为普通格式时指定。

-X method
--wal-method=method

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

支持以下用于收集预写日志的 方法

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]

请求压缩备份。如果包含 clientserver,则指定压缩的位置。在服务器上压缩将减少传输带宽,但会增加服务器的 CPU 消耗。默认值为 client,除非使用了 --target。在这种情况下,备份不会发送到客户端,因此只有服务器端压缩是合理的。当使用 -Xstream(这是默认设置)时,WAL 不会应用服务器端压缩。要压缩 WAL,请使用客户端压缩,或指定 -Xfetch

压缩方法可以设置为 gziplz4zstdnone(无压缩)或整数(0 表示无压缩,大于 0 表示 gzip)。可以选择性地指定压缩详细信息字符串。如果详细信息字符串是整数,则它指定压缩级别。否则,它应该是一个逗号分隔的关键字列表,每个关键字的形式为 keywordkeyword=value。目前支持的关键字是 levellongworkers。当压缩方法指定为纯整数时,不能使用详细信息字符串。

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

当 tar 格式与 gziplz4zstd 一起使用时,后缀 .gz.lz4.zst 将分别自动添加到所有 tar 文件名。当使用普通格式时,不能指定客户端压缩,但仍然可以请求服务器端压缩。如果这样做,服务器将压缩备份进行传输,然后客户端将解压缩并提取它。

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

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

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

将检查点模式设置为快速(即时)或分布(默认)(参见 第 25.3.4 节)。

-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 流式传输使用临时复制槽。

--sync-method=method

当设置为 fsync(这是默认值)时,pg_basebackup 将递归打开并同步备份目录中的所有文件。当使用普通格式时,文件搜索将遵循 WAL 目录和每个配置的表空间的符号链接。

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

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

-v
--verbose

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

--manifest-checksums=algorithm

指定应应用于备份清单中每个文件的校验和算法。目前,可用算法为 NONECRC32CSHA224SHA256SHA384SHA512。默认值为 CRC32C

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

使用 SHA 哈希函数为每个文件提供密码学安全的摘要,供希望验证备份未被篡改的用户使用,而 CRC-32C 算法提供了一个计算速度快得多的校验和;它能很好地捕获由意外更改引起错误,但不抵抗恶意修改。请注意,为了能对抗有权访问备份的对手,备份清单需要存储在其他安全的地方,或以其他方式验证自备份以来未被修改。

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

--manifest-force-encode

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

--no-estimate-size

阻止服务器估计将要流式传输的备份数据总量,导致 pg_stat_progress_basebackup 视图中的 backup_total 列始终为 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 不连接到集群中的任何特定数据库,因此服务器将忽略连接字符串中包含的任何数据库名称。但是,以这种方式提供的数据库名称会覆盖默认数据库名称(replication),以在 ~/.pgpass 中查找复制连接的密码。类似地,用于连接 PostgreSQL 的中间件或代理可能会使用该名称来实现连接路由等目的。数据库名称也可以由逻辑复制槽同步使用。

-h 主机
--host=主机

指定服务器所在机器的主机名。如果值以斜杠开头,则用作 Unix 域套接字的目录。默认值从 PGHOST 环境变量获取(如果已设置),否则将尝试进行 Unix 域套接字连接。

-p 端口
--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 支持的环境变量(参见 第 32.15 节)。

环境变量 PG_COLOR 指定是否在诊断消息中使用颜色。可能的值为 alwaysautonever

注释

在备份开始时,需要在源服务器上执行检查点。这可能需要一些时间(尤其是在未选择选项 --checkpoint=fast 时),在此期间 pg_basebackup 可能会显示为闲置。

备份将包括数据目录和表空间中的所有文件,包括配置文件以及第三方放置在目录中的任何其他文件,但某些由 PostgreSQL 管理的临时文件和操作系统文件除外。但只复制常规文件和目录,除非保留了用作表空间的符号链接。指向 PostgreSQL 已知某些目录的符号链接将被复制为空目录。其他符号链接和特殊设备文件将被跳过。有关精确详细信息,请参见 第 54.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 及更高版本,增量备份(--incremental)仅适用于服务器版本 17 及更高版本。

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 压缩,并存储在 backup 目录中

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

另请参阅

pg_dump第 27.4.6 节

提交更正

如果您在文档中发现任何不正确、与您对特定功能的体验不符或需要进一步说明的内容,请使用此表格报告文档问题。