openGauss灵衢加速资源池化事务快照传输特性简介 ​

可获得性 ​

本特性自openGauss 7.0.0版本开始引入。

特性简介 ​

在openGauss资源池化（一写多读）场景下，备机在执行事务状态判断、事务可见性判断以及快照相关逻辑时，需要频繁通过DMS消息或广播机制从主机获取CLOG、CSNLOG、Snapshot和OldestXmin等事务元数据。随着并发度和事务量上升，高频跨节点TCP通信会带来额外的消息交互开销和主机处理负担，成为事务状态查询和可见性判断路径上的性能热点。

本特性基于鲲鹏超节点（灵衢）提供的UB（Unified Bus）共享内存能力，在资源池化集群中为CLOG、CSNLOG、Snapshot和OldestXmin建立共享内存加速通道，将高频事务元数据访问从"消息获取"优化为"共享内存直读"，降低跨节点访问时延，减轻主机消息处理压力，提升资源池化场景的事务处理效率。

客户价值 ​

1. 降低事务访问时延：备机访问事务状态和可见性信息时的跨节点时延显著降低，热点事务路径的访问效率提升。
2. 减轻主机负载：减少主机处理DMS请求和广播同步的压力，缓解高并发场景下的消息负载，提高多节点读写的并发能力。
3. 兼顾性能与可靠性：在不改变现有事务语义和异常处理框架的前提下，通过"共享内存优先、DMS回退"的方式，既获得性能收益又保障功能可靠性。

特性描述 ​

本特性在资源池化场景下，利用灵衢UB共享内存能力，为主备节点间的四类事务元数据传输建立加速通道：

1. CLOG获取加速：主机在更新事务状态时同步维护CLOG共享内存缓存，备机查询事务提交、回滚和进行中状态时优先读取共享内存，失败后回退DMS。
2. CSNLOG获取加速：主机在写入事务CSN时同步维护CSNLOG共享内存缓存，备机进行事务可见性判断时优先读取共享内存中的CSN信息，失败后回退DMS。
3. Snapshot获取加速：主机在刷新最新MVCC快照时同步维护Snapshot共享内存槽位，备机获取快照时优先读取共享内存中的xmin/xmax/csn，失败后回退广播或DMS。
4. OldestXmin同步加速：备机定期将本节点oldest_xmin写入主机共享内存指定槽位，主机基于共享内存和本地状态维护全局OldestXmin，失败后回退DMS。
5. Reform场景适配：定义共享内存在normal reform、switchover、failover等场景下的初始化、映射、重建、热缓存拷贝、预热和失效处理规则，确保功能在故障和角色切换场景下行为可控。

本特性不涉及CLOG、CSNLOG的磁盘格式变更，不改变事务可见性语义，不新增用户可见SQL接口，现有DMS路径继续作为共享内存路径的异常兜底机制保留。

相较于原有通过DMS消息通信和广播机制同步事务元数据的方案，本特性基于灵衢UB共享内存能力做了如下增强：

1. CLOG/CSNLOG共享内存作为跨节点一级热缓存：本地SLRU缓存继续保留为节点内二级缓存，主机事务提交或状态推进时先沿用现有流程更新SLRU页面，再同步到灵衢共享内存，不改变原有事务状态落盘顺序和恢复语义。
2. Snapshot双读校验机制：Snapshot分区采用"version + xmin/xmax/csn + version"的双读校验方式，利用灵衢共享内存最高128位原子读写能力，避免读取半写状态，并与广播快照协同工作，保证备机始终获取最新有效快照。
3. 热缓存迁移：在switchover和在线failover场景下，新主节点可以将旧主的CLOG/CSNLOG热缓存拷贝到本机共享内存，减少切换后的缓存冷启动成本。
4. SLRU预热：在startup_reform场景下，通过SLRU预热机制在StartupXLOG尾段重新填充CLOG/CSNLOG共享内存，由参数ss_init_clog_size控制预热窗口大小。
5. 共享内存生命周期自动管理：所有节点在启动阶段完成本节点共享内存初始化，正常运行阶段由当前主机共享内存承担加速能力，备机共享内存作为角色切换时的预留资源，尽可能减少用户手动清理共享内存的操作。

特性增强 ​

特性约束 ​

