⚡

SchemaAlignmentSkill schema-alignment

数据库模式与代码数据模型之间的漂移检测工具，支持多种ORM和数据库技术，帮助识别和修复模式不一致问题。

架构设计 0 次安装 0 次浏览 更新于 3/2/2026

Schema Alignment Skill

数据库模式与代码数据模型之间的漂移检测。这项技能可以识别缺失的列、类型不匹配、孤立的迁移和命名不一致。

设计原则

这项技能是框架通用的。它适用于任何ORM或数据库：

  • SQLAlchemy (Python)
  • Django ORM (Python)
  • Prisma (TypeScript/JavaScript)
  • TypeORM (TypeScript)
  • Drizzle (TypeScript)
  • Alembic migrations
  • Prisma migrations
  • Django migrations

变量

变量 默认值 描述
SCHEMA_SOURCE auto 模式源：auto, migrations, live_db, models
SEVERITY_THRESHOLD medium 在此级别或更高级别报告问题
AUTO_FIX false 尝试生成修复建议
INCLUDE_TYPES true 包括类型不匹配检测

指令

MANDATORY - 按照以下工作流程步骤进行。

  1. 检测使用的数据库技术和ORM
  2. 从迁移或实时数据库中提取模式
  3. 从代码中提取数据模型
  4. 比较并识别漂移
  5. 生成对齐报告

红旗 - 停止并重新考虑

如果你即将：

  • 直接修改数据库模式而没有迁移
  • 假设列存在而没有检查模式
  • 因为“在测试中有效”而跳过类型检查
  • 忽略可空/不可空不匹配

停止 -> 检查模式对齐 -> 如有需要生成迁移 -> 然后继续

工作流程

1. 检测堆栈

识别数据库和ORM：

检查这些指标：

| 文件/依赖 | 技术 |
|-----------------|------------|
| alembic.ini, alembic/ | Alembic (SQLAlchemy) |
| prisma/schema.prisma | Prisma |
| manage.py + migrations/ | Django |
| ormconfig.json | TypeORM |
| drizzle.config.ts | Drizzle |
| supabase/migrations/ | Supabase (PostgreSQL) |

2. 提取数据库模式

选项A：从迁移（首选）

解析迁移文件以重建当前模式：

# Alembic示例
from alembic.script import ScriptDirectory
from alembic.config import Config

config = Config("alembic.ini")
scripts = ScriptDirectory.from_config(config)
# 遍历修订版本以构建模式

选项B：从实时数据库

查询information_schema（如果可访问）：

SELECT table_name, column_name, data_type, is_nullable
FROM information_schema.columns
WHERE table_schema = 'public';

选项C：从模型定义

直接解析ORM模型文件。

3. 提取代码模型

从代码中解析模型定义：

SQLAlchemy

