/database-design

name: database-design
description: 设计 BK-CI 数据库表、DDL 脚本、索引、分表或数据归档策略时使用。当用户提到表结构、字段设计、索引优化、SQL 脚本命名、分片、归档迁移时优先使用。

BK-CI 数据库设计

适用场景

• 新增或调整表结构
• 编写 DDL、DML 或增量更新脚本
• 设计索引、唯一约束、查询路径
• 评估是否需要分表、归档或冷热分层
• 审查某个数据模型是否适合当前服务边界

不适用场景

• 只是写一条临时查询 SQL 排查数据
• 只是改业务代码，不涉及持久化模型和表结构
• 需求本质是 API 设计、模块归属或权限模型，不是数据库设计

快速指导

1. 先确认数据归属到哪个服务。BK-CI 采用微服务拆分，禁止因为方便查询而跨服务共用数据库。 2. 先决定表的角色，再决定字段和索引：

• 主实体表：存核心业务状态
• 关系表：表达多对多或映射关系
• 汇总表：承载聚合读模型
• 历史表：承载高频追加或归档数据

3. 先按查询路径设计索引，不要先堆字段。最常用查询条件、排序字段、唯一约束字段优先进入索引设计。 4. DDL 变更必须走脚本管理，不要直接在数据库里手工改线上结构。 5. 变更前先考虑兼容性：

• 老字段是否仍被旧版本代码读取
• 新字段是否需要默认值
• 是否需要分阶段发布

6. 大表问题优先判断是索引、归档、冷热分层还是分表，不要默认直接分片。 7. 对 JSON、大文本、状态快照类字段，要明确为什么不能拆表，避免把主表做成“万能存储”。

高信号规则

• 脚本命名和版本目录要保持统一，详细规则见 `reference/1-script-management.md`
• 分表与路由策略的细节见 `reference/2-sharding.md`
• 表结构设计要服务于服务边界和查询模式，而不是追求理论上的“最全字段”
• 能用代码层聚合解决的问题，不优先通过跨服务数据库耦合解决

关键陷阱

• 只看写入模型，不看读路径，最后索引完全不匹配真实查询
• 先建“超大宽表”，后续再靠补丁式字段堆积解决一切问题
• 为了省事直接复用别的服务数据库，导致服务边界失效
• 把分表当成性能优化默认选项，忽略归档、汇总和冷热拆分
• 只改 DDL 不评估回滚、兼容和灰度发布路径

延伸阅读

• 脚本管理：`reference/1-script-management.md`
• 分表策略：`reference/2-sharding.md`
• 如果需求同时涉及模块归属，先看 `00-bkci-global-architecture`