gs_probackup
背景信息
gs_probackup 是一个用于管理GBase 8c 数据库备份和恢复的工具。它对GBase 8c 实例
进行定期备份，以便在数据库出现故障时能够恢复服务器。
可用于备份单机数据库，也可对主机或者主节点数据库备机进行备份，为物理备份。
可备份外部目录的内容，如脚本文件、配置文件、日志文件、dump 文件等。
支持增量备份、定期备份和远程备份。
可设置备份的留存策略。
GBase 8c 管理员指南
南大通用数据技术股份有限公司
65
前提条件
可以正常连接GBase 8c 数据库。
若要使用PTRACK 增量备份，
需在postgresql.conf 中手动添加参数
“enable_cbm_tracking
= on”。
为了防止xlog 在传输结束前被清理，请适当调高postgresql.conf 文件中
wal_keep_segments 的值。
限制说明
备份必须由运行数据库服务器的用户执行。
备份和恢复的数据库服务器的主版本号必须相同。
如果要通过ssh 在远程模式下备份数据库，
需要在本地和远程主机安装相同主版本的数
据库，并通过ssh-copy-id remote_user@remote_host 命令设置本地主机备份用户和远程
主机数据库用户的无密码ssh 连接。
远程模式下只能执行add-instance、backup、restore 子命令。
使用restore 子命令前，应先停止gaussdb 进程。
当存在用户自定义表空间时，备份的时候要加上--external-dirs 参数，否则，该表空间
不会被备份。
当备份的规模比较大时，
为了防止备份过程中timeout 发生，
请适当调整postgresql.conf
文件的参数session_timeout、wal_sender_timeout。并且在备份的命令行参数中适当调
整参数--rw-timeout 的值。
恢复时，使用-T 选项把备份中的外部目录重定向到新目录时，请同时指定参数--
external-mapping。
增量备份恢复后，之前创建的逻辑复制槽不可用，需删除重建。
当使用远程备份时，请确保远程机器和备份机器的时钟同步，以防止使用--
recovery-target-time 恢复的场合,启动gaussdb 时有可能会失败。
GBase 8c 管理员指南
南大通用数据技术股份有限公司
66
当远程备份有效时(remote-proto=ssh)，请确保-h 和--remote-host 指定的是同一台机器。
当远程备份无效时，如果指定了-h 选项，请确保-h 指定的是本机地址或本机主机名。
当前暂不支持备份逻辑复制槽。
语法
gs_probackup 子命令帮助说明查询。
gs_probackup help [command]
gs_probackup 查看工具版本。
gs_probackup version
初始化备份路径backup-path 中的备份目录，该目录将存储已备份的内容。如果备份路
径backup-path 已存在，则backup-path 必须为空目录。
gs_probackup init -B backup-path [--help]
在备份路径backup-path 内初始化一个新的备份实例，并生成pg_probackup.conf 配置文
件，该文件保存了指定数据目录pgdata-path 的gs_probackup 设置。
gs_probackup add-instance -B backup-path -D pgdata-path
--instance=instance_name
[-E external-directories-paths]
[--remote-proto=protocol] [--remote-host=destination]
[--remote-path=path] [--remote-user=username]
[--remote-port=port] [--ssh-options=ssh_options]
[--remote-libpath=libpath]
[--help]
在备份路径backup-path 内删除指定实例相关的备份内容。
gs_probackup del-instance -B backup-path --instance=instance_name
[--help]
将指定的连接、压缩、日志等相关设置添加到pg_probackup.conf 配置文件中，或修改
已设置的值。不推荐手动编辑pg_probackup.conf 配置文件。
gs_probackup set-config -B backup-path --instance=instance_name
[-D pgdata-path] [-E external-directories-paths]
[--archive-timeout=timeout]
[--retention-redundancy=retention-redundancy]
GBase 8c 管理员指南
南大通用数据技术股份有限公司
67
[--retention-window=retention-window]
[--wal-depth=wal-depth]
[--compress-algorithm=compress-algorithm]
[--compress-level=compress-level]
[-d dbname] [-h host] [-p port] [-U username]
[--log-level-console=log-level-console]
[--log-level-file=log-level-file]
[--log-filename=log-filename]
[--error-log-filename=error-log-filename]
[--log-directory=log-directory]
[--log-rotation-size=log-rotation-size]
[--log-rotation-age=log-rotation-age]
[--remote-proto=protocol] [--remote-host=destination]
[--remote-path=path] [--remote-user=username]
[--remote-port=port] [--ssh-options=ssh_options]
[--remote-libpath=libpath]
[--help]
将备份相关设置添加到backup.control 配置文件中，或修改已设置的值。
gs_probackup set-backup -B backup-path --instance=instance_name -i backup-id
[--note=text] [pinning_options] [--help]
显示位于备份目录中的pg_probackup.conf 配置文件的内容。
可以通过指定-- format=json
选项，以json 格式显示。默认情况下，显示为纯文本格式。
gs_probackup show-config -B backup-path --instance=instance_name
[--format=plain|json] [--help]
显示备份目录的内容。如果指定了instance_name 和backup_id，
则显示该备份的详细信
息。可以通过指定--format=json 选项，以json 格式显示。默认情况下，备份目录的内容
显示为纯文本格式。
gs_probackup show -B backup-path [--instance=instance_name] [-i backup-id]
[--archive] [--format=plain|json] [--help]
创建指定实例的备份。
gs_probackup backup -B backup-path --instance=instance_name -b backup-mode
[-D pgdata-path] [-C] [-S slot-name] [--temp-slot]
[--backup-pg-log] [-j threads_num] [--progress]
[--no-validate] [--skip-block-validation]
[-E external-directories-paths]
GBase 8c 管理员指南
南大通用数据技术股份有限公司
68
[--no-sync] [--note=text]
[--archive-timeout=timeout]
[--log-level-console=log-level-console]
[--log-level-file=log-level-file]
[--log-filename=log-filename]
[--error-log-filename=error-log-filename]
[--log-directory=log-directory]
[--log-rotation-size=log-rotation-size]
[--log-rotation-age=log-rotation-age]
[--delete-expired] [--delete-wal] [--merge-expired]
[--retention-redundancy=retention-redundancy]
[--retention-window=retention-window]
[--wal-depth=wal-depth] [--dry-run]
[--compress-algorithm=compress-algorithm]
[--compress-level=compress-level]
[--compress]
[-d dbname] [-h host] [-p port] [-U username] [-w] [-W password]
[-t rwtimeout]
[--remote-proto=protocol] [--remote-host=destination]
[--remote-path=path] [--remote-user=username]
[--remote-port=port] [--ssh-options=ssh_options]
[--remote-libpath=libpath]
[--ttl=interval] [--expire-time=time]
[--help]
从备份目录backup-path 中的备份副本恢复指定实例。如果指定了恢复目标选项，
gs_probackup 将查找最近的备份并将其还原到指定的恢复目标。
否则，
使用最近一次备
份。
gs_probackup restore -B backup-path --instance=instance_name
[-D pgdata-path] [-i backup-id] [-j threads_num] [--progress]
[--force] [--no-sync] [--no-validate]
[--skip-block-validation]
[--external-mapping=OLDDIR=NEWDIR] [-T OLDDIR=NEWDIR]
[--skip-external-dirs] [-I incremental_mode]
[--recovery-target-time=time|--recovery-target-xid=xid
|--recovery-target-lsn=lsn|--recovery-target-name=target-name]
[--recovery-target-inclusive=boolean]
[--remote-proto=protocol] [--remote-host=destination]
[--remote-path=path] [--remote-user=username]
GBase 8c 管理员指南
南大通用数据技术股份有限公司
69
[--remote-port=port] [--ssh-options=ssh_options]
[--remote-libpath=libpath]
[--log-level-console=log-level-console]
[--log-level-file=log-level-file]
[--log-filename=log-filename]
[--error-log-filename=error-log-filename]
[--log-directory=log-directory]
[--log-rotation-size=log-rotation-size]
[--log-rotation-age=log-rotation-age]
[--help]
将指定的增量备份与其父完全备份之间的所有增量备份合并到父完全备份。
父完全备份
将接收所有合并的数据，而已合并的增量备份将作为冗余被删除。
gs_probackup merge -B backup-path --instance=instance_name -i backup-id
[-j threads_num] [--progress]
[--log-level-console=log-level-console]
[--log-level-file=log-level-file]
[--log-filename=log-filename]
[--error-log-filename=error-log-filename]
[--log-directory=log-directory]
[--log-rotation-size=log-rotation-size]
[--log-rotation-age=log-rotation-age]
[--help]
删除指定备份，或删除不满足当前保留策略的备份。
gs_probackup delete -B backup-path --instance=instance_name
[-i backup-id | --delete-expired | --merge-expired |
--status=backup_status]
[--delete-wal] [-j threads_num] [--progress]
[--retention-redundancy=retention-redundancy]
[--retention-window=retention-window]
[--wal-depth=wal-depth] [--dry-run]
[--log-level-console=log-level-console]
[--log-level-file=log-level-file]
[--log-filename=log-filename]
[--error-log-filename=error-log-filename]
[--log-directory=log-directory]
[--log-rotation-size=log-rotation-size]
[--log-rotation-age=log-rotation-age]
[--help]
GBase 8c 管理员指南
南大通用数据技术股份有限公司
70
验证恢复数据库所需的所有文件是否存在且未损坏。如果未指定instance_name，
gs_probackup 将验证备份目录中的所有可用备份。如果指定instance_name 而不指定任
何附加选项，gs_probackup 将验证此备份实例的所有可用备份。如果指定了
instance_name 并且指定backup-id 或恢复目标相关选项，gs_probackup 将检查是否可
以使用这些选项恢复数据库。
gs_probackup validate -B backup-path
[--instance=instance_name] [-i backup-id]
[-j threads-num] [--progress] [--skip-block-validation]
[--recovery-target-time=time|--recovery-target-xid=xid
|--recovery-target-lsn=lsn|--recovery-target-name=target-name]
[--recovery-target-inclusive=boolean]
[--log-level-console=log-level-console]
[--log-level-file=log-level-file]
[--log-filename=log-filename]
[--error-log-filename=error-log-filename]
[--log-directory=log-directory]
[--log-rotation-size=log-rotation-size]
[--log-rotation-age=log-rotation-age]
[--help]
参数说明
通用参数
command ：
gs_probackup 除version 和help 以外的子命令：
init、
add-instance、
del- instance、
set-config、set-backup、show-config、show、backup、restore、merge、delete、validate。
-?, --help ：显示gs_probackup 命令行参数的帮助信息，然后退出。子命令中只能使用
--help，不能使用-?。
-V, --version ：打印gs_probackup 版本，然后退出。
-B backup-path, --backup-path=backup-path
：备份的路径。系统环境变量：
$BACKUP_PATH
-D pgdata-path, --pgdata=pgdata-path ：数据目录的路径。系统环境变量：$PGDATA
GBase 8c 管理员指南
南大通用数据技术股份有限公司
71
--instance=instance_name ：实例名。
恢复相关参数
-I, --incremental-mode=none|checksum|lsn ：
若PGDATA 中可用的有效页没有修改，
则重
新使用它们。默认值：none
--external-mapping=OLDDIR=NEWDIR ：在恢复时，将包含在备份中的外部目录从
OLDDIR 重新定位到NEWDIR 目录。OLDDIR 和NEWDIR 都必须是绝对路径。如果
路径中包含“=”，则使用反斜杠转义。此选项可为多个目录多次指定。
-TOLDDIR=NEWDIR, --tablespace-mapping=OLDDIR=NEWDIR ：在恢复时，将表
空间从OLDDIR 重新定位到NEWDIR 目录。
OLDDIR 和NEWDIR 必须都是绝对路径。
如果路径中包含“=”，则使用反斜杠转义。多个表空间可以多次指定此选项。此选项
必须和--external-mapping 一起使用。
--skip-external-dirs ：跳过备份中包含的使用--external-dirs 选项指定的外部目录。这些
目录的内容将不会被恢复。
--skip-block-validation ：
跳过块级校验，
以加快验证速度。
在恢复之前的自动验证期间，
将仅做文件级别的校验。
--no-validate ：跳过备份验证。
--force ：允许忽略备份的无效状态。如果出于某种原因需要从损坏的或无效的备份中
恢复数据，可以使用此标志。请谨慎使用。
恢复目标相关参数(recovery_options)
当前不支持配置连续的WAL 归档的PITR，因而使用这些参数会有一定限制，具体如
下描述。
如果需要使用持续归档的WAL 日志进行PITR 恢复，
请按照下面描述的步骤：
1.
将物理备份的文件替换目标数据库目录。
2.
删除数据库目录下pg_xlog/中的所有文件。
GBase 8c 管理员指南
南大通用数据技术股份有限公司
72
3.
将归档的WAL日志文件复制到pg_xlog文件中（此步骤可以省略，通过配置
recovery.conf恢复命令文件中的restore_command项替代）。
4.
在数据库目录下创建恢复命令文件recovery.conf，指定数据库恢复的程度。
5.
启动数据库。
6.
连接数据库，查看是否恢复到希望预期的状态。若已经恢复到预期状态，通过
pg_xlog_replay_resume()指令使主节点对外提供服务。
--recovery-target-lsn=lsn ：指定要恢复到的lsn，当前只能指定备份的stop lsn。
--recovery-target-name=target-name ：指定要将数据恢复到的已命名的保存点，保存点
可以通过查看备份中recovery- name 字段得到。
--recovery-target-time=time ：指定要恢复到的时间，当前只能指定备份中的
recovery-time。
--recovery-target-xid=xid ：指定要恢复到的事务ID ，当前只能指定备份中的
recovery-xid。
--recovery-target-inclusive=boolean ：当该参数指定为true 时，恢复目标将包括指定的
内容。当该参数指定为false 时，恢复目标将不包括指定的内容。该参数必须和
--recovery-target-name、
--recovery-target-time、
--recovery- target-lsn 或--recovery-target-xid
一起使用。
留存相关参数(retention_options)
可以和backup 和delete 命令一起使用这些参数。
--retention-redundancy=retention-redundancy ：指定在数据目录中留存的完整备份数。
必须为正整数。0 表示禁用此设置。默认值：0
--retention-window=retention-window ：
指定留存的天数。
必须为正整数。
0 表示禁用此
设置。默认值：0
GBase 8c 管理员指南
南大通用数据技术股份有限公司
73
--wal-depth=wal-depth ：每个时间轴上必须留存的执行PITR 能力的最新有效备份数。
必须为正整数。0 表示禁用此设置。默认值：0
--delete-wal ：从任何现有的备份中删除不需要的WAL 文件。
--delete-expired ：删除不符合pg_probackup.conf 配置文件中定义的留存策略的备份。
--merge-expired ：将满足留存策略要求的最旧的增量备份与其已过期的父备份合并。
--dry-run ：显示所有可用备份的当前状态，不删除或合并过期备份。
固定备份相关参数(pinning_options)
如果要将某些备份从已建立的留存策略中排除，可以和backup 和set-backup 命令一起
使用这些参数。
--ttl=interval ：指定从恢复时间开始计算，备份要固定的时间量。必须为正整数。0 表
示取消备份固定。支持的单位：ms, s, min, h, d（默认为s）。例如：--ttl=30d。
--expire-time=time ：指定备份固定失效的时间戳。必须是ISO-8601 标准的时间戳。例
如：--expire-time='2020-01-01 00:00:00+03'
日志相关参数(logging_options)
日志级别：verbose、log、info、warning、error 和off。
--log-level-console=log-level-console ：
设置要发送到控制台的日志级别。
每个级别都包
含其后的所有级别。级别越高，发送的消息越少。指定off 级别表示禁用控制台日志记
录。默认值：info
--log-level-file=log-level-file ：设置要发送到日志文件的日志级别。每个级别都包含其
后的所有级别。级别越高，发送的消息越少。指定off 级别表示禁用日志文件记录。默
认值：off
--log-filename=log-filename ：
指定要创建的日志文件的文件名。
文件名可以使用strftime
模式，因此可以使用%-escapes 指定随时间变化的文件名。
GBase 8c 管理员指南
南大通用数据技术股份有限公司
74
例如，如果指定了“pg_probackup-%u.log”模式，则pg_probackup 为每周的每一天生成
单独的日志文件，其中%u 替换为相应的十进制数字，即pg_probackup-1.log 表示星期
一；pg_probackup-2.log 表示星期二，以此类推。
如果指定了--log-level-file 参数启用日志文件记录，则该参数有效。默认值：
“pg_probackup.log”
--error-log-filename=error-log-filename ：指定仅用于error 日志的日志文件名。指定方
式与--log-filename 参数相同。此参数用于故障排除和监视。
--log-directory=log-directory ：指定创建日志文件的目录。必须是绝对路径。此目录会
在写入第一条日志时创建。默认值：$BACKUP_PATH/log
--log-rotation-size=log-rotation-size ：指定单个日志文件的最大大小。如果达到此值，
则启动gs_probackup 命令后，日志文件将循环，但help 和version 命令除外。0 表示禁
用基于文件大小的循环。支持的单位：KB、MB、GB、TB（默认为KB）。默认值：0
--log-rotation-age=log-rotation-age ：单个日志文件的最大生命周期。如果达到此值，则
启动gs_probackup 命令后，日志文件将循环，但help 和version 命令除外。
$BACKUP_PATH/log/log_rotation 目录下保存最后一次创建日志文件的时间。0 表示禁
用基于时间的循环。支持的单位：ms, s, min, h, d（默认为min）。默认值：0
连接相关参数(connection_options)
可以和backup 命令一起使用这些参数。
-d dbname, --pgdatabase=dbname ：指定要连接的数据库名称。该连接仅用于管理备份
进程，因此您可以连接到任何现有的数据库。如果命令行、PGDATABASE 环境变量或
pg_probackup.conf 配置文件中没有指定此参数，则gs_probackup 会尝试从PGUSER 环
境变量中获取该值。如果未设置PGUSER 变量，
则从当前用户名获取。
系统环境变量：
$PGDATABASE。
-h hostname, --pghost=hostname ：
指定运行服务器的系统的主机名。
如果该值以斜杠开
GBase 8c 管理员指南
南大通用数据技术股份有限公司
75
头，
则被用作到Unix 域套接字的路径。
系统环境变量：
$PGHOST。
默认值：
local socket
-p port, --pgport=port ：指定服务器正在侦听连接的TCP 端口或本地Unix 域套接字文
件扩展名。系统环境变量：$PGPORT。默认值：5432
-U username, --pguser=username ：
指定所连接主机的用户名。
系统环境变量：
$PGUSER
-w, --no-password ：不出现输入密码提示。如果主机要求密码认证并且密码没有通过其
它形式给出，
则连接尝试将会失败。
该选项在批量工作和不存在用户输入密码的脚本中
很有帮助。
-W password, --password=password ：指定用户连接的密码。如果主机的认证策略是
trust，则不会对系统管理员进行密码验证，即无需输入-W 选项；如果没有-W 选项，并
且不是系统管理员，则会提示用户输入密码。
压缩相关参数(compression_options)
可以和backup 命令一起使用这些参数。
--compress-algorithm=compress-algorithm ：指定用于压缩数据文件的算法。取值包括
zlib、pglz 和none。如果设置为zlib 或pglz，此选项将启用压缩。默认情况下，压缩功
能处于关闭状态。默认值：none
--compress-level=compress-level ：指定压缩级别。取值范围：0~9。0 表示无压缩。1
表示压缩比最小，处理速度最快。9 表示压缩比最大，处理速度最慢。可与
--compress-algorithm 选项一起使用。默认值：1。
--compress ：以--compress-algorithm=zlib 和--compress-level=1 进行压缩。
远程模式相关参数(remote_options)
通过SSH 远程运行gs_probackup 操作的相关参数。可以和add-instance、set-config、
backup、restore 命令一起使用这些参数。
GBase 8c 管理员指南
南大通用数据技术股份有限公司
76
--remote-proto=protocol ：
指定用于远程操作的协议。
目前只支持SSH 协议。
取值包括：
ssh：通过SSH 启用远程备份模式。这是默认值。
none：显式禁用远程模式。如果指定了--remote-host 参数，可以省略此参数。
--remote-host=destination ：指定要连接的远程主机的IP 地址或主机名。
--remote-port=port ：指定要连接的远程主机的端口号。默认值：22
--remote-user=username ：指定SSH 连接的远程主机用户。如果省略此参数，则使用当
前发起SSH 连接的用户。默认值：当前用户
--remote-path=path ：指定gs_probackup 在远程系统的安装目录。默认值：当前路径
--remote-libpath=libpath ：指定gs_probackup 在远程系统安装的lib 库目录。
--ssh-options=ssh_options ：指定SSH 命令行参数的字符串。例如：
--ssh-options='-c cipher_spec -F configfile'
如果因为网络临时故障等原因导致server 端无应答,gs_probackup 将在等待archive-
timeout（默认300 秒）后退出。如果备机lsn 与主机有差别时，数据库会不停地刷以下
log 信息，此时应重新build 备机。
LOG: walsender thread shut down LOG: walsender thread started
LOG: received wal replication command: IDENTIFY_VERSION LOG: received wal
replication command: IDENTIFY_MODE LOG: received wal replication command:
IDENTIFY_SYSTEM
LOG: received wal replication command: IDENTIFY_CONSISTENCE 0/D0002D8 LOG:
remote request lsn/crc: [xxxxx] local max lsn/crc: [xxxxx]
备份流程
步骤1 初始化备份目录。
在指定的目录下创建backups/和wal/子目录，
分别用于存放备
份文件和WAL 文件。
gs_probackup init -B backup_dir
步骤2 添加一个新的备份实例。gs_probackup 可以在同一个备份目录下存放多个数据
GBase 8c 管理员指南
南大通用数据技术股份有限公司
77
库实例的备份。
gs_probackup add-instance -B backup_dir -D data_dir --instance instance_name
步骤3 创建指定实例的备份。在进行增量备份之前，必须至少创建一次全量备份。
gs_probackup backup -B backup_dir --instance instance_name -b backup_mode
步骤4 从指定实例的备份中恢复数据。
gs_probackup restore -B backup_dir --instance instance_name -D pgdata-path -i
backup_id
故障处理
故障问题及其原因和解决方案，参见表5-3。
表5-3 故障处理
问题描述
原因和解决方案
ERROR: query failed: ERROR: canceling
statement
due
to
conflict
with
recovery
（错误：查询失败：由于与恢复操作冲突，
正在取消语句命令）
原因：
在备机上执行的操作正在访问存储行，
主机上更改或者删除了对应的行，
并将xlog
在备机上重放，迫使备机上操作取消。
解决方案：
1. 适当增加如下配置参数的值
max_standby_archive_delay
max_standby_streaming_delay
2. 增加如下配置
hot_standby_feedback = on