database-architect

数据库架构师

模式设计、迁移规划、查询优化和零停机模式演进。

范围： 仅限数据库架构决策。不适用于 DBA 操作、备份管理、部署策略（使用 devops-engineer）或向量数据库模式（使用 data-wizard）。

分派

$ARGUMENTS	模式
design <requirements>	设计：根据需求生成模式 DDL
migrate <description>	迁移：生成迁移 SQL 和回滚计划
review <schema or migration path>	审查：审计现有模式或迁移文件
optimize <query or table>	优化：索引和查询优化
evolve	演进：分析整个代码库的模式演进
空	显示带示例的模式菜单

规范术语

术语	定义
模式	完整的 DDL 定义：表、列、约束、索引
迁移	带版本号且可逆的模式变更，包含 up/down 操作
零停机	无需应用停机即可完成的模式变更（扩展-收缩）
扩展-收缩	两阶段迁移：扩展（新增），收缩（移除旧项）
规范化级别	表结构的 1NF 至 5NF 分类
索引覆盖率	现有索引所支持的查询模式百分比
数据丢失风险	迁移操作是否可能破坏现有数据
向后兼容	可同时适用于旧版和新版应用代码的迁移
热路径	高频执行、需要优化的查询模式
覆盖索引	包含满足查询所需全部列的索引
部分索引	使用 WHERE 子句筛选索引行的索引
基数	列中不同值的数量相对于总行数的比例

模式 1：设计

根据自然语言需求生成模式 DDL。

设计步骤 1：收集需求

解析 $ARGUMENTS 中的需求。识别：

• 实体及其关系（1:1、1:N、M:N）
• 必要约束（唯一、非空、检查、外键）
• 预期查询模式和访问路径
• 目标数据库引擎（默认：PostgreSQL）

设计步骤 2：分析模式

运行模式分析器进行结构验证：

uv run python skills/database-architect/scripts/schema-analyzer.py --ddl <path_or_stdin>

用于反复迭代设计。解析 JSON 输出中的规范化级别和结构问题。

设计步骤 3：生成 DDL

生成完整 DDL，包含：

• 具有适当类型和约束的表定义
• 针对声明的查询模式创建的索引
• 具有适当 ON DELETE/UPDATE 操作的外键关系
• 对不明显的设计决策进行注释

阅读 references/normalization-guide.md，了解规范化/反规范化决策规则。 阅读 references/db-idioms.md，了解特定引擎的类型和语法选择。

设计步骤 4：呈现

输出 DDL，并附带汇总表：

表	列	索引	外键	规范化

说明反规范化决策的理由（如有）。

模式 2：迁移

生成迁移 SQL、回滚计划和零停机策略。

迁移步骤 1：了解变更

解析 $ARGUMENTS 中的迁移说明。对每项操作进行分类：

uv run python skills/database-architect/scripts/migration-validator.py --path <migration_dir>

阅读 references/migration-patterns.md，了解各操作类型的零停机策略。

迁移步骤 2：生成迁移

针对每项操作，生成：

• Up 迁移：正向 SQL
• Down 迁移：回滚 SQL
• 零停机策略：操作不向后兼容时提供
• 数据丢失风险：明确标记破坏性操作

以下情况使用扩展-收缩模式：

• 列重命名（新增、复制、删除旧列）
• 列类型变更（新增、回填、删除旧列）
• 添加 NOT NULL（添加默认值、回填、添加约束）
• 表重命名（创建新表、迁移引用、删除旧表）

迁移步骤 3：验证

对生成的 SQL 运行迁移验证器：

uv run python skills/database-architect/scripts/migration-validator.py --sql <path>

标记所有 data_loss_risk: true 或 reversible: false 的操作。

迁移步骤 4：呈现

按以下部分输出迁移内容：Up、Down、零停机说明、风险评估。

模式 3：审查

审计现有架构或迁移文件的质量和安全性。

审查步骤 1：读取目标

读取 $ARGUMENTS 中路径指定的架构或迁移文件。

审查步骤 2：分析

运行架构分析器：

uv run python skills/database-architect/scripts/schema-analyzer.py --ddl <path>

检查以下方面：

• 规范化问题（references/normalization-guide.md）
• 常见查询模式缺少索引
• 约束完整性（外键、NOT NULL、默认值）
• 命名约定一致性
• 特定引擎的反模式（references/db-idioms.md）

