用途:在 Rust 应用中直接编写显式 SQL,并通过 sqlx 完成连接池、查询、迁移与事务管理,适合使用 tokio 运行时、axum 等框架的持久化层。
主要能力:sqlx 负责连接池、query、query!、FromRow;sqlx-cli 负责 migrate 与 prepare。支持 Postgres、SQLite 等数据库特性,需保留对应 database feature。查询使用绑定参数(如 $1),避免字符串拼接 SQL。有编译期数据库或 CI 中执行 .sqlx prepare 时,可用 query! / query_as! 做编译期检查;否则用 query_as::<_, Row> 并配合能感知列变更的测试。
使用方式:迁移文件放在 migrations/ 目录,如 20240101120000_create_orders.sql,使用 sqlx migrate 执行,已应用的迁移文件不应再编辑。查询代码靠近领域模块,例如 src/db.rs 放连接池与类型,src/db/orders.rs 放聚合查询。复合写入使用 Transaction 并显式 commit。连接池放入应用 State,设置 acquire timeout,最大连接数与生产环境对齐。读取使用 FromRow 结构体,不把原始行直接暴露到 API JSON。
适用场景:Postgres/MySQL/SQLite 持久化、多租户(WHERE 中带 tenant_id)、软删除过滤、Postgres 枚举与 Rust 枚举映射(sqlx::Type)等。
限制与注意:不要在同一聚合中混用 sqlx 与其他 ORM;不要每个请求新建连接池;不要用未类型化查询替代全部检查;错误映射上 RowNotFound 对应 404,唯一约束冲突对应 409,不向客户端泄露 SQLSTATE。离线或 CI 可用 SQLX_OFFLINE=true 配合已提交的 cargo sqlx prepare,prepare 过期会导致 CI 失败。测试可用 Testcontainers 或 sqlite in-memory,并复用相同迁移,覆盖无结果与唯一冲突场景。资料未提供具体版本、价格或平台信息。