FDB Record Layer 在线索引构建全解析不停机安全增改索引的完整流程附避坑清单【免费下载链接】fdb-record-layerA relational database with SQL support built on FoundationDB项目地址: https://gitcode.com/gh_mirrors/fd/fdb-record-layer如果你正在使用FDB Record Layer——一个构建在 FoundationDB 之上、支持 SQL 的开源关系型数据库——那么一定遇到过这样的场景生产表要新增一个索引但表还在持续写入能不能不停机、不锁表地把索引建起来这正是 Record Layer 的核心能力之一在线索引构建Online Index Building。本文用通俗的语言拆解它的完整流程、三种构建策略以及一份来自源码的避坑清单帮你安全地在生产环境增改索引。 为什么需要在线构建索引传统数据库加索引时往往需要锁定表或暂停写入对大表来说意味着漫长的停机窗口。Record Layer 的在线索引器OnlineIndexer的设计思路完全不同见 OnlineIndexer 类注释低优先级事务建索引的事务刻意使用低优先级尽量不干扰正常读写自适应退让重试失败次数越多每轮干的活就越少对在线业务越温柔断点续建已建好的范围会记入RangeSet即使进程崩溃或多台机器同时跑也不会重复构建。一句话总结业务照常跑索引慢慢建。 先搞懂索引的 5 种状态理解在线构建的前提是理解索引状态机。Record Layer 中索引状态定义在 IndexState共 5 种状态含义能否用于查询是否维护READABLE已构建完成默认状态✅✅WRITE_ONLY构建中写不读❌✅WRITE_ONLY_WITH_QUEUE构建中用户写入先进待处理队列❌✅READABLE_UNIQUE_PENDING唯一索引已建完但还有重复数据⚠️ 可查但不可依赖唯一性✅DISABLED本库不使用此索引❌❌整个在线构建过程本质上就是驱动索引状态从WRITE_ONLY→READABLE的迁移。 在线索引构建的完整 4 步流程第一步把新索引以 WRITE_ONLY 状态加入元数据先修改RecordMetaData把新索引定义加进去同时把该索引标记为WRITE_ONLY状态提交到数据库。从这一刻起查询不会使用这个索引所以不完整也无关紧要新写入的记录会同步更新这个索引增量数据自动跟上。FDBRecordStore提供了便捷方法小表可以直接重建新记录类型上的索引也会自动选择合适策略见 FDBRecordStore。第二步触发在线构建通过OnlineIndexer触发构建它支持两种粒度当前事务内立即构建rebuildIndex(recordStore)适合小表跨多事务同步构建buildIndex()适合大表内部自带重试循环。第三步增量追赶与进度协调构建期间索引器一边全量扫描存量记录一边靠第一步的增量维护自动追上新的写入。多个构建进程之间通过RangeSet和索引类型戳定义在 index_build.proto协调分工避免重复劳动。第四步构建完成切换为 READABLE全量扫描完成、增量追平后索引器把索引标记为READABLE查询计划器从此可以把这个索引用到 SQL 查询中。至此全程没有一次停机。⚙️ 三种构建策略怎么选OnlineIndexer.IndexingPolicyOnlineIndexer.java 内部类让构建策略可配置核心有三种方式按源索引构建byIndex目标索引的列被某个已可读索引完整覆盖时直接扫描源索引而非全表速度最快按记录扫描byRecords最通用的兜底策略直接扫原始记录协同构建mutual indexing按范围分片允许多个进程分工协作建同一个索引超大表利器。遇到索引已被别人建了一半的情况策略器会按DesiredAction配置执行四种动作之一ERROR报错、REBUILD推倒重来、CONTINUE接着建、MARK_READABLE直接标记完成。生产上建议熟悉这些选项别让默认行为替你做主。⚠️ 避坑清单源码里挖出来的坑 1COUNT / SUM 这类非幂等索引。增量构建期间它们可能重复累加。Record Layer 用RangeSet保证每个范围只处理一次如果你自定义构建流程务必保持这一机制否则统计值会错。坑 2唯一索引撞上重复数据。建完后索引不一定直接变READABLE而是进入READABLE_UNIQUE_PENDING——查询可用但唯一性约束暂不可依赖。需要清理重复记录后状态才会转正。坑 3重试递归上限。索引器内部有安全网INDEXING_ATTEMPTS_RECURSION_LIMIT 5超过就抛错终止。看到Too many indexing attempts日志时检查的是构建策略冲突而不是重试次数不够。坑 4构建方式混用。上次用按记录建了一半这次想用按源索引接着建默认是冲突的需要通过allowedTakeoverSet显式允许这类转换如MULTI_TARGET_TO_SINGLE。坑 5高写入负载下的冲突。WRITE_ONLY_WITH_QUEUE状态专门用来隔离索引器与用户写入的冲突见 FDBRecordStoreProperties大写入量场景可考虑启用待写队列。 关键源码与文档路径想深入阅读推荐从这几个位置入手在线索引器核心实现fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/foundationdb/OnlineIndexer.java索引状态机定义fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/IndexState.java记录存储与索引状态管理fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/foundationdb/FDBRecordStore.java构建进度协议fdb-record-layer-core/src/main/proto/index_build.proto官方索引参考文档docs/sphinx/source/reference/Indexes.rst 总结FDB Record Layer 的在线索引构建靠的是低优先级 增量维护 状态机 断点续建四件套新索引以WRITE_ONLY起步OnlineIndexer在业务流量缝隙中慢慢补齐存量数据完成后切到READABLE全程不停机。记住本文的 4 步流程和 5 条避坑清单你就能在生产环境安全地增改索引了。【免费下载链接】fdb-record-layerA relational database with SQL support built on FoundationDB项目地址: https://gitcode.com/gh_mirrors/fd/fdb-record-layer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FDB Record Layer 在线索引构建全解析：不停机安全增改索引的完整流程（附避坑清单）
FDB Record Layer 在线索引构建全解析不停机安全增改索引的完整流程附避坑清单【免费下载链接】fdb-record-layerA relational database with SQL support built on FoundationDB项目地址: https://gitcode.com/gh_mirrors/fd/fdb-record-layer如果你正在使用FDB Record Layer——一个构建在 FoundationDB 之上、支持 SQL 的开源关系型数据库——那么一定遇到过这样的场景生产表要新增一个索引但表还在持续写入能不能不停机、不锁表地把索引建起来这正是 Record Layer 的核心能力之一在线索引构建Online Index Building。本文用通俗的语言拆解它的完整流程、三种构建策略以及一份来自源码的避坑清单帮你安全地在生产环境增改索引。 为什么需要在线构建索引传统数据库加索引时往往需要锁定表或暂停写入对大表来说意味着漫长的停机窗口。Record Layer 的在线索引器OnlineIndexer的设计思路完全不同见 OnlineIndexer 类注释低优先级事务建索引的事务刻意使用低优先级尽量不干扰正常读写自适应退让重试失败次数越多每轮干的活就越少对在线业务越温柔断点续建已建好的范围会记入RangeSet即使进程崩溃或多台机器同时跑也不会重复构建。一句话总结业务照常跑索引慢慢建。 先搞懂索引的 5 种状态理解在线构建的前提是理解索引状态机。Record Layer 中索引状态定义在 IndexState共 5 种状态含义能否用于查询是否维护READABLE已构建完成默认状态✅✅WRITE_ONLY构建中写不读❌✅WRITE_ONLY_WITH_QUEUE构建中用户写入先进待处理队列❌✅READABLE_UNIQUE_PENDING唯一索引已建完但还有重复数据⚠️ 可查但不可依赖唯一性✅DISABLED本库不使用此索引❌❌整个在线构建过程本质上就是驱动索引状态从WRITE_ONLY→READABLE的迁移。 在线索引构建的完整 4 步流程第一步把新索引以 WRITE_ONLY 状态加入元数据先修改RecordMetaData把新索引定义加进去同时把该索引标记为WRITE_ONLY状态提交到数据库。从这一刻起查询不会使用这个索引所以不完整也无关紧要新写入的记录会同步更新这个索引增量数据自动跟上。FDBRecordStore提供了便捷方法小表可以直接重建新记录类型上的索引也会自动选择合适策略见 FDBRecordStore。第二步触发在线构建通过OnlineIndexer触发构建它支持两种粒度当前事务内立即构建rebuildIndex(recordStore)适合小表跨多事务同步构建buildIndex()适合大表内部自带重试循环。第三步增量追赶与进度协调构建期间索引器一边全量扫描存量记录一边靠第一步的增量维护自动追上新的写入。多个构建进程之间通过RangeSet和索引类型戳定义在 index_build.proto协调分工避免重复劳动。第四步构建完成切换为 READABLE全量扫描完成、增量追平后索引器把索引标记为READABLE查询计划器从此可以把这个索引用到 SQL 查询中。至此全程没有一次停机。⚙️ 三种构建策略怎么选OnlineIndexer.IndexingPolicyOnlineIndexer.java 内部类让构建策略可配置核心有三种方式按源索引构建byIndex目标索引的列被某个已可读索引完整覆盖时直接扫描源索引而非全表速度最快按记录扫描byRecords最通用的兜底策略直接扫原始记录协同构建mutual indexing按范围分片允许多个进程分工协作建同一个索引超大表利器。遇到索引已被别人建了一半的情况策略器会按DesiredAction配置执行四种动作之一ERROR报错、REBUILD推倒重来、CONTINUE接着建、MARK_READABLE直接标记完成。生产上建议熟悉这些选项别让默认行为替你做主。⚠️ 避坑清单源码里挖出来的坑 1COUNT / SUM 这类非幂等索引。增量构建期间它们可能重复累加。Record Layer 用RangeSet保证每个范围只处理一次如果你自定义构建流程务必保持这一机制否则统计值会错。坑 2唯一索引撞上重复数据。建完后索引不一定直接变READABLE而是进入READABLE_UNIQUE_PENDING——查询可用但唯一性约束暂不可依赖。需要清理重复记录后状态才会转正。坑 3重试递归上限。索引器内部有安全网INDEXING_ATTEMPTS_RECURSION_LIMIT 5超过就抛错终止。看到Too many indexing attempts日志时检查的是构建策略冲突而不是重试次数不够。坑 4构建方式混用。上次用按记录建了一半这次想用按源索引接着建默认是冲突的需要通过allowedTakeoverSet显式允许这类转换如MULTI_TARGET_TO_SINGLE。坑 5高写入负载下的冲突。WRITE_ONLY_WITH_QUEUE状态专门用来隔离索引器与用户写入的冲突见 FDBRecordStoreProperties大写入量场景可考虑启用待写队列。 关键源码与文档路径想深入阅读推荐从这几个位置入手在线索引器核心实现fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/foundationdb/OnlineIndexer.java索引状态机定义fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/IndexState.java记录存储与索引状态管理fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/provider/foundationdb/FDBRecordStore.java构建进度协议fdb-record-layer-core/src/main/proto/index_build.proto官方索引参考文档docs/sphinx/source/reference/Indexes.rst 总结FDB Record Layer 的在线索引构建靠的是低优先级 增量维护 状态机 断点续建四件套新索引以WRITE_ONLY起步OnlineIndexer在业务流量缝隙中慢慢补齐存量数据完成后切到READABLE全程不停机。记住本文的 4 步流程和 5 条避坑清单你就能在生产环境安全地增改索引了。【免费下载链接】fdb-record-layerA relational database with SQL support built on FoundationDB项目地址: https://gitcode.com/gh_mirrors/fd/fdb-record-layer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考