PostgreSQL / 系统课时

使用 pg_basebackup 初始化备库

使用 pg_basebackup 初始化备库

本课把一台空节点初始化为 PostgreSQL 物理流复制备库:先确认主备主版本与复制连接条件,再用 pg_basebackup 获取一致的基础备份,最后检查 -R 生成的待机标记和连接配置。重点是分清“基础备份完成”和“流复制已经建立”这两个状态。

学习目标

  • 使用 pg_basebackup 创建可启动为物理备库的数据目录
  • 理解 -X stream、-R 与基础备份一致性的职责边界
  • 验证 standby.signal 和 primary_conninfo,避免把备份成功误判为复制健康

初始化前检查

物理流复制要求主库与最终启动备库的 PostgreSQL 服务端使用同一主版本。补丁版本可以不同,但生产环境通常应保持在兼容且受支持的补丁水平。目标 PGDATA 必须为空;已有数据或表空间目录不能直接覆盖。

先检查主库可达性,并分别查看主库版本、备库服务端版本和本机 pg_basebackup 版本。示例同时准备密码文件:普通 SQL 连接匹配 postgres 数据库,物理复制连接匹配特殊的 replication 项。<IP>、<PORT>、<PATH>、<PASSWORD> 和 <VERSION> 都应替换为环境实际值。

bash
export PRIMARY_HOST="<IP>"
export PRIMARY_PORT="<PORT>"
export REPL_USER="replicator"
export PASSFILE="<PATH>"

umask 077
cat > "${PASSFILE}" <<EOF
${PRIMARY_HOST}:${PRIMARY_PORT}:postgres:${REPL_USER}:<PASSWORD>
${PRIMARY_HOST}:${PRIMARY_PORT}:replication:${REPL_USER}:<PASSWORD>
EOF
sudo chown postgres:postgres "${PASSFILE}"

pg_isready -h "${PRIMARY_HOST}" -p "${PRIMARY_PORT}"
PGPASSFILE="${PASSFILE}" psql \
  "host=${PRIMARY_HOST} port=${PRIMARY_PORT} dbname=postgres user=${REPL_USER}" \
  -Atc "SHOW server_version;"
postgres --version
pg_basebackup --version

预期输出

text
<IP>:<PORT> - accepting connections
<VERSION>
postgres (PostgreSQL) <VERSION>
pg_basebackup (PostgreSQL) <VERSION>

比较版本时关注主版本是否一致,不要要求三个 <VERSION> 的补丁号完全相同。若复制角色的 pg_hba.conf 规则只允许 replication 连接,版本查询应改用已有巡检账号,而不是为了检查版本额外放宽复制角色权限。

执行基础备份

在备库创建空目录,并以 PostgreSQL 服务账号运行一个主示例。-D 指定目标目录,-F p 使用普通目录格式,-X stream 在备份期间通过额外的复制连接持续接收所需 WAL,-P 显示进度,-R 只负责把结果准备成可进入 standby 模式的目录。

bash
export PGDATA="<PATH>"

sudo install -d -m 700 -o postgres -g postgres "${PGDATA}"

sudo -u postgres pg_basebackup \
  -d "host=${PRIMARY_HOST} port=${PRIMARY_PORT} user=${REPL_USER} passfile=${PASSFILE}" \
  -D "${PGDATA}" \
  -F p \
  -X stream \
  -P \
  -R

printf 'exit_code=%s\n' "$?"

预期输出

text
<VALUE>/<VALUE> kB (100%), <VALUE>/<VALUE> tablespace
exit_code=0

进度数字取决于数据量和表空间数量。基础备份不是普通文件复制:PostgreSQL 会协调备份起止过程,而 -X stream 会在备份期间接收使该备份能够一致恢复所需的 WAL。备份完成后若长时间不启动备库,还要依赖足够的 WAL 保留、归档或复制槽,避免后续追赶所需 WAL 被回收。

pg_basebackup 从主库生成备库数据目录并写入启动连接配置的链路

理解 -R 的边界

-R 不会启动 PostgreSQL,也不会证明 WAL receiver 已连接主库。它会在目标数据目录创建 standby.signal,并把连接信息写入 postgresql.auto.conf 的 primary_conninfo;如果备份命令显式使用了复制槽,相应槽配置也会被记录。

只有之后真正启动备库,PostgreSQL 才会看到 standby.signal、进入待机恢复流程,并依据 primary_conninfo 尝试连接上游。因此,本课应把状态分成两步:初始化完成表示目录与恢复连接配置已准备好;复制建立必须等启动后再检查 WAL receiver、主库 WAL sender 以及接收和回放 LSN。

验证初始化结果

现在只验证 pg_basebackup -R 应负责的产物,不提前把启动后的复制状态算作本课成功条件。

bash
sudo -u postgres test -f "${PGDATA}/standby.signal" \
  && echo "standby.signal: OK"

sudo -u postgres grep -E '^primary_conninfo[[:space:]]*=' \
  "${PGDATA}/postgresql.auto.conf"

预期输出

text
standby.signal: OK
primary_conninfo = '<VALUE>'

<VALUE> 中应能识别本次使用的主库地址、端口、复制用户和 passfile 等连接参数。密码文件必须持续对 PostgreSQL 服务账号可读;不要为了方便把密码直接写进课程脚本或公开配置。

初始化失败时怎么定位

目标目录非空时,先确认它确实是可丢弃的初始化目录,再清空或换新目录。出现认证失败或 no pg_hba.conf entry 时,检查主库是否允许该来源地址以复制角色建立物理复制连接;使用 -X stream 时还要确保主库有足够可用的 WAL sender 连接。

若备份成功但备库随后因缺失 WAL 无法继续恢复,不要重新解释为“-R 失效”。应检查备份完成到备库启动之间的 WAL 保留窗口、归档可用性或复制槽设计。本课的完成标志只有三个:基础备份命令成功、standby.signal 存在、primary_conninfo 可用;复制链路健康需要在启动后另行验收。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 pg_basebackup 初始化备库

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通