using-relational-databases

关系型数据库

用途

此技能用于指导跨多种语言进行关系型数据库的选择与实现。为事务系统、CRUD 应用和结构化数据存储选择最佳数据库引擎、ORM／查询构建器及部署策略。

何时使用此技能

在以下情况下触发此技能：

• 构建用户身份验证、内容管理或电子商务应用
• 实现 CRUD 操作（创建、读取、更新、删除）
• 设计具有关系的数据模型（用户 → 帖子、订单 → 商品）
• 在生产环境中安全迁移架构
• 设置连接池以提升性能
• 评估无服务器数据库选项（Neon、PlanetScale、Turso）
• 与前端技能（表单、表格、仪表板、搜索筛选）集成

以下情况跳过此技能：

• 大规模时序数据（使用时序数据库）
• 实时分析（使用列式数据库）
• 以文档为主的工作负载（使用文档数据库）
• 键值缓存（使用 Redis、Memcached）

快速参考：数据库选择

Database Selection Decision Tree
═══════════════════════════════════════════════════════════

PRIMARY CONCERN?
├─ MAXIMUM FLEXIBILITY & EXTENSIONS (JSON, arrays, vector search)
│  └─ PostgreSQL
│     ├─ Serverless → Neon (scale-to-zero, database branching)
│     └─ Traditional → Self-hosted, AWS RDS, Google Cloud SQL
│
├─ EMBEDDED / EDGE DEPLOYMENT (local-first, global latency)
│  └─ SQLite or Turso
│     ├─ Global distribution → Turso (libSQL, edge replicas)
│     └─ Local-only → SQLite (embedded, zero-config)
│
├─ LEGACY SYSTEM / MYSQL REQUIRED
│  └─ MySQL
│     ├─ Serverless → PlanetScale (non-blocking migrations)
│     └─ Traditional → Self-hosted, AWS RDS, Google Cloud SQL
│
└─ RAPID PROTOTYPING
   ├─ Python → SQLModel (FastAPI) or SQLAlchemy 2.0
   ├─ TypeScript → Prisma (best DX) or Drizzle (performance)
   ├─ Rust → SQLx (compile-time checks)
   └─ Go → sqlc (type-safe code generation)

快速参考：ORM 与查询构建器

ORM vs Query Builder Selection
═══════════════════════════════════════════════════════════

TEAM PRIORITIES?
├─ DEVELOPMENT SPEED / DEVELOPER EXPERIENCE
│  └─ ORM (abstracts SQL, handles relations automatically)
│     ├─ Python → SQLAlchemy 2.0, SQLModel
│     ├─ TypeScript → Prisma (migrations, type generation)
│     ├─ Rust → SeaORM (Active Record + Data Mapper)
│     └─ Go → GORM, Ent
│
├─ PERFORMANCE / QUERY CONTROL
│  └─ Query Builder (SQL-like, zero abstraction overhead)
│     ├─ Python → SQLAlchemy Core, asyncpg
│     ├─ TypeScript → Drizzle, Kysely
│     ├─ Rust → SQLx (compile-time query validation!)
│     └─ Go → sqlc (generates types from SQL)
│
├─ TYPE SAFETY / COMPILE-TIME GUARANTEES
│  ├─ Rust → SQLx (queries checked at build time)
│  ├─ Go → sqlc (generates types from SQL)
│  ├─ TypeScript → Prisma or Drizzle
│  └─ Python → SQLModel (Pydantic integration)
│
└─ COMPLEX QUERIES / JOINS
   ├─ SQL-first → Query builders or raw SQL
   └─ ORM-friendly → SeaORM, SQLAlchemy ORM

多语言实现

Python：SQLAlchemy 2.0 + SQLModel

推荐库：

• SQLAlchemy 2.0 (/websites/sqlalchemy_en_21) - ORM + Core，7,090 个代码片段
• SQLModel - FastAPI 集成、Pydantic 验证
• asyncpg - 高性能异步 PostgreSQL 驱动程序

适用场景：

• 需要灵活性的生产应用
• FastAPI／Starlette 后端
• async/await 工作流

快速模式：

