pg_basebackup

pg_basebackup — 获取 PostgreSQL 集簇的基础备份

当前查看 PostgreSQL 18.6。

说明

pg_basebackup — 获取 PostgreSQL 集簇的基础备份

手册中的可执行程序: pg_basebackup
程序版本: 18.6
参考清单: 客户端程序
选项定义组: 35

用法

pg_basebackup [ option ...]

手册中的选项

选项与参数	说明
-D directory --pgdata= directory	设置写入输出的目标目录。如果该目录不存在， pg_basebackup 会创建它（以及所有缺失的父目录）。如果该目录已经存在，则必须为空。
-F format --format= format	选择输出格式。 format 可以是以下值之一：
-i old_manifest_file --incremental= old_manifest_file	执行增量备份。必须提供参考备份的备份清单；该文件将被上传到服务器，随后服务器会返回所请求的增量备份。
-R --write-recovery-conf	创建 standby.signal 文件，并将连接设置追加到目标目录中的 postgresql.auto.conf 文件中（如果使用 tar 格式，则追加到基础归档文件内）。这样可以更方便地利用备份结果搭建备库。
-t target --target= target	指示服务器将基础备份放到哪里。默认目标是 client ，表示备份应发送到运行 pg_basebackup 的那台机器。如果目标改为 server:/some/path ，则备份会存储在服务器运行所在机器的 /some/path 目录中。将备份存储在服务器上需要超级用户权限，或拥有 pg_write_server_files 角色的权限。如果目标设置为 blackhole ，则内容会被丢弃，不会存储到任何地方。这只应用于测试目的，因为最终不会得到实际备份。
-T olddir = newdir --tablespace-mapping= olddir = newdir	在备份期间，将目录 olddir 中的表空间重定位到 newdir 。要使此选项生效， olddir 必须与源服务器上定义的该表空间路径完全一致。（但如果源服务器上在 olddir 中没有表空间，也不算错误。）与此同时， newdir 是接收主机文件系统中的一个目录。与主目标目录一样， newdir 不必事先存在，但如果存在则必须为空。 olddir 和 newdir 都必须是绝对路径。如果任一路径中需要包含等号（ = ），请在其前面加上反斜杠。可以多次指定此选项，以处理多个表空间。
--waldir= waldir	设置写入 WAL（预写式日志）文件的目录。默认情况下，WAL 文件会放在目标目录的 pg_wal 子目录中，但此选项可用于将其放在其他位置。 waldir 必须是绝对路径。与主目标目录一样， waldir 不必事先存在，但如果存在则必须为空。只有当备份采用普通文件格式时，才能指定此选项。
-X method --wal-method= method	在备份中包含所需的 WAL（预写式日志）文件。这将包括备份期间生成的所有预写式日志。除非指定方法 none ，否则就可以在目标目录中启动 postmaster，而无需查阅 WAL 归档，从而使输出成为一个完全独立的备份。
-z --gzip	启用 tar 文件输出的 gzip 压缩，使用默认压缩级别。压缩仅在使用 tar 格式时可用，并且所有 tar 文件名都会自动添加 .gz 后缀。
-Z level -Z [{client\|server}-] method [: detail ] --compress= level --compress=[{client\|server}-] method [: detail ]	请求对备份进行压缩。如果包含 client 或 server ，则指定压缩执行的位置。在服务器端压缩会减少传输带宽占用，但会增加服务器 CPU 消耗。默认值是 client ，但使用 --target 时除外；此时备份不会发送到客户端，因此只有服务器端压缩才有意义。使用默认的 -Xstream 时，服务器端压缩不会应用于 WAL。若要压缩 WAL，请使用客户端压缩，或者指定 -Xfetch 。
-c {fast\|spread} --checkpoint={fast\|spread}	将检查点模式设置为 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 兆字节。
-S slotname --slot= slotname	此选项只能与 -X stream 一起使用。它会使 WAL 流式传输使用指定的复制槽。如果此基础备份打算用作使用复制槽的流复制备库，那么该备库应将同一个复制槽名称用作 primary_slot_name 的值。这样可以确保主库在基础备份结束与新备库开始流复制之间的这段时间内，不会移除任何必需的 WAL 数据。
--sync-method= method	设置为 fsync （默认）时， pg_basebackup 会递归打开并同步备份目录中的所有文件。使用普通文件格式时，查找文件会跟随 WAL 目录和各已配置表空间的符号链接。
-v --verbose	启用详细模式。它会在启动和关闭过程中输出一些额外步骤；如果同时启用了进度报告，还会显示当前正在处理的确切文件名。
--manifest-checksums= algorithm	指定应用到备份清单中每个文件的校验和算法。目前可用的算法有 NONE 、 CRC32C 、 SHA224 、 SHA256 、 SHA384 和 SHA512 。默认值为 CRC32C 。
--manifest-force-encode	强制将备份清单中的所有文件名编码为十六进制。如果未指定此选项，则只对非 UTF8 文件名进行十六进制编码。此选项主要用于测试读取备份清单文件的工具是否能正确处理这种情况。
--no-estimate-size	禁止服务器估算将要流式传输的备份数据总量，因此 pg_stat_progress_basebackup 视图中的 backup_total 列始终为 NULL。
--no-manifest	禁止生成备份清单。如果未指定此选项，服务器将生成并发送一个备份清单，可使用 pg_verifybackup 进行验证。该清单列出了备份中的每一个文件，但不包括可能包含在其中的任何 WAL 文件。它还会保存每个文件的大小、最后修改时间以及可选的校验和。
--no-slot	防止为备份创建临时复制槽。
--no-verify-checksums	如果获取基础备份的服务器启用了校验和，则禁用对这些校验和的验证。
-d connstr --dbname= connstr	以连接字符串的形式指定用于连接服务器的参数；这些参数会覆盖任何相互冲突的命令行选项。
-h host --host= host	指定服务器运行所在机器的主机名。如果该值以斜线开头，则它会被用作 Unix 域套接字的目录。默认值取自 PGHOST 环境变量（如果已设置）；否则会尝试使用 Unix 域套接字连接。
-p port --port= port	指定服务器监听连接所使用的 TCP 端口，或本地 Unix 域套接字文件扩展名。默认使用 PGPORT 环境变量中的值（如果已设置），否则使用编译时确定的默认值。
-s interval --status-interval= interval	指定发送回源服务器的状态包之间相隔的秒数。较小的值可以让服务器端对备份进度的监控更精确。值为零时会完全禁用周期性状态更新，不过当服务器请求时仍会发送更新，以避免因超时而断开连接。默认值是 10 秒。
-U username --username= username	指定连接时使用的用户名。
-w --no-password	禁止发出密码提示。如果服务器要求密码认证，而又无法通过其他方式（例如 .pgpass 文件）获得密码，则连接尝试将失败。此选项对于批处理作业和脚本很有用，因为那种场景下通常没有用户在场输入密码。
-W --password	强制 pg_basebackup 在连接源服务器之前提示输入密码。
-V --version	输出 pg_basebackup 的版本并退出。
-? --help	显示 pg_basebackup 命令行参数的帮助并退出。