# 查找类似模式：
class User(Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    email = Column(String(255), nullable=False)

Prisma

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

Pydantic/TypeScript类型

也提取相关类型：

  • Pydantic模型
  • TypeScript接口
  • BAML类型定义

4. 比较并检测漂移

运行比较：

检查 源A 源B 问题类型
缺失列 DB模式 ORM模型 MISSING_IN_MODEL
缺失列 ORM模型 DB模式 MISSING_IN_DB
类型不匹配 DB类型 代码类型 TYPE_MISMATCH
可空不匹配 DB可空 模型可空 NULLABLE_MISMATCH
命名漂移 snake_case camelCase NAMING_DRIFT
缺失迁移 模型更改 迁移文件 MISSING_MIGRATION
FK约束 DB约束 ORM关系 FK_MISMATCH

5. 生成报告

输出格式：

# Schema Alignment Report

**Generated**: 2025-12-24T10:00:00Z
**Database**: PostgreSQL (via Supabase)
**ORM**: SQLAlchemy 2.0

## 摘要

| 严重性 | 计数 |
|----------|-------|
| HIGH | 2 |
| MEDIUM | 3 |
| LOW | 5 |

## 问题

### 1. MISSING_IN_MODEL (HIGH)

**表**：`curation_jobs`
**列**：`retry_count` (INTEGER NOT NULL DEFAULT 0)
**模型**：`src/models/curation_job.py:CurationJob`

数据库中存在该列，但在ORM模型中未定义。

**修复**：
```python
retry_count: Mapped[int] = mapped_column(Integer, default=0)

2. TYPE_MISMATCH (MEDIUM)

表：books 列：isbn (VARCHAR(13)) 模型：src/models/book.py:Book.isbn -> str

数据库限制为13个字符，但模型允许无界字符串。

修复：

isbn: Mapped[str] = mapped_column(String(13))

3. MISSING_MIGRATION (LOW)

模型更改：User.preferences添加了(JSONB) 迁移：未找到

模型中添加了新列，但没有迁移。

修复：

alembic revision --autogenerate -m "add user preferences"


## 菜谱

### SQLAlchemy检测
- IF: 解析SQLAlchemy模型
- THEN: 阅读并执行`./cookbook/sqlalchemy-detection.md`

### Prisma检测
- IF: 解析Prisma模式
- THEN: 阅读并执行`./cookbook/prisma-detection.md`

### Alembic迁移
- IF: 生成迁移修复
- THEN: 阅读并执行`./cookbook/alembic-migration.md`

## 问题严重性矩阵

| 问题类型 | 默认严重性 | 如果升级 |
|------------|-----------------|------------|
| MISSING_IN_MODEL | HIGH | 列是NOT NULL |
| MISSING_IN_DB | MEDIUM | 模型引用它 |
| TYPE_MISMATCH | MEDIUM | 可能导致数据丢失 |
| NULLABLE_MISMATCH | LOW | 代码中为NOT NULL，数据库中为可空 |
| NAMING_DRIFT | LOW | - |
| MISSING_MIGRATION | LOW | - |
| FK_MISMATCH | MEDIUM | 导致ORM错误 |

## 集成

### 与/ai-dev-kit:check-schema一起使用

直接调用：

```bash
# 全检查
/ai-dev-kit:check-schema

# 检查特定表
/ai-dev-kit:check-schema --tables=users,orders

# 生成修复
/ai-dev-kit:check-schema --auto-fix

# 输出到文件
/ai-dev-kit:check-schema --output=alignment-report.md

与/ai-dev-kit:execute-lane一起使用

作为数据库相关通道的预飞行检查：

通道：SL-DB（数据库模式）

预飞行检查：
1. ✓ Git工作树干净
2. ✗ 模式对齐检查失败
   - 发现2个高严重性问题
   - 见alignment-report.md

操作：在继续之前解决模式问题。

与/ai-dev-kit:plan-phase一起使用

在阶段规划期间运行：

规划阶段P1...

模式对齐：⚠️ 检测到3个问题
- 1个缺失迁移
- 2个类型不匹配

建议：将模式对齐任务添加到SL-DB通道。

输出模式

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "generated_at": {"type": "string", "format": "date-time"},
    "database": {"type": "string"},
    "orm": {"type": "string"},
    "summary": {
      "type": "object",
      "properties": {
        "high": {"type": "integer"},
        "medium": {"type": "integer"},
        "low": {"type": "integer"}
      }
    },
    "issues": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {"type": "string"},
          "severity": {"enum": ["HIGH", "MEDIUM", "LOW"]},
          "table": {"type": "string"},
          "column": {"type": "string"},
          "model_location": {"type": "string"},
          "description": {"type": "string"},
          "fix": {"type": "string"}
        }
      }
    }
  }
}

最佳实践

  1. 定期运行：在每个PR之前检查模式对齐
  2. CI集成：在CI管道中添加以自动检测
  3. 迁移卫生：始终为模型更改生成迁移
  4. 类型一致性：在模型中使用与数据库约束匹配的显式类型
  5. 记录漂移：如果漂移是有意的，记录原因