from sqlmodel import SQLModel, Field, Session
class User(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    email: str = Field(unique=True, index=True)

参见： references/orms-python.md，了解完整的 SQLAlchemy／SQLModel 模式、异步工作流和连接池。

TypeScript：Prisma 与 Drizzle

推荐库：

• Prisma 6.x (/prisma/prisma, score: 96.4, 4,281 doc snippets) - 最佳开发体验，支持迁移
• Drizzle ORM (/drizzle-team/drizzle-orm-docs, score: 95.4, 4,037 snippets) - 性能出色，类似 SQL

快速比较：

• Prisma：最佳开发体验、自动生成类型、内置迁移
• Drizzle：性能最佳、语法类似 SQL、零开销

参见： references/orms-typescript.md，了解 Prisma 与 Drizzle 的详细比较、Kysely 和 TypeORM 模式。

Rust：SQLx（编译时检查）

推荐库：

• SQLx 0.8 - 编译时查询验证、异步
• SeaORM 1.x - 采用 Active Record 模式的完整 ORM
• Diesel 2.3 - 成熟、稳定（同步／异步）

快速模式：

use sqlx::FromRow;
#[derive(FromRow)]
struct User { id: i32, email: String, name: String }
// Compile-time checked queries (verified at build time!)
let user = sqlx::query_as::<_, User>("SELECT * FROM users WHERE email = $1")
    .bind("[email protected]").fetch_one(&pool).await?;

参见： references/orms-rust.md，了解 SQLx 宏、SeaORM、Diesel 模式及编译时保证。

Go：sqlc（类型安全的代码生成）

推荐库：

• sqlc - 根据 SQL 查询生成 Go 代码
• GORM v2 - 支持关联和钩子的完整 ORM
• Ent - 基于图的 ORM，以代码定义架构
• pgx - 高性能 PostgreSQL 驱动程序

快速模式：

-- queries.sql: SQL annotations generate type-safe Go code
-- name: CreateUser :one
INSERT INTO users (email, name) VALUES ($1, $2) RETURNING *;

user, err := queries.CreateUser(ctx, db.CreateUserParams{Email: "[email protected]"})

参见： references/orms-go.md，了解 sqlc 设置、GORM、Ent 和 pgx 模式。

连接池

推荐连接池大小：

• Web API（单个实例）：10-20 个连接
• 无服务器（每个函数）：1-2 个连接 + pgBouncer
• 后台工作进程：5-10 个连接

参见： references/connection-pooling.md，了解配置示例、容量计算公式和监控策略。

迁移

关键原则：

1. 删除列时采用多阶段部署（绝不要在生产环境中直接删除）
2. 使用 CREATE INDEX CONCURRENTLY（PostgreSQL）以避免阻塞写入
3. 在类生产环境的数据量下，于预发布环境测试迁移

工具： Alembic (Python)、Prisma Migrate (TypeScript)、SQLx migrations (Rust)、golang-migrate (Go)

参见： references/migrations-guide.md，了解安全迁移模式、多阶段部署和回滚策略。

无服务器数据库

数据库	类型	主要特性	最适用于
Neon	PostgreSQL	数据库分支、缩放至零	开发工作流、预览环境
PlanetScale	MySQL (Vitess)	非阻塞式架构变更	MySQL 应用、零停机迁移
Turso	SQLite (libSQL)	边缘部署、低延迟	边缘函数、全球分发

参见： references/serverless-databases.md，了解设置示例、分支工作流和成本比较。

前端集成

常见集成模式：

• Forms 技能：表单提交 → API 验证 → 数据库 CRUD（INSERT/UPDATE）
• Tables 技能：分页查询 → API → 带排序/筛选功能的表格展示
• Dashboards 技能：聚合查询（COUNT、SUM）→ API → KPI 卡片
• Search-filter 技能：全文搜索（PostgreSQL tsvector）→ 排序结果

查看实际示例： examples/python-sqlalchemy/、examples/typescript-drizzle/、examples/rust-sqlx/

随附资源

参考文档

• references/postgresql-guide.md - PostgreSQL 特性（pgvector、PostGIS、TimescaleDB）
• references/mysql-guide.md - MySQL 专属模式、PlanetScale 集成
• references/sqlite-guide.md - SQLite 模式、Turso 边缘部署
• references/orms-python.md - SQLAlchemy 2.0、SQLModel、asyncpg
• references/orms-typescript.md - Prisma、Drizzle、Kysely 比较
• references/orms-rust.md - SQLx、SeaORM、Diesel
• references/orms-go.md - GORM、sqlc、Ent、pgx
• references/migrations-guide.md - 安全的架构演进模式
• references/connection-pooling.md - 连接池大小设置和监控
• references/serverless-databases.md - Neon、PlanetScale、Turso 部署

实际示例

• examples/python-sqlalchemy/ - SQLAlchemy 2.0 + FastAPI，支持连接池和迁移
• examples/typescript-prisma/ - Prisma + Next.js，包含架构和迁移
• examples/typescript-drizzle/ - Drizzle + Hono，支持类型安全查询
• examples/rust-sqlx/ - SQLx + Axum，支持编译时检查
• examples/go-sqlc/ - sqlc + Gin，生成类型安全代码

实用脚本

• scripts/validate_schema.py - 验证数据库架构结构和约束
• scripts/generate_migration.py - 为常见操作生成迁移模板

最佳实践

安全性：

• 始终使用参数化查询（防止 SQL 注入）
• 使用 Argon2/bcrypt 对密码进行哈希处理
• 使用环境变量存储连接字符串
• 在生产环境中启用 SSL/TLS

性能：

• 使用连接池（Web API 通常设置为 10-20）
• 为筛选/排序列创建索引
• 为大型结果集实现分页
• 使用 EXPLAIN ANALYZE 排查慢查询

可靠性：

• 先在预发布环境中测试迁移
• 对多语句操作使用事务
• 监控连接池耗尽情况
• 设置并测试数据库备份

开发：

• 对架构和迁移进行版本控制
• 使用数据库分支（Neon）开发功能
• 针对真实数据库编写集成测试