手册定义

pg_basebackup

pg_basebackup — 获取PostgreSQL集簇的基础备份

大纲

pg_basebackup [option...]

说明

pg_basebackup用于获取正在运行的PostgreSQL数据库集簇的基础备份。备份过程不会影响数据库的其他客户端，并且该备份既可用于时间点恢复（见第 25.3 节），也可用作日志传送或流复制备库的起点（见第 26.2 节）。

pg_basebackup既可以执行完整基础备份，也可以执行增量基础备份。执行完整备份时，它会精确复制数据库集簇的文件。执行增量备份时，原本会包含在完整备份中的某些文件，可能会被这些文件的增量版本替代，其中仅包含自参考备份以来被修改过的块。增量备份不能直接使用；必须先使用pg_combinebackup将其与它所依赖的先前备份合并。关于增量备份的更多信息，见第 25.3.3 节；关于从备份恢复的步骤，见第 25.3.5 节。

在任何模式下，pg_basebackup都会确保服务器自动进入和退出备份模式。备份始终针对整个数据库集簇；不可能只备份单个数据库或数据库对象。对于选择性备份，必须使用诸如pg_dump之类的其他工具。

备份是通过一个使用复制协议的常规PostgreSQL连接进行的。建立该连接所使用的用户 ID 必须具有REPLICATION权限（见第 21.2 节），或者是超级用户，并且pg_hba.conf必须允许该复制连接。服务器还必须将max_wal_senders设置得足够高，以便至少提供一个用于备份的 WAL 发送进程，并在使用 WAL 流式传输时再提供一个 WAL 发送进程。

