rust-sqlx-postgres-service

Rust SQLx Postgres 服务

使用此技能以架构优先、编译检查和可测试的方式进行 Rust/Postgres 更改。优先采用显式迁移、注入连接池、精简的仓储函数，以及与业务操作相匹配的事务边界。

核心工作流

1. 更改代码前，检查 Cargo.toml、migrations/、.sqlx/、docker-compose.yml、CI，以及现有的数据库辅助模块。
2. 首先设计架构更改。先创建或更新迁移，再编写依赖该迁移的仓储代码。
3. 优先使用 sqlx::query! 和 query_as! 进行编译时 SQL 检查。仅当查询结构确实会在运行时变化时，才使用动态 SQL。
4. 显式注入 PgPool、PgConnection 或 Transaction。不要在处理程序或仓储函数中创建连接池。
5. 保持仓储函数精简，并根据行为命名。返回领域类型或持久化 DTO，而不要在应用中泄露原始行数据。
6. 对必须一起提交或回滚的多步操作使用事务。
7. 如果更改会影响 API 语义，添加或更新集成测试，以运行迁移并验证对外行为。
8. 运行内置预检脚本，或运行仓库中等效的 SQLx/Cargo CI 命令。

迁移规则

更改现有表或数据前，请阅读 references/migration-safety.md。

默认的迁移偏好：

• 首先采用增量式更改：新增可空列、新表和新索引。
• 如果表可能很大，将数据回填与架构创建分开。
• 仅在现有数据满足条件后，才添加 not null、唯一性和外键约束。
• 对会出现在错误信息或运维操作中的约束和索引，使用明确的名称。
• 如果项目使用向下迁移，就保留它们；否则，在迁移评审中说明回滚预期。

查询规则

有关 SQLx 宏、事务和离线模式的详情，请阅读 references/sqlx-patterns.md。

• 优先使用绑定参数，而不是字符串插值。
• 对按键查找的操作使用 fetch_optional。
• 如果不需要行数据，对插入和更新使用 execute。
• 如果调用方需要生成的 ID 或时间戳，使用 RETURNING。
• 对目标应恰好为一行的更新和删除，检查受影响的行数。
• 在仓储层边界附近，将数据库唯一性冲突映射为领域错误。

验证

适用标准 SQLx 工作流时，请从 Rust 项目根目录运行：

path/to/rust-sqlx-postgres-service/scripts/sqlx-preflight.sh

此脚本采取保守策略：检查格式和测试；当 CLI 和 DATABASE_URL 可用时，检查 SQLx 迁移状态；当 .sqlx/ 或 DATABASE_URL 可用时，通过 cargo sqlx prepare --check 验证 SQLx 离线元数据；并且仅在设置了 RUST_SQLX_PREFLIGHT_RUN_MIGRATIONS=1 时应用迁移。

如果仓库使用不同的 CI 命令，请运行该命令并说明原因。

参考文件

• references/sqlx-patterns.md：query!、query_as!、连接池、事务、功能标志和离线模式。
• references/migration-safety.md：安全的迁移顺序和发布检查。