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流(如果使用流)。

在同一时间可以有多个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_compresslog的工具以archive_command从 WAL 文件中移除全页写。

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

选项

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

-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 文件,并将连接设置附加到目标目录(或使用tar格式的基本存档文件中)的postgresql.auto.conf文件中。 这样可以简化使用备份结果设置备用服务器的过程。

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

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

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

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

目前,这个选项仅以普通输出格式工作,如果选择了tar格式,请忽略它。

--waldir=waldir

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

-X method
--wal-method=method

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

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

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
--compress=level

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

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

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

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

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

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

使用SHA散列函数可为希望验证备份是否遭到篡改的用户提供每个文件的加密安全摘要,而CRC32C算法提供的校验和计算速度更快。它擅长捕获由于意外更改引起的错误,但不能抵抗恶意修改。 请注意,为了对有权访问备份的对手有用,备份清单必须安全地存储在其他位置,否则必须经过验证以确保自从进行备份以来未进行任何修改。

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

--manifest-force-encode

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

--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并不连接到集簇中的任何特定数据库,连接字符串中的任何数据库名将被忽略。

-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(见第 34.15 节)支持的环境变量。

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

注解

在备份的开始时,需要在源服务器上执行检查点。这可能需要一点时间(尤其在没有使用选项--checkpoint=fast时),在此期间pg_basebackup看起来处于闲置状态。

备份将包括数据目录和表空间中的所有文件,包括配置文件以及由第三方放在该目录中的任何额外文件,不过由PostgreSQL管理的特定临时文件除外。但只有常规文件和目录会被拷贝,但用于表空间的符号链接会被保留。指向PostgreSQL已知的特定目录的符号链接被拷贝为空目录。其他符号链接和特殊设备文件会被跳过。准确的细节请参考第 53.4 节

在普通格式中,表空间将备份到源服务器上的相同路径,除非使用了--tablespace-mapping选项。如果没有这个选项并且表空间正在使用,在同一台服务器上进行普通格式的基础备份将无法工作,因为备份必须要写入到与原始表空间相同的目录位置。

在使用 tar 格式时,用户应负责在启动使用数据的 PostgreSQL 服务器前解压每一个 tar 文件。如果有额外的表空间,用于它们的 tar 文件需要被解压到正确的位置。在这种情况下,服务器将根据包含在base.tar文件中的tablespace_map文件的内容为那些表空间创建符号链接。

pg_basebackup可以和具有相同或较低主版本的服务器一起工作,最低是 9.1。但是,WAL 流模式(-X 流)只能和版本为 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

参见

pg_dump, 第 28.4.5 节