database-patterns

数据库模式

涵盖数据库迁移、模式设计和版本管理的完整模式。每个类别都在 rules/ 中包含独立规则文件，按需加载。

快速参考

类别	规则数	影响	适用场景
Alembic 迁移	2	CRITICAL	数据迁移、分支管理
模式设计	3	HIGH	规范化、索引策略、NoSQL 模式
版本管理	2	HIGH	更新日志、模式漂移检测
零停机迁移	2	CRITICAL	扩展-收缩、pgroll、回滚监控

| 数据库选择 | 1 | HIGH | 选择合适的数据库、PostgreSQL 与 MongoDB 对比、成本分析 |

共计：5 个类别中的 10 条规则

此技能是对 Alembic 和 PostgreSQL 的封装，而非其文档的替代品。请先阅读 references/ork-delta.md：其中列出了上游文档未涵盖的版本下限、修正和内部约定。下表中的内容都是有意移除的。

上游文档涵盖内容（请勿重复说明）

这些主题属于厂商文档。请从相应来源查阅，而不是在此重新讲解。

主题	一手资料
Alembic 自动生成、异步 env.py 模板、revision/upgrade/downgrade/history CLI	https://alembic.sqlalchemy.org/en/latest/autogenerate.html（我们对异步模板的一项修正见 references/ork-delta.md）
迁移分支、合并修订、元组 down_revision、分支标签	https://alembic.sqlalchemy.org/en/latest/branches.html
多数据库 env.py、批量回填方案、迁移钩子、按环境条件执行的迁移	https://alembic.sqlalchemy.org/en/latest/cookbook.html
回滚和数据完整性测试框架	references/migration-testing.md
JSONB 运算符、索引和存储权衡	https://www.postgresql.org/docs/current/datatype-json.html（范式和内部反规范化决策见 rules/schema-normalization.md）
完整索引类型参考及语法（B-tree、GIN、部分索引、覆盖索引、CREATE INDEX CONCURRENTLY、REINDEX）	https://www.postgresql.org/docs/current/sql-createindex.html（实际采用的内部子集见 rules/schema-indexing.md）
迁移期间的 lock_timeout、statement_timeout、咨询锁	https://www.postgresql.org/docs/current/runtime-config-client.html 和 rules/versioning-drift.md
枚举类型变更	https://www.postgresql.org/docs/current/datatype-enum.html
表分区	https://www.postgresql.org/docs/current/ddl-partitioning.html
触发器函数	https://www.postgresql.org/docs/current/plpgsql-trigger.html
外键级联语义	https://www.postgresql.org/docs/current/ddl-constraints.html
时态表和审计轨迹表、CDC 变更日志、存储过程和视图版本管理	https://www.postgresql.org/docs/18/sql-createtable.html（假设这些功能会提供行历史记录之前，请先阅读 references/ork-delta.md）
HNSW 和向量索引调优（m、ef_construction、hnsw.ef_search）	https://github.com/pgvector/pgvector
通用的部署前、备份和模式审查清单	https://alembic.sqlalchemy.org/en/latest/tutorial.html
异步 SQLAlchemy 会话、FastAPI 接线、连接池调优	ork:python-backend 技能

快速入门

# Alembic: Auto-generate migration from model changes
# alembic revision --autogenerate -m "add user preferences"

def upgrade() -> None:
    op.add_column('users', sa.Column('org_id', UUID(as_uuid=True), nullable=True))
    op.execute("UPDATE users SET org_id = 'default-org-uuid' WHERE org_id IS NULL")

def downgrade() -> None:
    op.drop_column('users', 'org_id')

-- Schema: Normalization to 3NF with proper indexing
-- PG18: prefer uuidv7() (time-ordered, better B-tree locality) over gen_random_uuid() (random v4)
CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT uuidv7(),
    customer_id UUID NOT NULL REFERENCES customers(id),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_orders_customer_id ON orders(customer_id);

Alembic 迁移

使用 Alembic 管理 SQLAlchemy 2.0 异步应用的迁移。