可以同时运行多个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视图都会报告备份进度。详见第 27.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 流式传输时，才允许这样做。

-i old_manifest_file --incremental=old_manifest_file

执行增量备份。必须提供参考备份的备份清单；该文件将被上传到服务器，随后服务器会返回所请求的增量备份。

-R --write-recovery-conf

创建standby.signal 文件，并将连接设置追加到目标目录中的postgresql.auto.conf文件中（如果使用 tar 格式，则追加到基础归档文件内）。这样可以更方便地利用备份结果搭建备库。

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不必事先存在，但如果存在则必须为空。olddir和newdir都必须是绝对路径。如果任一路径中需要包含等号（=），请在其前面加上反斜杠。可以多次指定此选项，以处理多个表空间。

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

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

--waldir=waldir

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

-X method --wal-method=method

在备份中包含所需的 WAL（预写式日志）文件。这将包括备份期间生成的所有预写式日志。除非指定方法none，否则就可以在目标目录中启动 postmaster，而无需查阅 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 格式时可用，并且所有 tar 文件名都会自动添加.gz后缀。

-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使用时，所有 tar 文件名都会分别自动加上.gz、.lz4或.zst后缀。使用普通文件格式时，不能指定客户端压缩，但仍可以请求服务器端压缩。这样做时，服务器会先压缩备份再传输，而客户端会对其进行解压并提取。

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

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

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

将检查点模式设置为 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

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

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

对于希望验证备份未被篡改的用户，使用 SHA hash 函数可以为每个文件提供具有密码学安全性的摘要；而 CRC-32C 算法提供的校验和计算速度要快得多，虽然它很适合发现由于意外改动造成的错误，但并不能抵御恶意修改。请注意，要想对能够访问备份的攻击者形成防护，备份清单就需要安全地保存在其他地方，或者以其他方式确认自备份完成后未被修改。

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

--manifest-force-encode

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

--no-estimate-size

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

如果不使用此选项，备份会先枚举整个数据库的大小，然后再回过头来发送实际内容。这可能会让备份耗时略长，特别是在发送第一批数据之前所需时间会更久。如果这种估算耗时过长，此选项就很有用，因为它可以避免这段估算时间。

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

--no-manifest

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

--no-slot

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

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

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

--no-verify-checksums

如果获取基础备份的服务器启用了校验和，则禁用对这些校验和的验证。

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

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

-d connstr --dbname=connstr

以连接字符串的形式指定用于连接服务器的参数；这些参数会覆盖任何相互冲突的命令行选项。

出于与其他客户端应用保持一致的考虑，此选项名为--dbname；但由于pg_basebackup并不连接到集簇中的某个特定数据库，连接字符串中包含的数据库名会被服务器忽略。不过，以这种方式提供的数据库名会覆盖默认数据库名（replication），从而用于在~/.pgpass中查找复制连接的密码。类似地，连接PostgreSQL时使用的中间件或代理，也可能出于连接路由等目的使用该名称。该数据库名也可供逻辑复制槽同步使用。

-h host --host=host

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

-p port --port=port

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

-s interval --status-interval=interval

指定发送回源服务器的状态包之间相隔的秒数。较小的值可以让服务器端对备份进度的监控更精确。值为零时会完全禁用周期性状态更新，不过当服务器请求时仍会发送更新，以避免因超时而断开连接。默认值是 10 秒。

-U username --username=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指定是否在诊断消息中使用颜色。可能的值为always、auto和never。

注解

在备份开始时，需要在源服务器上执行一次检查点。这可能需要一些时间（尤其是在未使用--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

要为本地服务器创建一个备份，为每个表空间生成一个 tar 文件，并使用gzip以 9 级压缩后存储到目录backup中：

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

另见

pg_dump, Section 27.4.6

文档与源码

来源构建

版本: 18.6
构建: https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
来源指纹: ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8

版本比较

PostgreSQL 14 → 15: 属性变化。

以下差异保留原始字段名与英文源描述。

