PostgreSQL 在 Rust 生态中的适配方案不少，但真正愿意把 SQL 写在一等公民位置的库并不多。sqlx 不要求你学习另一套查询 DSL，它接受原生 SQL 字符串，并在编译期尽可能校验语句、参数和返回类型。这意味着很多低级错误不会留到运行时，尤其适合需要精细控制查询计划、又不想失去类型安全的服务端项目。本文会从连接池、查询映射、事务和扩展类型几个方向展开，示例代码默认使用 tokio 异步运行时。
一、连接层：PgPool 如何避免阻塞与耗尽
在异步 Rust 应用里，数据库连接管理不当会让并发优势大打折扣。sqlx 提供的 PgPool 是一个异步连接池，它不会像阻塞驱动那样占用大量线程，而是通过异步等待和连接复用提升吞吐。创建连接池时最常用的入口是 PgPoolOptions，它可以设置最大连接数、最小空闲连接、获取连接超时和空闲回收时间。最大连接数并不是越大越好，PostgreSQL 默认只允许 100 个并发连接，如果应用实例很多，每个实例把池子调到 50 以上，很可能把数据库连接占满。一般建议先看数据库的 max_connections 配置，再根据实例数量和请求延迟来倒推单个池的大小。
另一个容易忽略的点是 acquire_timeout。如果不设置或设置太长，当连接池耗尽时，新的请求会一直排队，最终表现为接口超时。设置一个合理的获取超时，比如 5 秒，能让故障快速暴露。Pool 本身可以克隆，克隆成本很低，所以可以在应用启动时创建一次 PgPool，然后通过状态管理或依赖注入传递给各个 handler。下面是一段基础配置代码，展示了最小连接数、最大连接数和超时参数的设置方式。
use sqlx::postgres::PgPoolOptions;
#[tokio::main]
async fn main() -> Result<(), sqlx::Error> {
let database_url = "postgres://user:password@localhost:5432/mydb";
let pool = PgPoolOptions::new()
.max_connections(10)
.min_connections(2)
.acquire_timeout(std::time::Duration::from_secs(5))
.idle_timeout(std::time::Duration::from_secs(300))
.connect(database_url)
.await?;
let row: (i64,) = sqlx::query_as("SELECT COUNT(*) FROM users")
.fetch_one(&pool)
.await?;
println!("用户总数: {}", row.0);
Ok(())
}
连接池配置好后，每次请求不要重新创建池，而是直接克隆已有的 PgPool。克隆操作只增加引用计数，不会新建物理连接。这样可以避免启动阶段的连接风暴，也能让监控指标更稳定。对于短连接或批处理任务，可以单独创建较小的池，避免影响在线请求的可用连接数。
二、查询层：编译期校验与 FromRow 映射
sqlx 最有辨识度的能力是宏在编译期读取数据库结构。使用 query! 宏时，它会连接 DATABASE_URL 指向的数据库，或者读取 .sqlx 目录下的离线元数据，然后检查 SQL 语句里的表名、列名和参数类型是否匹配。如果某个列不存在，编译会直接失败。这个机制对于快速迭代的项目帮助很大，因为重构数据库后，很多调用点会立刻报错。不过动态拼接 SQL 无法享受编译期校验，这时只能退回到运行时 query 或 query_as 函数。
与 query! 相比，query_as 更灵活，它不需要在编译期强制连接数据库，而是把返回行映射到实现了 FromRow 的结构体。你只需要在结构体上派生 FromRow，然后保证字段名与查询结果的列名一致，类型能够被 Decode。如果查询结果可能为空，建议使用 fetch_optional 而不是 fetch_one，否则会得到一个 RowNotFound 错误。以下示例定义 User 结构体，并根据用户 ID 查询单条记录，返回 Option<User> 表示记录可能不存在。
use sqlx::FromRow;
#[derive(Debug, FromRow)]
struct User {
id: i32,
name: String,
email: String,
}
async fn get_user(pool: &sqlx::PgPool, user_id: i32) -> Result<Option<User>, sqlx::Error> {
let user = sqlx::query_as::<_, User>(
"SELECT id, name, email FROM users WHERE id = $1"
)
.bind(user_id)
.fetch_optional(pool)
.await?;
Ok(user)
}
这段代码里的 query_as 泛型参数第一个下划线表示由编译器推断数据库类型，通常固定为 Postgres，第二个参数是目标结构体 User。字段 id、name、email 必须与 SELECT 列一一对应。如果数据库返回的列比结构体字段多，sqlx 不会报错，但如果结构体中某个字段在结果集中找不到对应列，运行时会返回解码错误。因此最好让查询列与结构体字段保持严格一致，或者使用 SQL 别名来调整。
三、事务与错误处理：commit 与自动回滚
涉及多个写操作的业务，必须放在事务里。sqlx 的事务通过 pool.begin().await? 获取，返回的 Transaction 实现了 Executor，可以直接执行查询。事务对象在离开作用域时如果还没有 commit，会自动执行 rollback。这个行为让错误路径的处理变得简单：只要在需要提交的地方显式调用 tx.commit().await?，其他提前返回或问号传播都会触发 Drop 回滚，不会留下半截数据。
下面的转账示例执行两次更新，第一次扣款、第二次加款。如果第二步失败，函数通过 ? 提前返回，tx 被释放并回滚，第一步的扣款不会生效。注意 execute 方法需要传入 &mut *tx，因为 Transaction 需要以可变引用的方式执行，&mut *tx 可以解引用为内部的连接执行器。错误类型 sqlx::Error 覆盖了连接错误、解码错误、行未找到等常见情况，在实际项目中通常需要区分 Database 错误和 RowNotFound，以便返回不同的业务状态码。
async fn transfer(pool: &sqlx::PgPool, from: i32, to: i32, amount: i64) -> Result<(), sqlx::Error> {
let mut tx = pool.begin().await?;
sqlx::query("UPDATE accounts SET balance = balance - $1 WHERE id = $2")
.bind(amount)
.bind(from)
.execute(&mut *tx)
.await?;
sqlx::query("UPDATE accounts SET balance = balance + $1 WHERE id = $2")
.bind(amount)
.bind(to)
.execute(&mut *tx)
.await?;
tx.commit().await?;
Ok(())
}
如果需要更细粒度的错误控制，可以匹配 sqlx::Error::Database 并读取其中的约束名。例如唯一键冲突会包含 code 23505，检查约束冲突会有对应的约束名。把这些数据库特定错误映射成业务异常，能让接口返回更有意义的提示，而不是简单抛出 500。
四、PostgreSQL扩展类型：JSONB、数组与RETURNING
PostgreSQL 的 JSONB、数组、UUID 等类型在 sqlx 中都有对应的 Rust 映射。启用 json 特性后，JSONB 字段可以直接绑定 serde_json::Value，数组字段可以映射为 Vec<String>、Vec<i32> 等。这样就不需要手动序列化成文本再写入，查询时也能直接拿到结构化数据。需要注意 serde_json::Value 默认对应 JSON 类型，而 PostgreSQL 的 JSONB 在 sqlx 中同样作为 serde_json::Value 处理，底层驱动会负责二进制或文本协议转换。
另一个值得使用的特性是 RETURNING 子句。插入数据后想立刻拿到自增主键或完整记录，传统做法是再发一条 SELECT，但 RETURNING 可以在同一条 INSERT 语句中返回指定列。sqlx 配合 query_as 可以很方便地接收这些列，减少一次网络往返。下面示例插入一个带标签和 JSON 负载的事件，并通过 RETURNING id 直接获取新生成的 ID。这段代码还展示了如何绑定 Vec<String> 和 serde_json::Value 这类复合类型。
#[derive(Debug, FromRow)]
struct Event {
id: i32,
tags: Vec<String>,
payload: serde_json::Value,
}
async fn insert_event(pool: &sqlx::PgPool, tags: Vec<String>, payload: serde_json::Value) -> Result<i32, sqlx::Error> {
let rec = sqlx::query_as::<_, (i32,)>(
"INSERT INTO events (tags, payload) VALUES ($1, $2) RETURNING id"
)
.bind(&tags)
.bind(&payload)
.fetch_one(pool)
.await?;
Ok(rec.0)
}
使用这类扩展类型时，记得在 Cargo.toml 中开启对应特性。sqlx 的特性开关切得很细，postgres、json、macros、runtime-tokio-rustls 都需要按需添加。如果缺少 json 特性，绑定 serde_json::Value 时会在编译期报特征未实现；如果缺少 runtime-tokio 相关特性，异步运行时将无法正确驱动。
五、选型对比与总结
与 Diesel 这类基于 DSL 的 ORM 相比，sqlx 更接近底层 SQL，学习成本更低，也不需要处理复杂的 trait 派生和表结构同步。与 SeaORM 相比，sqlx 的功能范围更小，但这也意味着更少的抽象和更透明的执行计划。如果团队更习惯直接写 SQL，并且希望保留编译期检查，sqlx 会很顺手；如果项目中有大量动态构建查询的需求，则可以考虑在 sqlx 之上封装一层查询构造器。
实际使用 sqlx 时，最常见的坑并不是语法，而是异步生命周期和数据库连接检查。运行 cargo build 时如果发现 query! 宏报错，先确认 DATABASE_URL 是否可访问，或者是否需要生成离线元数据文件。另一个常见问题是连接池参数设置过高，导致测试环境超出 PostgreSQL 连接上限。把这些基础配置和错误路径理顺之后，sqlx 在 Rust 和 PostgreSQL 之间提供了一条非常高效的通道。
PostgreSQLsqlxRust修改时间：2026-09-26 19:10:57