Databasus 复制凭据规格：PostgreSQL 物理备份的 WAL 轮转权限与 PITR 前条件解析

数据库灾备【免费下载链接】databasusPostgreSQL backup tool with Point-In-Time-Recovery and restore verification项目地址https://gitcode.com/gh_mirrors/po/databasus点击查看免费下载导读本文围绕 Databasus 开源仓库中的复制凭据规格文档展开讲解 Databasus 在 PostgreSQL 物理备份场景下如何管理复制用户权限Databasus 供应的复制用户拥有哪些能力、平台在何种条件下才接受可恢复到任意时间点Point-In-Time-RecoveryPITR的物理备份配置、以及哪些备份类型不受此约束。读完本文你将理解pg_switch_wal()权限在连续 WAL 流式备份中的决定性作用掌握 Databasus 供应复制用户时的最小权限策略并能在自管理集群与托管平台上正确判断与排查复制凭据问题。背景为什么复制用户需要 WAL 轮转权限PostgreSQL 的物理备份遵循两条互补的数据通道一是由pg_basebackup生成的基础全量备份二是由pg_receivewal持续从源集群拉取的 WAL 段Write-Ahead Log。要恢复到一个备份完成之后的任意时间点Databasus 必须重放备份结束点之后的归档 WAL 段。而 WAL 段只有在源集群关闭switch当前段之后才会成为可归档、可上传的完整文件。这里存在一个关键的时间缝隙如果一个数据库写入频率极低当前 WAL 段可能需要数小时甚至数天才能写满。在这段时间里最新 WAL 一直停留在源集群本地磁盘上恢复点recovery point无法越过当前段。要让恢复点按可控节奏前进唯一办法就是主动触发 WAL 段切换——在 PostgreSQL 中即调用pg_switch_wal()函数。Databasus 将这一需求形式化为规格中的明确要求凡是承诺 PITR 的连续 WAL 流式配置其凭据必须能够强制 WAL 段轮转而仅做全量/增量备份、不重放归档 WAL 的备份类型则不受此约束。规格要求一Databasus 供应的复制用户必须能强制 WAL 轮转在平台允许的前提下规格原文规定当 Databasus 在源集群上供应复制用户时它SHALL同时赋予该用户强制 WAL 段切换的能力使低写入数据库的恢复点由轮转间隔限定而不是被当前段写满所需的时间拖住。如果连接的管理员无法授予该能力供应SHALL仍然成功并交付一个可用的复制用户同时报告强制 WAL 轮转对该凭据不可用。对应源码在 backend/internal/features/databases/databases/postgresql/physical/forced_wal_rotation.go其中两个核心函数完整实现了这一规格// 读取权限而不是调用 pg_switch_wal()使检查在每次连接测试中都是安全的 // 一次成功的调用会归档一个被填充的 WAL 段。 func canForceWalRotation(ctx context.Context, querier pgRowQuerier, roleName string) (bool, error) { var canExecute bool if err : querier.QueryRow( ctx, SELECT has_function_privilege($1, pg_switch_wal(), EXECUTE), roleName, ).Scan(canExecute); err ! nil { return false, fmt.Errorf(failed to check pg_switch_wal privilege: %w, err) } return canExecute, nil }值得注意的细节是探测权限用的是has_function_privilege(... pg_switch_wal(), EXECUTE)查询系统目录而不是实际调用pg_switch_wal()。这是因为一次成功调用会把一个填充padded的 WAL 段归档若在每次连接测试中都这么做会产生无谓的段而读取目录则没有任何副作用。规格的边界受轮转间隔限定由 backend/internal/features/backups/backups/usecases/physical/postgresql/wal_rotation.go 中的常量落地// 只有已定稿的段才会被上传因此一小时只写几个字节的数据库 // 会把最新 WAL 一直留在本地直到段写满——恢复点被单块磁盘拖住数小时或数天。 // 按此节奏强制轮转可以约束这一点代价是源被写入期间每个间隔一个近乎空的段。 const DefaultForcedRotationInterval 5 * time.Minute也就是说Databasus 默认每 5 分钟检查一次当前 WAL 位置pg_current_wal_lsn()若自上次轮转以来有新写入且间隔已到就执行pg_switch_wal()。轮转追踪器walRotationTracker通过记录轮转后的 LSN来避免对空转源重复轮转——pg_switch_wal()会把插入点推进到新段若不把该推进视为已轮转位置空转数据库也会每间隔轮转一次。两种场景的判定规格用两个场景界定了平台允许的含义自管理集群且管理员可授予权限管理员请求 Databasus 创建复制用户且连接的管理员能够授予该能力——则创建出的用户既能强制 WAL 段切换其凭据也能用于 WAL 流式备份配置。托管平台拒绝授予该能力同一请求打到无法授予该权限的托管平台——复制用户仍被创建并可用于物理备份但结果会报告强制 WAL 轮转不可用。对应实现位于 backend/internal/features/databases/databases/postgresql/physical/model.go 的CreateReplicationOnlyUser。它先检测平台类型自管理/RDS/Azure/GCP/未知托管再在单个事务内依次执行CREATE USER→ 授予复制权限 →尝试授予pg_switch_wal()的 EXECUTE。授予动作被包在保存点savepoint里因为被拒绝的语句否则会中止创建角色的事务。// 拒绝授予该能力的源不能用于连续 WAL 流式备份 // 但它仍然可以服务 FULL 和增量备份因此拒绝是一种结果而非失败。 // GRANT 运行在保存点内因为被拒绝的语句会中止创建角色的事务。 func grantWalSwitchIfPermitted(ctx context.Context, tx pgx.Tx, username string) (isGranted bool, err error) { savepoint, err : tx.Begin(ctx) // ... _, err savepoint.Exec(ctx, fmt.Sprintf(GRANT EXECUTE ON FUNCTION pg_switch_wal() TO %s, quotedUsername)) if err ! nil { if rollbackErr : savepoint.Rollback(ctx); rollbackErr ! nil { /* ... */ } var pgErr *pgconn.PgError if errors.As(err, pgErr) pgErr.Code pgErrorCodeInsufficientPrivilege { return false, nil // 42501被拒是结果不是失败 } // ... } // 最终以目录而非语句退出状态为准使供应与连接测试对同一角色不会分歧 return canForceWalRotation(ctx, tx, username) }最终返回结构体ReplicationOnlyUser携带IsForcedWalRotationAvailable字段true 或 false把凭据可用与强制轮转是否可用分开上报正是规格要求的供应仍成功 报告不可用。规格要求二供应只拓宽一个能力——最小权限边界规格对权限边界给出硬性约束供应SHALL只授予强制 WAL 段切换这一项能力除此之外什么都不加。供应出的角色SHALL保持仅限复制无数据读取、无创建角色/数据库的能力、不属于任何管理员角色。该能力SHALL只授予被供应的角色本身绝不可授予会外溢到集群其他角色的组若源拒绝集群权限必须保持原样不得授予任何更弱或更宽泛的替代权限。从源码看这份最小权限承诺体现在两个层面授予动作是单项且尽力而为的grantWalSwitchIfPermitted只执行一条GRANT EXECUTE ON FUNCTION pg_switch_wal()不存在 fallback 到SUPERUSER或某个宽泛管理角色的分支。遇到42501权限不足时直接返回false不做任何替代授予与规格无更弱或更宽泛的替代特权完全一致。Databasus 还会主动检查过度的权限ShouldSuggestReplicationOnlyUsermodel.go会在接入的凭据上检查SUPERUSER、CREATEROLE、CREATEDB、BYPASSRLS、云管理员角色成员关系rds_superuser、azure_pg_admin、cloudsqlsuperuser、表级写权限、schema 上的 CREATE、以及 SECURITY DEFINER 函数的 EXECUTE——任一命中都会建议改用仅复制用户确保实际使用的凭据不越界。三个场景的判定即由此实现授予成功后的角色边界角色能流式 WAL、能强制段切换但仍不能读表数据、不能建角色/库、不能当管理员。无其他角色获益由于授予目标被pgx.Identifier{username}.Sanitize()严格限定为新建的单个用户且不使用组角色集群内其他角色不会获得该能力。源拒绝时保存点回滚只撤销那次 GRANT创建用户之外没有任何权限被改动。规格要求三拒绝无法界定恢复点的流式配置这是整个规格的入口校验核心。其推理链条是任意时间点恢复需要重放已到达存储的 WAL 段而段只有在源关闭它之后才会到达存储。因此当用户配置连续 WAL 流式备份时DatabasusSHALL拒绝该配置除非提供的凭据能强制 WAL 段切换。拒绝信息必须同时给出两条出路在源上授予该能力或选择不重放归档 WAL 的备份类型。规格特别强调不得引导用户去开启源上的归档archiving——那会让集群把每个段保留到归档器确认等于用集群的无限保留换取恢复点不是正确的解法。拒绝方式必须与其他物理源的前置条件检查一致使用户在同一时刻一并解决。此逻辑在 model.go 的checkReplicationReadiness中实现// 连续流式备份承诺备份之间的恢复点而只有已定稿的段才会被上传。 // 没有 pg_switch_wal 时安静的源会把最新 WAL 留在本地直到段写满承诺无法兑现。 if p.BackupType.IsWalStreaming() { canRotate, err : canForceWalRotation(ctx, conn, p.Username) if err ! nil { return err } if !canRotate { quotedUsername : pgx.Identifier{p.Username}.Sanitize() return postgresql_shared.ConnectionTestError{ Code: postgresql_shared.ConnErrNoWalSwitchPrivilege, Message: fmt.Sprintf( user %s cannot force a WAL segment switch, so the recovery point between backups would advance only as segments fill. Run GRANT EXECUTE ON FUNCTION pg_switch_wal() TO %s on the source, or choose a backup type that does not replay archived WAL, quotedUsername, quotedUsername, ), } } }错误码ConnErrNoWalSwitchPrivilegeno_wal_switch_privilege定义于 backend/internal/features/databases/databases/postgresql/shared/connection_error.go错误消息同时点名授予 EXECUTE与改选不重放归档 WAL 的备份类型两条出路正是规格要求的双向指引且不提及任何归档开关符合不得引导开启 archiving的约束。该检查与同函数内的其他前置条件wal_level必须是replica/logical、max_wal_senders、max_replication_slots、PG17 下增量/流式所需summarize_walon、自定义表空间禁止等并列执行因此用户在连接测试这一环节就会在同一条错误流里看到所有不满足项。规格对适用范围做了三点明确源码也一一对应手工输入的凭据与 Databasus 供应的凭据一视同仁检查基于p.Username对目录做has_function_privilege探测与凭据来源无关被拒的托管平台同样返回no_wal_switch_privilege并在消息中说明该源上连续 WAL 流式不可用而非建议会让集群无限保留 WAL 的源设置。新建与修改一视同仁checkReplicationReadiness同时被创建与更新路径调用controller_test.go中ConnErrNoWalSwitchPrivilege出现在两处测试L2460、L2543覆盖了修改已保存的流式数据库场景。拒绝不停止既有备份规格注明修改被拒时该数据库已在运行的备份不会因拒绝而停止——配置校验与运行中的备份任务彼此解耦。运行时兜底轮转被拒时的降级除了配置校验规格精神还延伸到运行时。runForcedWalRotationwal_rotation.go中流式监督器在轮转被拒权限不足时报告breakReasonRotationDenied并停止轮转循环而不是无限重试if err ! nil { if !isInsufficientPrivilegeError(err) { logger.WarnContext(ctx, forced wal rotation failed; will retry, error, err) continue } logger.WarnContext(ctx, source refuses pg_switch_wal; forced wal rotation disabled for this streamer, error, err) s.reportChainAtRisk(logger, breakReasonRotationDenied, nil) return }注释点明设计意图轮转是尽力而为的pg_switch_wal默认仅超级用户可调用除非授予 EXECUTE而物理备份只要求 REPLICATION。拒绝是永久性的因此循环报告一次即停止而非无限轮询。这正是规格托管平台拒绝后如实上报、不虚构能力的运行时镜像。规格要求四不重放归档 WAL 的备份类型不受此约束最后一条规格划清了豁免边界只恢复到备份本身完成点的备份类型不会读取归档段因此SHALL NOT被要求具备强制段切换能力。DatabasusSHALL接受仅能流式复制streaming的凭据配置此类备份。对应枚举定义于 backend/internal/features/databases/databases/postgresql/physical/enums.goconst ( BackupTypeFullOnly BackupType FULL BackupTypeFullAndIncremental BackupType FULL_INCREMENTAL BackupTypeFullIncrementalAndWalStream BackupType FULL_INCREMENTAL_WAL_STREAM ) func (t BackupType) IsRequireWalSummary() bool { return t BackupTypeFullAndIncremental || t BackupTypeFullIncrementalAndWalStream } func (t BackupType) IsWalStreaming() bool { return t BackupTypeFullIncrementalAndWalStream }三个备份类型的权限画像可以总结如下备份类型枚举值是否需要pg_switch_walEXECUTE是否需要 WAL summary恢复能力仅全量FULL否否恢复到该次备份完成点全量 增量FULL_INCREMENTAL否是PG17恢复到增量链覆盖点全量 增量 WAL 流式FULL_INCREMENTAL_WAL_STREAM是是PG17任意时间点PITR因此仅全量含增量配置 不能强制轮转的凭据→ 配置被接受备份与恢复全程无权限错误。规格场景FULL_INCREMENTAL 不可轮转凭据 接受由checkReplicationReadiness中IsWalStreaming()分支之外的自然通过路径保证。日后升级为流式→ 用户把该数据库改为连续 WAL 流式时前述第三条要求立即适用于该变更若源无法界定恢复点则被拒绝。由于IsWalStreaming()只在FULL_INCREMENTAL_WAL_STREAM上为真变更生效的那一刻权限检查就随之收紧。这一设计避免了一个常见陷阱运维团队为了追求 PITR 而把仅需全量备份的源强行升级权限或反之在托管平台上因无法授予pg_switch_wal而放弃物理备份。Databasus 把备份能力与PITR 能力分层解耦基础备份只要求REPLICATIONPITR 才额外要求轮转权限两者由备份类型显式表达。与前置规格的衔接WAL 保留策略的配套视角理解复制凭据规格最好与同目录下的 WAL 保留规格 对照阅读。复制凭据规格回答凭据能否让恢复点前进WAL 保留规格回答前进的 WAL 何时可以被回收——两者共同保证恢复链的连续性一个 WAL 段只有当没有任何保留的、同一时间线上成功完成的全量备份始于该段结束之前时才被视为无引用可删跨越某备份开始位置的段必须保留因为它仍携带备份完成后的全部写入。一旦全量备份报告成功且 WAL 流式保持健康系统必须保持从该备份结束位置向后的归档 WAL 连续任何后台维护都不得在成功备份后立即引入缺口——这与本规格凭据必须能让恢复点前进互为前提轮转权限保证段会被定稿上传保留策略保证上传的段不会被误删。用一句话概括两者的分工复制凭据规格定义恢复点能推进的权限底线WAL 保留规格定义已推进的 WAL 不被破坏的删除边界。若要深入实践 PITR这两份文档应一并研读。实战排查清单基于上述规格与源码在实际接入 PostgreSQL 物理备份时可以按以下清单核对区分平台类型自管理集群可直接授予GRANT EXECUTE ON FUNCTION pg_switch_wal() TO roleRDS/Azure/GCP 等托管平台若无此授予途径流式配置会被拒绝no_wal_switch_privilege此时应接受仅全量/增量方案。检查复制基线权限凭据必须拥有REPLICATION属性且源集群wal_level为replica或logical、max_wal_senders与max_replication_slots大于 0。确认 PG17 的 WAL summary选择含增量或流式的备份类型时源必须开启summarize_walon见 ADR-0008。避免过度授权Databasus 供应用户时只会多加pg_switch_walEXECUTE 一项手工建用户时请避免 SUPERUSER、CREATEROLE、CREATEDB 与云管理员角色Databasus 会通过ShouldSuggestReplicationOnlyUser提示你收敛。理解拒绝消息的两条出路看到no_wal_switch_privilege时要么在源上授予 EXECUTE要么改选FULL/FULL_INCREMENTAL备份类型不要被引导去开启源端归档。确认连接测试时机该检查属于TestReplicationConnection的checkReplicationReadiness链路在创建与修改数据库、配置变更时都会触发且不会停止已运行的既有备份。相关参考文件规格文档 replication-credentials/spec.md 与配套的 wal-retention/spec.md核心实现 forced_wal_rotation.go、model.go、enums.go、wal_rotation.go校验测试见 forced_wal_rotation_test.go 与 controller_test.go。赞分享数据库灾备【免费下载链接】databasusPostgreSQL backup tool with Point-In-Time-Recovery and restore verification项目地址https://gitcode.com/gh_mirrors/po/databasus点击查看免费下载相关推荐Databasus 物理备份复制账号权限设计pg_switch_wal() 授权与 PITR 恢复点的前置校验Databasus 物理备份复制账号权限设计pg_switch_wal 授权与 PITR 恢复点的前置校验 本篇围绕 Databasus 物理备份的复制账号权数据库灾备Databasus PostgreSQL 物理备份为复制用户授予 pg_switch_wal() 权限让 WAL 流式备份的恢复点名副其实Databasus PostgreSQL 物理备份为复制用户授予 pg_switch_wal 权限让 WAL 流式备份的恢复点名副其实 本文围绕 Datab数据库灾备Databasus PostgreSQL 物理备份为复制用户授予 pg_switch_wal() 执行权并在连接测试中拦截无法强制 WAL 轮转的流式配置Databasus PostgreSQL 物理备份为复制用户授予 pg_switch_wal 执行权并在连接测试中拦截无法强制 WAL 轮转的流式配置 本文数据库灾备上一篇CANN/ge算子句柄销毁API下一篇cool-retro-term 纹理坐标畸变算法揭秘曲率效果核心代码逐行讲解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考