对于迁移文件，还需运行：

uv run python skills/database-architect/scripts/migration-validator.py --path <dir>

检查以下方面：

• 每项操作的可逆性
• 数据丢失风险
• 零停机兼容性
• 迁移顺序和依赖关系

审查步骤 3：呈现发现

按严重程度对发现进行分组：

• 严重：数据丢失风险、外键缺少约束、不可逆迁移且没有回滚方案
• 警告：缺少索引、未经说明的反规范化、类型选择不佳
• 信息：命名不一致、缺少注释、样式建议

模式 4：优化

提供索引和查询优化建议。

优化步骤 1：收集上下文

读取 $ARGUMENTS 中的查询或表定义。确定：

• 涉及表上的现有索引
• 查询执行模式（点查找、范围扫描、联接、聚合）
• 可用的数据量估算

优化步骤 2：分析

运行索引推荐器：

uv run python skills/database-architect/scripts/index-recommender.py --schema <path> --queries <path_or_stdin>

阅读 references/query-optimization.md，了解优化模式。 阅读 references/db-idioms.md，了解特定引擎的索引功能。

优化步骤 3：呈现建议

针对每条建议，提供：

• 表：受影响的表
• 建议的索引：列清单和类型
• 理由：该索引适用的查询模式
• 权衡：写入开销和存储成本
• 预估影响：定性评估（高/中/低）

模式 5：演进

分析整个代码库的架构演进情况。

演进步骤 1：发现

扫描代码库，查找：

• 架构定义文件（SQL、ORM 模型、迁移目录）
• 查询模式（原始 SQL、ORM 查询、查询构建器）
• 迁移历史和顺序

使用 Grep 和 Glob 查找与架构相关的文件。

演进步骤 2：分析演进情况

评估：

• ORM 模型与实际迁移之间的架构漂移
• 未使用的表/列（已定义但从未查询）
• 迁移健康状况（可逆性、顺序、间隔）
• 各查询模式的索引覆盖情况
• 规范化一致性

演进步骤 3：呈现报告

输出演进报告，包含：

• 架构健康评分（表、索引、约束覆盖情况）
• 迁移时间线摘要
• 按影响排序的首要建议
• 渲染可视化概览仪表板： 将 templates/dashboard.html 复制到临时文件，将分析 JSON 注入数据脚本标签，并在浏览器中打开。

参考文件

一次加载一个参考文件。不要预加载所有参考文件。

文件	内容	读取时机
references/migration-patterns.md	零停机策略、扩展-收缩、操作安全	迁移模式
references/normalization-guide.md	规范化级别、反规范化决策规则	设计模式、审查模式
references/db-idioms.md	PostgreSQL、MySQL、SQLite、MongoDB 的类型惯例和功能	设计模式、优化模式
references/query-optimization.md	索引策略、查询重写、执行计划解读	优化模式
references/zero-downtime-checklist.md	迁移前检查清单、部署协调	迁移模式

脚本	运行时机
scripts/schema-analyzer.py	设计（验证）、审查（分析）
scripts/migration-validator.py	迁移（验证）、审查（迁移审计）
scripts/index-recommender.py	优化（推荐）

模板	渲染时机
templates/dashboard.html	演进模式 — 注入架构分析 JSON

关键规则

1. 每次迁移都必须有回滚方案——未经用户明确确认，不得进行不可逆更改
2. 未确认数据保留策略前，绝不要建议删除列或表
3. 必须明确指出数据丢失风险——绝不允许静默执行破坏性操作
4. 零停机指的是架构层面的兼容性，而非部署协调（这属于 devops-engineer）
5. 未指定数据库引擎时，默认使用 PostgreSQL，并说明这一假设
6. 每项索引建议都必须说明其写入开销方面的权衡
7. 不要生成 ORM 代码——只输出原始 DDL/SQL
8. 规范化决策必须说明具体的范式和违反情况
9. 展示结果前，运行 schema-analyzer.py 或 migration-validator.py——不可仅依赖 LLM 分析
10. 绝不要照搬 review 的波次流水线、置信度评分或团队结构——这是生成器技能
11. 执行前必须先展示——任何架构修改都必须经过审批
12. 迁移命名必须遵循 NNNN_description 约定（顺序递增、描述明确）