Docs4dev
Docs
postgre-sql / 10.7 / reference / app-pgbasebackup.html

pg_basebackup

pg_basebackup —对 PostgreSQL 集群进行基本备份

Synopsis

pg_basebackup [ option ...]

Description

pg_basebackup 用于对正在运行的 PostgreSQL 数据库集群进行基础备份。采取这些措施不会影响数据库的其他 Client 端，并且既可以用于时间点恢复(请参阅Section 25.3)，又可以用作日志传送或流复制备用服务器(请参阅Section 26.2)的起点。

pg_basebackup 制作数据库集群文件的二进制副本，同时确保系统自动进入和退出备份模式。总是对整个数据库集群进行备份；无法备份单个数据库或数据库对象。对于单个数据库备份，必须使用诸如pg_dump之类的工具。

备份是通过常规 PostgreSQL 连接进行的，并使用复制协议。必须与超级用户或具有REPLICATION权限的用户(请参阅Section 21.2)构建连接，并且pg_hba.conf必须明确允许复制连接。还必须将服务器的max_wal_senders设置得足够高，以使至少一个会话可用于备份，而另一个则用于 WAL 流传输(如果使用)。

可以同时运行多个pg_basebackup，但是从性能的角度来看，最好只备份一个并复制结果。

pg_basebackup 不仅可以从主数据库而且还可以从备用数据库进行基本备份。要从备用数据库中获取备份，请设置备用数据库，使其可以接受复制连接(即，设置max_wal_senders和hot_standby，并配置host-based authentication)。您还需要在主机上启用full_page_writes。

请注意，备用数据库的联机备份有一些限制：

  • 在备份的数据库群集中未创建备份历史记录文件。

  • 如果使用-X none，则不能保证备份所需的所有 WAL 文件都在备份结束时存档。

  • 如果在线备份期间将备用数据库提升为主数据库，则备份将失败。

  • 备份所需的所有 WAL 记录必须包含足够的整页写操作，这要求您在主服务器上启用full_page_writes，而不能使用 pg_compresslog 之类的工具archive_command从 WAL 文件中删除整页写操作。

Options

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

  • -D directory
    --pgdata=directory

    • 将输出写入的目录。 pg_basebackup 将创建目录和所有父目录(如果需要)。该目录可能已经存在，但是如果该目录已经存在并且不为空，则错误。

当备份处于 tar 模式并且目录指定为-(破折号)时，tar 文件将被写入stdout。

此选项是必需的。

  • -F format
    --format=format

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

  • p
    plain

    • 将输出写为纯文件，其布局与当前数据目录和表空间的布局相同。当集群没有其他表空间时，整个数据库将放置在目标目录中。如果集群包含其他表空间，则主数据目录将放置在目标目录中，而所有其他表空间将放置在与服务器上相同的绝对路径中。

这是默认格式。

  • t
    tar

    • 将输出作为 tar 文件写入目标目录中。主数据目录将被写入名为base.tar的文件，所有其他表空间将以表空间 OID 命名。

如果将值-(破折号)指定为目标目录，则 tar 内容将写入标准输出，适用于通过管道传输到例如 gzip。仅当群集没有其他表空间并且不使用 WAL 流时，才有可能这样做。

  • -r rate
    --max-rate=rate

    • 从服务器传输的数据的最大传输速率。值以每秒千字节为单位。使用后缀M表示每秒的兆字节。后缀k也被接受，并且不起作用。有效值介于每秒 32 KB 和每秒 1024 MB 之间。

目的是限制 pg_basebackup 对正在运行的服务器的影响。

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

  • -R
    --write-recovery-conf

    • 在输出目录(或使用 tar 格式的基本归档文件)中写入最少的recovery.conf，以轻松设置备用服务器。 recovery.conf文件将记录连接设置以及 pg_basebackup 使用的复制插槽(如果已指定)，以便流式复制稍后将使用相同的设置。

  • -S slotname
    --slot=slotname

    • 此选项只能与-X stream一起使用。这将导致 WAL 流使用指定的复制插槽。如果要将基本备份用作使用复制插槽的流复制备用数据库，则应在recovery.conf中使用相同的复制插槽名称。这样，可以确保服务器在基本备份结束到流复制开始之间没有删除任何必要的 WAL 数据。

如果未指定此选项，并且服务器支持临时复制插槽(版本 10 及更高版本)，则自动将临时复制插槽用于 WAL 流。

  • --no-slot

    • 即使服务器支持，此选项也可以防止在备份期间创建临时复制插槽。