1. 本特性只在openGauss的资源池化架构下生效，且集群各节点需要具备鲲鹏超节点（灵衢）能力，并在数据库参数配置文件中设置UB动态库路径。
2. 本特性在集群中所有节点统一生效，不支持集群中部分节点开启该功能。
3. 由于事务日志内存拷贝流程与按需回放冲突，本特性与按需回放+实时构建特性（enable_ondemand_recovery）不支持同时开启。
4. CLOG分区实际占用8GB、CSNLOG分区实际占用2GB、OldestXmin和Snapshot分区各按最小粒度对齐到128MB，整块连续共享内存总占用约11GB，需确保超节点有足够共享内存资源。
5. 本特性创建的共享内存主要用于事务和快照信息的缓存访问加速，退出时不进行清理，便于下次启动复用。
6. 由于灵衢共享内存映射对用户权限具有条件约束，本特性使用时集群各个节点的用户uid必须保持相同。
7. 本特性依赖的UBS Memory软件包对于底层组件的版本存在依赖关系，因此不推荐使用安装包内附带的libstdc++.so.6，应当使用系统/usr/lib64/目录下的动态库，可能会导致启动失败。
8. 灵衢内存故障场景的处理依赖OS层面的相关可靠性功能实现，目前正在进行适配和开发工作中，因此该场景处理暂未加入本特性中。
9. 主机启动场景下的SLRU预热会增加主机启动耗时，ss_init_clog_size配置越大，预热开销越高；在线failover和switchover场景，新主会将旧主共享内存拷贝给自己，避免冷启动，会增加部分RTO时间。

依赖关系 ​

1. 硬件依赖：集群各节点需具备鲲鹏超节点（灵衢）的UB共享内存能力。
2. 软件依赖：依赖UBS Memory服务提供的UB Memory共享域创建、共享内存申请与映射能力；依赖DMS组件提供资源池化场景下的事务状态同步兜底机制。
3. 参数依赖：本特性总开关enable_ub需设置为on；ss_init_clog_size参数用于调整CLOG/CSNLOG启动预热窗口上限。

基本原理 ​

本特性采用"本地持久化链路不变、灵衢共享内存优先访问、DMS作为兜底"的分层方案。核心原理如下：

共享内存组织：每个节点创建一块固定长度的连续共享内存（名称ub_<inst_id>_<user_id>_txn_cache），按偏移划分为控制块、CLOG区、CSNLOG区、OldestXmin区和Snapshot区。所有节点都会映射主节点的共享内存，如果发生倒换则重新映射新主节点的共享内存。

CLOG缓存结构：使用连续共享内存槽位数组clog_buf，长度2^32，每个槽位16位（14位timeline + 2位clogvalue），总计8GB。按xid计算槽位下标idx = xid % ClogCacheSize，timeline = (xid / ClogCacheSize) % (2^14)用于校验。利用16位原子读写避免半读半写。

CSNLOG缓存结构：使用连续共享内存槽位数组csnlog_buf，长度2^27，每个槽位128位（高64位timeline + 低64位csn），总计2GB。按xid计算槽位下标idx = xid % CsnlogCacheSize，timeline = xid / CsnlogCacheSize。利用128位原子读写避免半读半写。

Snapshot缓存结构：采用单槽位"version + xmin/xmax/csn + version"的双读校验方式。主机写入时先写奇数version再写偶数version，备机读取时只有前后版本一致且为偶数时才认为命中成功。

OldestXmin缓存结构：按inst_id组织128个槽位的固定长度数组，每个槽位保存64位oldest_xmin，初始值为0表示无效。

访问路径：备机访问事务元数据时优先读取主机共享内存，命中则直接返回；未命中、校验失败、处于reform期间或共享内存不可用时，回退到现有DMS链路。

Reform适配：reform开始后立即暂停共享内存加速路径，事务状态访问统一回退DMS；reform结束后重新映射主节点共享内存并恢复快路径。switchover/在线failover场景下会尝试将旧主CLOG/CSNLOG热缓存迁移到新主；startup_reform场景下通过SLRU预热重新填充缓存。

使用指导 ​

参数配置 ​

配置策略 ​

1. 部署启动：如果希望使用UB内存加速访问路径，则需要开启enable_ub = on，ss_init_clog_size可自行设置，也可使用默认100MB。
2. 初次启动如果发现有残留的未知共享内存存在，为了保险可以使用ubsectl delete memory -t share --name xxx命令将内存清理掉，防止访问到错误的遗留内存块。
3. 由于特性约束中第7点提到的依赖文件限制，在通过gs_install执行脚本安装好集群环境之后，需要检索openGauss目录下的libstdc++.so.6文件，并使用mv或者rm命令将其备份或者直接删除，使得gaussdb自动链接系统库文件。
4. 由于本特性必须依赖UBS Memory动态库组件，因此系统参数配置中需要添加文件路径的参数，例如ubs_mem_path = '/usr/local/ubs_mem/lib/libubsm_sdk.so'，具体文件路径根据UB安装设置决定。

参数联动约束 ​

1. enable_ub是本特性的前置开关，只有在其开启时，其余参数才具备实际意义。
2. ss_init_clog_size只在主机启动场景生效，normal reform、switchover和在线failover场景不触发预热逻辑。
3. 本特性与enable_ondemand_recovery不支持同时开启。

使用场景 ​

一主多备资源池化集群中，备机大量执行只读查询需要频繁判断事务可见性，CLOG/CSNLOG共享内存直读可显著降低单次事务状态查询的跨节点往返开销，同时可以加速备机获取快照速度。