pg_basebackup

pg_basebackup — 获得一个PostgreSQL集簇的一个基础备份

大纲

pg_basebackup [option...]

描述

pg_basebackup被用于获得一个正在运行的PostgreSQL数据库集簇的基础备份。获得这些备份不会影响连接到该数据库的其他客户端,并且可以被用于时间点恢复(见第 25.3 节)以及用作一个日志传送或流复制后备服务器的开始点(见第 26.2 节)。

pg_basebackup建立数据库集簇文件的一份二进制副本,同时保证系统进入和退出备份模式。备份总是从整个数据库集簇获得,不可能备份单个数据库或数据库对象。关于个体数据库备份,必须使用一个像pg_dump的工具。

备份通过一个常规PostgreSQL连接制作,并且使用复制协议。该连接必须由一个超级用户或者一个具有REPLICATION权限(第 21.2 节)的用户建立,并且pg_hba.conf必须显式地允许该复制连接。该服务器还必须被配置,使max_wal_senders设置得足够高以留出至少一个会话用于备份以及一个用于WAL流(如果使用流)。

在同一时间可以有多个pg_basebackup运行,但是从性能的角度来说最好只做一个备份并且复制结果。

pg_basebackup不仅能从主控机也能从后备机创建一个基础备份。要从后备机获得一个备份,设置后备机让它能接受复制连接(也就是,设置max_wal_sendershot_standby,并且配置基于主机的认证)。你将也需要在主控机上启用full_page_writes

注意在来自后备机的在线备份中有一些限制:

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

  • 如果正在使用-X none,不保证备份所需的所有 WAL 文件在备份结束时被归档。

  • 如果在在线备份期间后备机被提升为主控机,备份会失败。

  • 备份所需的所有 WAL 记录必须包含足够的全页写,这要求你在主控机上启用full_page_writes并且不使用一个类似pg_compresslog的工具以archive_command从 WAL 文件中移除全页写。

选项

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

-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 千字节每秒到 1024 兆字节每秒之间。

其目标是限制在运行服务器上的pg_basebackup产生的影响。

这个选项总是会影响数据目录的传输。如果收集方法是fetch时,只有 WAL 文件受到影响。

-R
--write-recovery-conf

在输出目录中(或者当使用 tar 格式时再基础归档文件中)建立 standby.signal 并附加连接设置到postgresql.auto.conf 来简化设置一个后备服务器。 postgresql.auto.conf文件将记录连接设置(如果有)以及pg_basebackup所使用的复制槽,这样流复制后面就会使用相同的设置。

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

在备份期间将目录olddir中的表空间重定位到newdir中。为使之有效,olddir必须正好匹配表空间所在的路径(但如果备份中没有包含olddir中的表空间也不是错误)。olddirnewdir必须是绝对路径。如果一个路径凑巧包含了一个=符号,可用反斜线对它转义。对于多个表空间可以多次使用这个选项。例子见下文。

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

--waldir=waldir

指定用于预写式日志目录的位置。waldir必须是绝对路径。只有当备份是平面文件模式时才能指定事务日志目录。

-X method
--wal-method=method

在备份中包括所需的预写式日志文件(WAL文件)。这包括所有在备份期间产生的预写式日志。除非指定了方法none,可以直接在提取出的目录中启动postmaster而无需参考日志归档,所以这样得到的是一种完整的独立备份。

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

n
none

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

f
fetch

在备份末尾收集预写式日志文件。因此,有必要把wal_keep_segments参数设置得足够高,这样在备份末尾之前日志不会被移除。如果在要传输日志时它已经被轮转,备份将失败并且是不可用的。

如果使用tar格式,预写式日志文件将被写入到base.tar文件。

s
stream

在备份被创建时流传送预写式日志。这将开启一个到服务器的第二连接并且在运行备份时并行开始流传输预写式日志。因此,它将使用最多两个由max_wal_senders参数配置的连接。只要客户端能保持接收预写式日志,使用这种模式不需要在主控机上保存额外的预写式日志。

如果使用tar格式,预写式日志文件被写入到一个单独的名为pg_wal.tar的文件(如果服务器的版本超过10,该文件将被命名为pg_wal.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(默认)(见第 25.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 的总估计后增加。

当这个选项被启用时,备份开始时会列举整个数据库的尺寸,并且接着回头开始发送实际的内容。这可能使备份需要多花一点点时间,并且它在发送第一个数据之前花费的时间更长。

-S slotname
--slot=slotname

这个选项仅能与-X stream一起使用。它导致WAL流使用指定的复制槽。如果该基础备份的目的是被用作一台使用复制槽的流复制后备,则它应该使用与primary_slot_name中相同的复制槽名称。通过这种方式,可以确保服务器不会移除位于该基础备份结束与流复制开始之间产生的任何所需的WAL数据。

指定的复制槽必须已经存在,除非同时使用了选项-C

如果这个选项没有被指定并且服务器支持临时复制槽(版本10以后),则会自动使用一个临时复制槽来进行WAL流。

-v
--verbose

启用冗长模式。将在启动和关闭期间输出一些额外步骤,并且如果进度报告也被启用,还会显示当前正在被处理的确切文件名。

--no-slot

如果服务器支持临时复制槽,这个选项防止备份期间创建临时复制槽。

在使用日志流时,如果没有用选项-S指定槽名称,则默认会创建临时复制槽。

这个选项的主要目的是允许在服务器没有空闲复制槽可用时制作基础备份。使用复制槽几乎总是最好的方式,因为它能防止备份期间所需的WAL被删除。

--no-verify-checksums

如果在取基础备份的服务器上启用了校验码验证,则禁用校验码验证。

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

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

-d connstr
--dbname=connstr

以一个连接字符串的形式指定用于连接到服务器的参数。详见第 33.1.1 节

为了和其他客户端应用一致,该选项被称为--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(见第 33.14 节)支持的环境变量。

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

注解

在备份的开始时,需要向从中拿去备份的服务器写一个检查点。尤其在没有使用选项--checkpoint=fast时,这可能需要一点时间,在其间pg_basebackup看起来处于闲置状态。

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

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

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

pg_basebackup可以和具有相同或较低主版本的服务器一起工作,最低是 9.1。但是,WAL 流模式(-X 流)只能和版本为 9.3 及以上版本的服务器一起工作。当前版本的 tar 格式模式(--format=tar)只能用于版本 9.5 及以上的服务器。

如果在源集簇上启用了组权限,在plain以及tar模式中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