用途
rust-database 用于在 Rust 项目中交付数据库访问层，目标是做到与迁移兼容、可回滚、可观测。它强调基于数据库真实的方言、模式和事务语义来工作，而不是把 HTTP 处理器当作仓储层，也不使用 mock 来验证真实数据库行为。
主要能力
技能覆盖数据库访问的设计、实现、迁移、测试与运维，涉及 SQLx、Diesel、SeaORM 等访问栈，以及模式演进、事务边界、连接池等主题。它要求在修改前确认数据库契约，包括：数据库产品、精确版本、扩展、部署拓扑、读写节点；当前模式约束、索引、触发器、视图与迁移历史；SQLx、Diesel、SeaORM 等访问栈的锁定版本及其特性；Rust 工具链/MSRV、同步或异步执行模型；连接上限、实例数量、超时、事务隔离级别与一致性要求；数据量特征、热查询模式、分页策略、保留策略与归档需求；凭据来源、TLS 配置、租户边界、行级权限与审计要求；以及部署是否允许停机、双写、回填或破坏性 DDL。当无法访问真实数据库时，技能要求区分“代码/离线元数据验证”与“真实方言验证”，不得在报告中混为一谈。
使用方式
工作流分为若干步骤。首先建立当前基线，例如运行 rustc --version --verbose、cargo metadata --format-version 1、cargo tree -e features、cargo test --all-targets，并定位连接初始化、连接池配置、仓储实现、查询、迁移、测试夹具与 CI 数据库连接；执行现有迁移状态/检查命令，但未经明确授权不得运行会修改共享数据库的操作。其次保留现有访问栈，不因个人偏好重写 SQLx、Diesel 或 SeaORM，而是根据当前代码库与任务需求选择：SQLx 适用于需要直接 SQL 访问、异步查询和可选编译期查询验证的场景；Diesel 适用于类型化 DSL 查询、同步连接或已有 Diesel 模式；SeaORM 适用于异步 ORM/实体模型及相应迁移系统；原生数据库驱动保留给协议或功能不支持通用层的情况，但会扩大维护与安全审查范围。所有 API 必须与 Cargo.lock 中版本对应的文档一致，避免把最新示例直接套用到旧项目。
技能要求让模式约束强制事实：主键、唯一约束、外键、非空检查与检查约束应作为数据库保证的不可变不变量；Rust 类型表达领域语义，但不能替代数据库提供的跨进程并发保证；明确整数宽度、小数精度、时区、UUID、JSON 格式与可空性映射；所有查询绑定参数，动态标识符或排序字段只能通过允许列表和类型映射处理，不能当作普通绑定值假装安全；限制列选择，避免依赖不稳定的 SELECT * 布局；在高数据量下优先使用稳定排序策略和基于键集的分页，而非无界 offset 操作。
迁移方面，技能要求先设计迁移再改代码。每个模式变更需记录：正向 DDL 语句；新旧版本应用之间的兼容窗口；数据回填方法、批量大小与回滚点；索引构建风险与锁竞争影响；回滚或前向恢复策略；验证查询、监控指标与终止条件。采用 expand → backfill → switch → contract 的顺序。破坏性操作（删除列、更改类型、重建大表、清空数据、不可逆回填）需要明确的目标解析与授权细节。
事务方面，技能要求把事务放在完整用例内：通过应用服务或仓储工作单元发起事务，不要跨 HTTP 处理器随意提交事务；确保单个共享事务与连接集内的写入原子成功；避免事务范围内无界的用户交互，包括事务内不必要的对外 HTTP 等待；按数据库文档选择隔离级别，识别丢失更新、写偏斜、幻读等风险；只对数据库明确标识的瞬时错误重试，并设置重试次数、退避策略与幂等边界；提交失败是可能的，不能把“最后一条 SQL 成功”当作事务完成；drop/rollback 是安全网，但不替代显式控制流设计与测试实践。
数据访问接口方面，技能建议采用 application use case -> repository / unit of work port -> SQL/ORM adapter -> database 的结构。仓储方法应接受领域参数与结果，不泄漏 Web DTO；错误分类为未找到、唯一冲突、外键违反、序列化失败、超时、不可用等；保留完整错误链用于日志与诊断，同时防止敏感 SQL 参数暴露在用户响应中；批量接口必须定义排序语义、部分失败处理、幂等保证与返回行数；避免 N+1 查询，在需要预取连接或批处理时，按真实数据规模验证性能。
连接预算方面，技能要求用公式（每实例连接池上限 × 最大实例数）+ 运维连接来验证总连接预算，设置获取、连接、语句与事务超时，定义空闲/最大生命周期、健康检查与优雅关闭流程；不要每请求新建连接池，也不要让无限等待掩盖资源耗尽问题。
适用场景
适用于需要设计、实现、迁移、测试和运维 Rust 数据库访问层的项目，尤其是涉及 SQLx、Diesel、SeaORM 等访问栈，需要处理模式演进、事务边界、连接池、真实数据库验证与迁移兼容性的场景。也适用于需要明确数据库契约、连接预算、错误分类与可观测性的团队。
限制
技能明确划分了交接边界：HTTP 路由、处理器、状态码、中间件属于 rust-web；凭据、租户授权、审计日志、敏感字段暴露属于 rust-web-security；异步取消、锁、任务、阻塞隔离属于 rust-concurrency；测试分层、覆盖率指标、性能基线属于 rust-testing；特性、构建脚本、离线元数据、发布流水线属于 rust-cargo-build；类型、所有权语义、错误 trait、标准库行为属于 rust-stable。技能本身不负责这些领域。此外，当无法访问真实数据库时，只能进行代码/离线元数据验证，不能声称完成了真实方言验证。完成标准要求：数据库版本、模式、访问栈与一致性假设明确；所有查询参数化，动态标识符经允许列表过滤；迁移兼容窗口、回填策略、恢复流程与破坏性边界有文档；事务覆盖完整用例，连接预算与超时有依据；真实数据库测试验证迁移、约束、回滚与并发风险；fmt、check、test、Clippy 通过；未验证的真实数据库测试必须明确标记。