--- PostgreSQL 14
+++ PostgreSQL 15
@@ -26,6 +26,14 @@
       "signature": "-R --write-recovery-conf"
     },
     {
+      "description": "Instructs the server where to place the base backup. The default target is client , which specifies that the backup should be sent to the machine where pg_basebackup is running. If the target is instead set to server:/some/path , the backup will be stored on the machine where the server is running in the /some/path directory. Storing a backup on the server requires superuser privileges or having privileges of the pg_write_server_files role. If the target is set to blackhole , the contents are discarded and not stored anywhere. This should only be used for testing purposes, as you will not end up with an actual backup. Since WAL streaming is implemented by pg_basebackup rather than by the server, this option cannot be used together with -Xstream . Since that is the default, when this option is specified, you must also specify either -Xfetch or -Xnone .",
+      "names": [
+        "-t target",
+        "--target= target"
+      ],
+      "signature": "-t target --target= target"
+    },
+    {
       "description": "Relocates the tablespace in directory olddir to newdir during the backup. To be effective, olddir must exactly match the path specification of the tablespace as it is defined on the source server. (But it is not an error if there is no tablespace in olddir on the source server.) Meanwhile newdir is a directory in the receiving host's filesystem. As with the main target directory, newdir need not exist already, but if it does exist it must be empty. Both olddir and newdir must be absolute paths. If either path needs to contain an equal sign ( = ), precede that with a backslash. This option can be specified multiple times for multiple tablespaces. If a tablespace is relocated in this way, the symbolic links inside the main data directory are updated to point to the new location. So the new data directory is ready to be used for a new server instance with all tablespaces in the updated locations. Currently, this option only works with plain output format; it is ignored if tar format is selected.",
       "names": [
         "-T olddir = newdir",
@@ -57,20 +65,22 @@
       "signature": "-z --gzip"
     },
     {
-      "description": "Enables gzip compression of tar file output, and specifies the compression level (0 through 9, 0 being no compression and 9 being best compression). Compression is only available when using the tar format, and the suffix .gz will automatically be added to all tar filenames.",
+      "description": "Requests compression of the backup. If client or server is included, it specifies where the compression is to be performed. Compressing on the server will reduce transfer bandwidth but will increase server CPU consumption. The default is client except when --target is used. In that case, the backup is not being sent to the client, so only server compression is sensible. When -Xstream , which is the default, is used, server-side compression will not be applied to the WAL. To compress the WAL, use client-side compression, or specify -Xfetch . The compression method can be set to gzip , lz4 , zstd , or none for no compression. A compression detail string can optionally be specified. If the detail string is an integer, it specifies the compression level. Otherwise, it should be a comma-separated list of items, each of the form keyword or keyword=value . Currently, the supported keywords are level and workers . If no compression level is specified, the default compression level will be used. If only a level is specified without mentioning an algorithm, gzip compression will be used if the level is greater than 0, and no compression will be used if the level is 0. When the tar format is used with gzip , lz4 , or zstd , the suffix .gz , .lz4 , or .zst , respectively, will be automatically added to all tar filenames. When the plain format is used, client-side compression may not be specified, but it is still possible to request server-side compression. If this is done, the server will compress the backup for transmission, and the client will decompress and extract it. When this option is used in combination with -Xstream , pg_wal.tar will be compressed using gzip if client-side gzip compression is selected, but will not be compressed if any other compression algorithm is selected, or if server-side compression is selected.",
       "names": [
         "-Z level",
-        "--compress= level"
-      ],
-      "signature": "-Z level --compress= level"
+        "-Z [{client|server}-] method [: detail ]",
+        "--compress= level",
+        "--compress=[{client|server}-] method [: detail ]"
+      ],
+      "signature": "-Z level -Z [{client|server}-] method [: detail ] --compress= level --compress=[{client|server}-] method [: detail ]"
     },
     {
       "description": "Sets checkpoint mode to fast (immediate) or spread (the default) (see Section 26.3.3 ).",
       "names": [
-        "-c fast|spread",
-        "--checkpoint= fast|spread"
-      ],
-      "signature": "-c fast|spread --checkpoint= fast|spread"
+        "-c {fast|spread}",
+        "--checkpoint={fast|spread}"
+      ],
+      "signature": "-c {fast|spread} --checkpoint={fast|spread}"
     },
     {
       "description": "Specifies that the replication slot named by the --slot option should be created before starting the backup. An error is raised if the slot already exists.",

比较已记录的接口与属性，排除来源指纹和构建元数据。某个样本中没有记录，不能据此判断实际引入或移除的版本。

快速链接

pg_basebackup

说明

用法

手册中的选项

手册定义

pg_basebackup

大纲

说明

选项

环境

注解

示例

另见

相关条目

文档与源码

版本比较

相关条目