Spock 故障排查手册10 个高频复制问题与解决方案【免费下载链接】spockLogical multi-master PostgreSQL replication项目地址: https://gitcode.com/gh_mirrors/spock3/spockSpock 是一款基于 PostgreSQL 的逻辑多主复制Logical Multi-Master Replication扩展能够让你在多个节点之间实现双向数据同步。在实际生产环境中Spock 故障排查是每个 DBA 迟早都要面对的课题——无论是复制不启动、订阅卡死还是复制延迟飙升处理不当都可能造成数据不一致。这份PostgreSQL 复制故障排查手册为你整理了 10 个最常遇到的Spock 复制问题与对应的解决方案附上可复用的 SQL 命令和诊断思路帮你快速定位、快速恢复。排查前的准备工作必查参数与日志在开始逐个排查之前先确认基础配置是否正确。Spock 正常运行需要在每个节点的postgresql.conf中设置以下参数详细说明见 configuring.mdwal_level logical max_worker_processes 10 max_replication_slots 10 max_wal_senders 10 shared_preload_libraries spock track_commit_timestamp on同时确认pg_hba.conf允许节点间建立连接并检查 PostgreSQL 日志RHEL 系通常位于/var/lib/pgsql/18/data/log/tail -f /var/lib/pgsql/18/data/log/postgresql-*.log grep -i spock /var/lib/pgsql/18/data/log/postgresql-*.log以下 10 个高频问题均假设以上基础配置已经就绪。问题 1复制不启动订阅一直没有任何动静现象创建订阅后复制进程始终不工作节点间数据不同步。排查步骤用psql -h 节点IP -U postgres -d 数据库名测试节点间连通性确认两端都安装了扩展SELECT extname, extversion FROM pg_extension WHERE extname spock;查看 PostgreSQL 日志中的详细报错。解决方案绝大多数情况是pg_hba.conf未放行逻辑复制连接或扩展未在两端创建。修正后重试即可。问题 2订阅卡在 Initializing 状态现象spock.sub_show_status()显示订阅长期处于初始化initializing状态无法完成初始同步。排查与解决检查提供方节点参数是否够用订阅数越多需要的值越大SHOW max_replication_slots; -- 每个提供方节点至少为 1 SHOW max_wal_senders; -- 每个提供方节点至少为 1PostgreSQL 18 还需检查max_active_replication_origins建议至少等于订阅数并留出余量修改参数后重启 PostgreSQLsudo systemctl restart postgresql-18用SELECT * FROM spock.sub_show_status();复查状态。问题 3DDL 语句没有复制到其他节点现象在提供方执行CREATE TABLE、ALTER TABLE等 DDL订阅方没有任何反应。排查与解决SHOW spock.enable_ddl_replication; -- 应为 on SHOW spock.include_ddl_repset; -- 应开启 SHOW spock.allow_ddl_from_functions; -- 函数内 DDL 是否需要复制注意CREATE DATABASE等语句被 Spock 刻意排除在复制之外CREATE TABLE...AS...会复制但可能不安全。此外启用自动 DDL 复制前务必保证各节点表结构完全一致。问题 4UPDATE/DELETE 报错 unable to find tuple现象UPDATE或DELETE操作在复制时失败日志提示找不到目标元组。原因表缺少主键Primary Key或合法的副本标识Replica Identity复制进程无法唯一定位要更新的行。解决方案二选一-- 方案一添加主键 ALTER TABLE table_name ADD PRIMARY KEY (column_name); -- 方案二基于唯一索引设置副本标识 ALTER TABLE table_name REPLICA IDENTITY USING INDEX index_name;唯一索引必须是非部分、非延迟non-deferrable且基于 NOT NULL 列。注意REPLICA IDENTITY FULL只有在表有主键且配置了 Delta-Apply 列时才受支持。问题 5唯一约束冲突导致复制中断现象订阅方表上存在多个唯一索引或约束复制时出现如下报错ERROR: spock doesnt support index rechecks needed for deferrable indexes DETAIL: relation public.test_relation has deferrable indexes: index1原因多主环境下下游表应只保留一个唯一索引/约束/主键延迟约束deferrable还会在 INSERT 冲突检测时被静默跳过可能产生重复行。详细限制见 limitations.md。解决方案将延迟约束改为非延迟约束ALTER TABLE table_name DROP CONSTRAINT constraint_name; ALTER TABLE table_name ADD CONSTRAINT constraint_name UNIQUE (column_name);问题 6Delta-Apply 列报 cant operate NULL values现象配置了 Delta-Apply 冲突规避的列在应用时报错复制进程停止。原因Delta-Apply 列必须定义为 NOT NULL否则无法计算增量值。解决方案ALTER TABLE table_name ALTER COLUMN column_name SET NOT NULL; ALTER TABLE table_name ALTER COLUMN column_name SET (log_old_valuetrue, delta_apply_functionspock.delta_apply);关于 Delta-Apply 的冲突规避原理参见 conflicts.md。问题 7订阅状态显示 down现象订阅状态为 down数据停止同步。排查与解决确认提供方节点在线且可访问查看提供方复制槽是否活跃SELECT slot_name, active FROM pg_replication_slots;检查两端 PostgreSQL 日志中的错误尝试重启订阅SELECT spock.sub_disable(subscription_name : sub_name); SELECT spock.sub_enable(subscription_name : sub_name);问题 8复制延迟Lag持续升高现象订阅方数据明显落后于提供方实时性变差。排查用 Spock 自带的延迟追踪视图查看每个订阅的落后情况字段含义见 lag_tracking.mdSELECT * FROM spock.lag_tracker;重点关注replication_lag时间延迟和replication_lag_bytes数据量延迟。常见原因与对策max_worker_processes不足 → 调大并重启网络带宽受限 → 检查吞吐量大事务阻塞 → 尽量拆分为小事务订阅方硬件性能差 → 升级硬件或降低负载。问题 9冲突解决策略不生效现象多主节点同时修改同一行数据期望的冲突解决结果没有出现。排查与解决SHOW spock.conflict_resolution; -- 目前仅支持 last_update_winslast_update_wins最后更新时间戳胜出依赖track_commit_timestamp on。如果该参数关闭冲突解决将退化为远端变更总是静默应用。设置方式ALTER SYSTEM SET spock.conflict_resolution last_update_wins; SELECT pg_reload_conf();冲突类型如insert_exists、delete_missing等及可解决性对照详见 conflict_types.md。问题 10节点故障后无法恢复数据现象某节点宕机其他节点缺少该节点部分事务常规重启无法补齐。解决方案使用 ACEActive Consistency Engine进行五阶段恢复流程详见 catastrophic_node_failure.md评估幸存节点上的订阅状态清理 Spock 元数据spock.sub_drop()与spock.node_drop()用ace table-diff找出缺失数据用ace table-repair以同步节点为数据源修复重跑 table-diff 校验一致性。⚠️ 关键提醒修复时务必使用--preserve-origin标志否则修复行的 origin ID 和时间戳会错乱引发新一轮冲突。善用异常日志与升级后的快速验证复制被错误中断时先查看异常行为设置与异常日志SHOW spock.exception_behaviour; -- transdiscard / discard / sub_disable SELECT * FROM spock.exception_log ORDER BY timestamp DESC LIMIT 10;Spock 升级后建议用以下查询做一次快速体检SELECT extname, extversion FROM pg_extension WHERE extname spock; SELECT sub_name, sub_enabled FROM spock.subscription; SELECT slot_name, active FROM pg_replication_slots; SELECT application_name, state, write_lag FROM pg_stat_replication;写在最后这 10 个问题是Spock 故障排查中最常见的高频场景覆盖了连接、订阅、DDL、冲突、性能、恢复等核心环节。掌握上述诊断 SQL 和修复命令大多数复制故障都能在几分钟内定位。如果问题依然无法解决记得收集 Spock 版本、PostgreSQL 版本、postgresql.conf配置、日志报错以及spock.sub_show_status()输出这些信息能极大缩短支持排查时间。相关函数说明可参考 spock_functions/index.mdGUC 配置细节可查阅 configuring.md。【免费下载链接】spockLogical multi-master PostgreSQL replication项目地址: https://gitcode.com/gh_mirrors/spock3/spock创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Spock 故障排查手册：10 个高频复制问题与解决方案
Spock 故障排查手册10 个高频复制问题与解决方案【免费下载链接】spockLogical multi-master PostgreSQL replication项目地址: https://gitcode.com/gh_mirrors/spock3/spockSpock 是一款基于 PostgreSQL 的逻辑多主复制Logical Multi-Master Replication扩展能够让你在多个节点之间实现双向数据同步。在实际生产环境中Spock 故障排查是每个 DBA 迟早都要面对的课题——无论是复制不启动、订阅卡死还是复制延迟飙升处理不当都可能造成数据不一致。这份PostgreSQL 复制故障排查手册为你整理了 10 个最常遇到的Spock 复制问题与对应的解决方案附上可复用的 SQL 命令和诊断思路帮你快速定位、快速恢复。排查前的准备工作必查参数与日志在开始逐个排查之前先确认基础配置是否正确。Spock 正常运行需要在每个节点的postgresql.conf中设置以下参数详细说明见 configuring.mdwal_level logical max_worker_processes 10 max_replication_slots 10 max_wal_senders 10 shared_preload_libraries spock track_commit_timestamp on同时确认pg_hba.conf允许节点间建立连接并检查 PostgreSQL 日志RHEL 系通常位于/var/lib/pgsql/18/data/log/tail -f /var/lib/pgsql/18/data/log/postgresql-*.log grep -i spock /var/lib/pgsql/18/data/log/postgresql-*.log以下 10 个高频问题均假设以上基础配置已经就绪。问题 1复制不启动订阅一直没有任何动静现象创建订阅后复制进程始终不工作节点间数据不同步。排查步骤用psql -h 节点IP -U postgres -d 数据库名测试节点间连通性确认两端都安装了扩展SELECT extname, extversion FROM pg_extension WHERE extname spock;查看 PostgreSQL 日志中的详细报错。解决方案绝大多数情况是pg_hba.conf未放行逻辑复制连接或扩展未在两端创建。修正后重试即可。问题 2订阅卡在 Initializing 状态现象spock.sub_show_status()显示订阅长期处于初始化initializing状态无法完成初始同步。排查与解决检查提供方节点参数是否够用订阅数越多需要的值越大SHOW max_replication_slots; -- 每个提供方节点至少为 1 SHOW max_wal_senders; -- 每个提供方节点至少为 1PostgreSQL 18 还需检查max_active_replication_origins建议至少等于订阅数并留出余量修改参数后重启 PostgreSQLsudo systemctl restart postgresql-18用SELECT * FROM spock.sub_show_status();复查状态。问题 3DDL 语句没有复制到其他节点现象在提供方执行CREATE TABLE、ALTER TABLE等 DDL订阅方没有任何反应。排查与解决SHOW spock.enable_ddl_replication; -- 应为 on SHOW spock.include_ddl_repset; -- 应开启 SHOW spock.allow_ddl_from_functions; -- 函数内 DDL 是否需要复制注意CREATE DATABASE等语句被 Spock 刻意排除在复制之外CREATE TABLE...AS...会复制但可能不安全。此外启用自动 DDL 复制前务必保证各节点表结构完全一致。问题 4UPDATE/DELETE 报错 unable to find tuple现象UPDATE或DELETE操作在复制时失败日志提示找不到目标元组。原因表缺少主键Primary Key或合法的副本标识Replica Identity复制进程无法唯一定位要更新的行。解决方案二选一-- 方案一添加主键 ALTER TABLE table_name ADD PRIMARY KEY (column_name); -- 方案二基于唯一索引设置副本标识 ALTER TABLE table_name REPLICA IDENTITY USING INDEX index_name;唯一索引必须是非部分、非延迟non-deferrable且基于 NOT NULL 列。注意REPLICA IDENTITY FULL只有在表有主键且配置了 Delta-Apply 列时才受支持。问题 5唯一约束冲突导致复制中断现象订阅方表上存在多个唯一索引或约束复制时出现如下报错ERROR: spock doesnt support index rechecks needed for deferrable indexes DETAIL: relation public.test_relation has deferrable indexes: index1原因多主环境下下游表应只保留一个唯一索引/约束/主键延迟约束deferrable还会在 INSERT 冲突检测时被静默跳过可能产生重复行。详细限制见 limitations.md。解决方案将延迟约束改为非延迟约束ALTER TABLE table_name DROP CONSTRAINT constraint_name; ALTER TABLE table_name ADD CONSTRAINT constraint_name UNIQUE (column_name);问题 6Delta-Apply 列报 cant operate NULL values现象配置了 Delta-Apply 冲突规避的列在应用时报错复制进程停止。原因Delta-Apply 列必须定义为 NOT NULL否则无法计算增量值。解决方案ALTER TABLE table_name ALTER COLUMN column_name SET NOT NULL; ALTER TABLE table_name ALTER COLUMN column_name SET (log_old_valuetrue, delta_apply_functionspock.delta_apply);关于 Delta-Apply 的冲突规避原理参见 conflicts.md。问题 7订阅状态显示 down现象订阅状态为 down数据停止同步。排查与解决确认提供方节点在线且可访问查看提供方复制槽是否活跃SELECT slot_name, active FROM pg_replication_slots;检查两端 PostgreSQL 日志中的错误尝试重启订阅SELECT spock.sub_disable(subscription_name : sub_name); SELECT spock.sub_enable(subscription_name : sub_name);问题 8复制延迟Lag持续升高现象订阅方数据明显落后于提供方实时性变差。排查用 Spock 自带的延迟追踪视图查看每个订阅的落后情况字段含义见 lag_tracking.mdSELECT * FROM spock.lag_tracker;重点关注replication_lag时间延迟和replication_lag_bytes数据量延迟。常见原因与对策max_worker_processes不足 → 调大并重启网络带宽受限 → 检查吞吐量大事务阻塞 → 尽量拆分为小事务订阅方硬件性能差 → 升级硬件或降低负载。问题 9冲突解决策略不生效现象多主节点同时修改同一行数据期望的冲突解决结果没有出现。排查与解决SHOW spock.conflict_resolution; -- 目前仅支持 last_update_winslast_update_wins最后更新时间戳胜出依赖track_commit_timestamp on。如果该参数关闭冲突解决将退化为远端变更总是静默应用。设置方式ALTER SYSTEM SET spock.conflict_resolution last_update_wins; SELECT pg_reload_conf();冲突类型如insert_exists、delete_missing等及可解决性对照详见 conflict_types.md。问题 10节点故障后无法恢复数据现象某节点宕机其他节点缺少该节点部分事务常规重启无法补齐。解决方案使用 ACEActive Consistency Engine进行五阶段恢复流程详见 catastrophic_node_failure.md评估幸存节点上的订阅状态清理 Spock 元数据spock.sub_drop()与spock.node_drop()用ace table-diff找出缺失数据用ace table-repair以同步节点为数据源修复重跑 table-diff 校验一致性。⚠️ 关键提醒修复时务必使用--preserve-origin标志否则修复行的 origin ID 和时间戳会错乱引发新一轮冲突。善用异常日志与升级后的快速验证复制被错误中断时先查看异常行为设置与异常日志SHOW spock.exception_behaviour; -- transdiscard / discard / sub_disable SELECT * FROM spock.exception_log ORDER BY timestamp DESC LIMIT 10;Spock 升级后建议用以下查询做一次快速体检SELECT extname, extversion FROM pg_extension WHERE extname spock; SELECT sub_name, sub_enabled FROM spock.subscription; SELECT slot_name, active FROM pg_replication_slots; SELECT application_name, state, write_lag FROM pg_stat_replication;写在最后这 10 个问题是Spock 故障排查中最常见的高频场景覆盖了连接、订阅、DDL、冲突、性能、恢复等核心环节。掌握上述诊断 SQL 和修复命令大多数复制故障都能在几分钟内定位。如果问题依然无法解决记得收集 Spock 版本、PostgreSQL 版本、postgresql.conf配置、日志报错以及spock.sub_show_status()输出这些信息能极大缩短支持排查时间。相关函数说明可参考 spock_functions/index.mdGUC 配置细节可查阅 configuring.md。【免费下载链接】spockLogical multi-master PostgreSQL replication项目地址: https://gitcode.com/gh_mirrors/spock3/spock创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考