---
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`