如果在使用日志流时未使用选项-S指定插槽名称，则默认情况下会创建临时复制插槽。

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

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

    • 在备份过程中，将目录空间中的表空间olddir *重新定位到newdir 。为了有效， olddir *必须与当前定义的表空间的路径规范完全匹配。 (但是，如果备份中包含的olddir 中没有表空间，这不是错误.) olddir 和 newdir *都必须是绝对路径。如果路径恰好包含=符号，请使用反斜杠对其进行转义。可以为多个表空间多次指定此选项。请参见下面的示例。

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

  • --waldir=waldir

    • 指定预写日志目录的位置。 * waldir *必须是绝对路径。仅当备份处于纯模式时才能指定预写日志目录。

  • -X method
    --wal-method=method

    • 在备份中包括所需的预写日志文件(WAL 文件)。这将包括备份期间生成的所有预写日志。除非指定了方法none，否则可以直接在提取的目录中启动邮局主管，而无需查阅日志 Files，因此使之成为完全独立的备份。

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

  • n
    none

    • 备份中不要包括预写日志。

    • f
      fetch

      • 在备份结束时收集预写日志文件。因此，必须将wal_keep_segments参数设置得足够高，以便在备份结束之前不删除日志。如果在传输日志时已将其旋转，则备份将失败并且无法使用。

使用 tar 格式模式时，预写日志文件将被写入base.tar文件。

  • s
    stream

    • 创建备份时，流式传输预写日志。这将打开与服务器的第二个连接，并在运行备份时开始并行流式传输预写日志。因此，它将用完max_wal_senders参数配置的两个连接。只要 Client 端可以跟上收到的预写日志，使用此模式就不需要在主数据库上保存额外的预写日志。

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

此值为默认值。

  • -z
    --gzip

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

  • -Z level
    --compress=level

    • 启用 tar 文件输出的 gzip 压缩，并指定压缩级别(0 至 9，0 为无压缩，9 为最佳压缩)。压缩仅在使用 tar 格式时可用，后缀.gz将自动添加到所有 tar 文件名中。

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

  • -c fast|spread
    --checkpoint=fast|spread

    • 将检查点模式设置为快速(立即)或扩展(默认)(请参阅Section 25.3.3)。

  • -l label
    --label=label

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

  • -n
    --no-clean

    • 默认情况下，当pg_basebackup因错误中止时，它会在发现无法完成作业之前删除可能创建的所有目录(例如，数据目录和预写日志目录)。此选项禁止整理，因此对于调试很有用。

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

  • -P
    --progress

    • 启用进度报告。启用此选项将在备份期间提供大致的进度报告。由于数据库在备份过程中可能会更改，因此这只是一个近似值，可能不会以精确的100%结尾。特别是，当 WAL 日志包含在备份中时，无法预先估计数据总量，在这种情况下，一旦目标估计数超过了没有 WAL 的总估计量，估计的目标大小将增加。

启用此功能后，备份将从枚举整个数据库的大小开始，然后返回并发送实际内容。这可能会使备份花费的时间稍长一些，尤其是在发送第一个数据之前，备份将花费更长的时间。

  • -N
    --no-sync

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

  • -v
    --verbose

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

以下命令行选项控制数据库连接参数。

  • -d connstr
    --dbname=connstr

    • 指定用于连接到服务器的参数，作为连接字符串。有关更多信息，请参见Section 33.1.1。

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

  • -h host
    --host=host

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

  • -p port
    --port=port

    • 指定服务器正在侦听连接的 TCP 端口或本地 Unix 域套接字文件 extensions。默认值是PGPORT环境变量(如果已设置)或已编译的默认值。

  • -s interval
    --status-interval=interval

    • 指定状态包发送回服务器之间的秒数。这样可以更轻松地监视来自服务器的进度。零值将完全禁用定期状态更新，尽管在服务器请求时仍将发送更新，以避免超时断开连接。默认值为 10 秒。

  • -U username
    --username=username

    • 连接的用户名。

  • -w
    --no-password

    • 切勿发出密码提示。如果服务器要求密码验证，而其他方式(例如.pgpass文件)无法使用密码，则连接尝试将失败。该选项在没有用户 Importing 密码的批处理作业和脚本中很有用。

  • -W
    --password

    • 强制 pg_basebackup 在连接数据库之前提示 Importing 密码。

这个选项从来都不是必须的，因为如果服务器要求密码认证，pg_basebackup 会自动提示 Importing 密码。但是，pg_basebackup 会浪费连接尝试，以发现服务器需要密码。在某些情况下，值得 Importing-W以避免额外的连接尝试。

其他选项也可用：

  • -V
    --version

    • 打印 pg_basebackup 版本并退出。

  • -?
    --help

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

Environment

与大多数其他 PostgreSQLUtil 一样，该 Util 使用 libpq 支持的环境变量(请参见Section 33.14)。

Notes

在备份开始时，需要在获取备份的服务器上写入一个检查点。尤其是如果不使用选项--checkpoint=fast，这可能要花费一些时间，在此期间 pg_basebackup 似乎是空闲的。

备份将包括数据目录和表空间中的所有文件，包括配置文件以及由第三方放置在目录中的任何其他文件，但由 PostgreSQLManagement 的某些临时文件除外。但是只复制常规文件和目录，只保留用于表空间的符号链接。指向 PostgreSQL 已知的某些目录的符号链接被复制为空目录。其他符号链接和特殊设备文件将被跳过。有关详细信息，请参见Section 52.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 版或更高版本的服务器。

Examples

要在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

See Also

pg_dump