规则	文件	关键模式
数据迁移	rules/alembic-data-migration.md	批量回填、分两阶段设置 NOT NULL、零停机
分支管理	rules/alembic-branching.md	功能分支、合并迁移、冲突解决

自动生成配置由上游提供。我们对 Alembic 异步 env.py 模板唯一的改动（in_greenlet() 守卫）记录在 references/ork-delta.md 中。

Schema 设计

使用规范化、索引和约束模式设计 SQL 和 NoSQL Schema。

规则	文件	关键模式
规范化	rules/schema-normalization.md	1NF-3NF、何时反规范化、JSON 与规范化的取舍
索引	rules/schema-indexing.md	B-tree、GIN、HNSW、部分索引/覆盖索引
NoSQL 模式	rules/schema-nosql.md	嵌入与引用、文档设计、分片

版本管理

跨环境进行数据库版本控制和变更管理。

规则	文件	关键模式
变更日志	rules/versioning-changelog.md	Schema 版本表、语义化版本、审计记录
漂移检测	rules/versioning-drift.md	环境同步、校验和验证、迁移锁

回滚测试见 references/migration-testing.md； 有损降级的文档字符串约定见 references/ork-delta.md。

数据库选择

选择合适数据库的决策框架。默认使用 PostgreSQL。

规则	文件	关键模式
选择指南	rules/db-selection.md	PostgreSQL 优先、分级矩阵、反模式

关键决策

决策	建议	理由
异步方言	postgresql+asyncpg	为 SQLAlchemy 2.0 提供原生异步支持
NOT NULL 列	分两阶段：先允许为空，再修改	避免锁定，保持向后兼容
大表索引	CREATE INDEX CONCURRENTLY	零停机，不锁定表
规范化目标	OLTP 使用 3NF	减少冗余，同时保持查询性能
主键策略	分布式场景使用 UUID，单数据库场景使用 INT	根据上下文选择合适的键生成方式
软删除	deleted_at 时间戳列	保留审计记录，支持恢复
迁移粒度	每个文件对应一项逻辑变更	更易回滚和调试
生产部署	生成 SQL，审核后再应用	绝不在生产环境中自动运行

反模式（禁止）

# NEVER: Add NOT NULL without default or two-phase approach
op.add_column('users', sa.Column('org_id', UUID, nullable=False))  # LOCKS TABLE!

# NEVER: Use blocking index creation on large tables
op.create_index('idx_large', 'big_table', ['col'])  # Use CONCURRENTLY

# NEVER: Skip downgrade implementation
def downgrade():
    pass  # WRONG - implement proper rollback

# NEVER: Modify migration after deployment - create new migration instead

# NEVER: Run migrations automatically in production
# Use: alembic upgrade head --sql > review.sql

# NEVER: Run CONCURRENTLY inside transaction
op.execute("BEGIN; CREATE INDEX CONCURRENTLY ...; COMMIT;")  # FAILS

# NEVER: Delete migration history
command.stamp(alembic_config, "head")  # Loses history

# NEVER: Skip environments (Always: local -> CI -> staging -> production)

详细文档

资源	描述
references/ork-delta.md	我们的修正和内部约定。请先阅读
references/migration-testing.md	升级/降级周期和数据完整性测试工具
references/postgres-vs-mongodb.md	PostgreSQL 优先默认策略背后的正面对比
references/db-migration-paths.md	跨引擎迁移风险矩阵
references/cost-comparison.md	托管数据库成本分析
references/storage-and-cms.md	对象存储和 CMS 选择
scripts/	迁移模板、模型变更检测器

零停机迁移

使用扩展-收缩模式和在线 Schema 变更，在不中断服务的情况下安全更改数据库 Schema。

规则	文件	关键模式
扩展-收缩	rules/migration-zero-downtime.md	扩展阶段、回填、收缩阶段、pgroll 自动化
回滚与监控	rules/migration-rollback.md	pgroll 回滚、锁监控、复制延迟、回填进度

相关技能

• sqlalchemy-2-async - 异步 SQLAlchemy 会话模式
• ork:testing-integration - 集成测试模式，包括迁移测试
• caching - 用于补充数据库性能的缓存层设计
• ork:performance - 性能优化模式