接口在单请求下一切正常。为了验证并发,我把连接池的 max_connections 调成 1,两个请求各占住连接 3 秒,再发第三个请求。预期是排队,实际返回的是 HTTP 503,响应体 {"error":"pool exhausted"},服务端日志只有一行 ERROR:pool acquire failed error=pool timed out while waiting for an open connection。
这次是我故意把池子调小,问题暴露得很干净。真实项目里更常见的是相反的情况:池子看起来够大,但某个慢查询把连接占住,后来者排队,超时后一起 503;或者事务忘了 commit,接口返回成功,数据却回滚了。数据访问这一层的问题,很少是「SQL 写错了」这么直白,多数是边界和资源没算清楚。
这篇在上一篇的路由骨架上补数据层。范围限定在 sqlx 0.8.6 加 SQLite 上:两种查询方式怎么选、池子开多大、迁移文件放哪、事务从哪开始到哪结束、错误怎么变成 HTTP 状态码。PostgreSQL 的连接串和迁移输出没有在本机实测,涉及的地方会明确标注。
先看现象:数据层的九个典型故障
数据层的故障有一个共同点:表面是 HTTP 状态码,根因却在连接、事务或 SQL 类型上。下面这张表按「看到的现象」组织,第三列是可以立刻执行的检查动作。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 并发一上来,第三个请求 503 | 池子被前两个请求占满,acquire_timeout 到期 | 看 max_connections、超时设置和慢查询 |
启动后报 no such table: items | 建表 SQL 或迁移没执行,库文件是空的 | 用 sqlite 客户端打开库,看表是否存在 |
| 接口返回 200,数据没写进去 | 事务没有 commit,tx 被丢弃后自动回滚 | 看事务结尾有没有 tx.commit().await |
query! 编译时报缺 DATABASE_URL | 该宏要在编译期连库校验 SQL 与字段类型 | 设置环境变量,或改用运行期校验的查询 |
| 插入成功但拿不到新 id | 插入和查询用了不同连接,看不到未提交的数据 | 用 RETURNING,或把两条语句放进同一事务 |
| 字段反序列化失败 | SQL 列名与结构体字段不一致,或类型不匹配 | 看 SELECT 的列名,必要时起别名 |
SQLite 报 database is locked | 多个写事务并发,或事务过长占住写锁 | 看事务范围,考虑 WAL 和串行写入 |
| 数据库错误直接变成 500,前端看不懂 | sqlx::Error 没有映射,日志与响应混在一起 | 看错误有没有统一 IntoResponse |
| 拼接 SQL 字符串「能用」 | 把用户输入直接拼进 SQL,存在注入风险 | 检查所有 SQL 是否用 .bind() |
这张表里最容易被误判的是第三条。事务不 commit 不一定报错,接口可能照常返回 200,因为语句本身执行成功了,只是没有落到磁盘。SQLite 和 PostgreSQL 都遵循这个行为:事务对象在 drop 时如果没有 commit,就回滚。所以「写了没生效」先看事务边界,不要先怀疑数据库。
「database is locked」和「pool timed out」看起来都像数据库忙,处理方式却不同:前者是 SQLite 的写锁冲突,通常要把写事务变短或改成串行;后者是应用侧连接池没有空闲连接,先查慢查询和池子参数。日志里如果不带错误类型,只写一句「数据库错误」,这两种情况就会被混在一起,排查方向也会跑偏。
两种查询:query! 与 query_as
这一篇沿用上一篇的依赖,只把 sqlx 的特性补全:行映射需要 derive,迁移宏需要 migrate,query! 宏需要 macros。
[dependencies]
sqlx = { version = "0.8.6", features = ["runtime-tokio", "sqlite", "derive", "migrate", "macros"] }
cargo add sqlx@0.8.6 --features runtime-tokio,sqlite,derive,migrate,macros
cargo run
sqlx 提供两条查询路线。query! 是编译期校验的宏:写 SQL 时,编译器会连接 DATABASE_URL 指向的数据库,确认表、列、类型都对,然后把结果映射成一个匿名结构体。好处是 SQL 写错在编译期就暴露;代价是构建机必须能连到数据库,CI 里需要额外的准备,离线构建还要生成缓存文件。
query_as 是运行期校验:把 SQL 字符串和结构体交给 sqlx,运行时执行,字段对不上就在那一刻报错。它不要求编译期连库,适合库结构经常变、或者构建环境没有数据库的场景。代价是错误发现得晚,拼错的列名要等到请求打过来才知道。
query! 编译期校验
SQL 与 Rust 类型在编译期对齐,重命名列、改类型会立刻编译失败;适合表结构稳定、CI 能提供数据库的项目。代价是构建依赖数据库,迁移和代码的先后顺序要安排好;宏生成的是匿名类型,跨函数传递时要额外处理。
query_as 运行期校验
不要求编译期连库,构建简单;结构体可以显式定义并复用,适合分层和测试。代价是 SQL 错误要到运行时才暴露,字段名不一致时表现为反序列化失败,需要靠集成测试兜底。
我在这套示例里用 query_as,原因是工程要在 Windows 本机随时构建,不想让编译依赖一个正在运行的数据库。等表结构稳定、CI 里能起一个测试库之后,再把核心查询换成 query!,收益是编译期就能拦住大部分低级错误。这个切换不需要重写业务,只改查询那一行和结构体的来源。
query! 的编译期连接、sqlx::migrate! 的实际输出,这两项我没有在本机实测。下面给的迁移目录和命令按 sqlx 0.8 的官方行为书写,首次使用前请在自己的环境里跑一遍,确认 _sqlx_migrations 表和版本记录符合预期。不管选哪条路线,SQL 参数都不要拼接字符串。sqlx 的 .bind() 会把值作为参数传给数据库驱动,驱动负责转义和类型处理。拼接字符串则把用户输入当成 SQL 的一部分,一个带引号的姓名就能改变语句结构。这个风险不是「小心一点」能解决的,应该用代码规范直接禁掉字符串拼接。
连接池:池子不是越大越好
连接池(connection pool)是一组预先建立、可复用的数据库连接。每个请求需要数据库时从池子里借一条,用完归还,避免每次请求都重新握手。池子的两个关键参数是 max_connections(最多同时借出多少条)和 acquire_timeout(借不到时最多等多久)。
本文开头的 503 就是这两个参数共同作用的结果。完整复现配置如下:
use std::time::Duration;
use sqlx::sqlite::SqlitePoolOptions;
let pool = SqlitePoolOptions::new()
.max_connections(1)
.acquire_timeout(Duration::from_secs(1))
.connect("sqlite://app.db?mode=rwc")
.await
.expect("open sqlite");
用两个各占住连接 3 秒的请求把池子占满,第三个请求在 1 秒后放弃等待,返回 503,日志是:
HTTP/1.1 503 Service Unavailable
content-type: application/json
{"error":"pool exhausted"}
ERROR rustdemo: pool acquire failed error=pool timed out while waiting for an open connection
这段证据说明两件事。第一,池子满时请求不会无限等,acquire_timeout 是保护;第二,超时必须以可识别的错误暴露出来,否则客户端只会看到一个没有上下文的 503。把 sqlx::Error::PoolTimedOut 单独映射成 503,其他数据库错误映射成 500,是这一层最基本的错误分类。
池子开多大,取决于数据库能接住多少并发,而不是应用想要多少。SQLite 是单写者模型,写事务同时只能有一个,把 max_connections 开到几十并不会提高写入吞吐,只会让更多请求排队;读多写少的场景可以适当放大,但要配合 WAL 模式。PostgreSQL 的经验值通常从 CPU 核数的个位数倍数开始,再观察数据库的活跃连接、等待事件和应用侧的排队时间,逐步调整。
触发调整的信号很具体:如果日志里频繁出现 pool timed out,先看是不是有慢查询占住连接,而不是直接调大池子;如果数据库 CPU 已经接近饱和,调大池子只会把压力更多压给数据库。池子是缓冲,不是产能。把池子调大之前,先确认每条查询都能在可接受时间内归还连接。
还有一个容易忽略的边界:一个请求里如果串行执行多条查询,它会一条一条借还连接,但如果在事务里,整段事务会占住同一条连接。事务越长,占住连接越久,池子的有效容量越小。这也是为什么事务里不要做网络调用、不要等用户输入。
测试池子行为时,故意把参数调到极端比「感觉够用」更有效:max_connections(1) 加 1 秒超时,能在几秒内复现排队和超时;把池子调回正常值,再用压测工具逐步加并发,观察延迟曲线在哪个点开始抬升。这个拐点比任何经验值都更贴近你的查询和机器。
迁移与启动建表
表结构要有版本,不能靠人记忆。sqlx 的迁移机制是:在 migrations/ 目录放按时间命名的 SQL 文件,启动时调用 sqlx::migrate!,它会按文件名顺序执行未应用的迁移,并在 _sqlx_migrations 表里记录版本。已经执行过的文件不会重复执行,所以同一份迁移可以在多次启动中安全调用。
对应的启动代码大致如下。sqlx::migrate! 的路径是相对当前源文件或项目根目录的,先用 ./migrations,跑不通再按错误提示调整:
sqlx::migrate!("./migrations")
.run(&pool)
.await
.expect("run migrations");
这套机制的具体输出、_sqlx_migrations 表的结构,我没有在本机实测。本机验证用的最小方案是启动时执行 CREATE TABLE IF NOT EXISTS,这样不依赖迁移宏也能把表建出来:
sqlx::query(
"CREATE TABLE IF NOT EXISTS items (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL
)",
)
.execute(&pool)
.await
.expect("create table");
CREATE TABLE IF NOT EXISTS 适合单机、单表的起步阶段,不适合长期演进:加列、改类型、回滚都没有版本记录。项目一旦有第二个环境,就该切到迁移文件。迁移的纪律只有一条:已经上线的迁移文件不要改,要改就新增一个。改旧文件会让开发库和生产库的结构悄悄分叉,排查时非常难。
迁移的执行顺序由文件名决定,所以多人协作时不要让两个分支产生同名或时间倒序的文件。合并前先拉最新代码,确认自己的迁移排在最后;上线前在空库上完整跑一遍,确认从零建库和增量升级都能通过。迁移失败时不要手工改生产库再继续,先让服务停在启动失败状态,把问题带回开发环境复现。
事务:begin 到 commit 之间
事务(transaction)是一组要么全部成功、要么全部不生效的数据库操作。sqlx 的用法是从池子里 begin() 拿到一个事务对象,所有语句在它上面执行,最后 commit() 提交;中途任何一步返回错误、函数提前返回,事务对象被丢弃,数据库自动回滚。
下面的例子把「插入商品」和「写审计记录」放在同一个事务里。注意每条语句都用 &mut *tx 借用事务连接,而不是直接用 &pool:
async fn create_item(
State(state): State<AppState>,
Json(input): Json<NewItem>,
) -> Result<(StatusCode, Json<Item>), ApiError> {
let mut tx = state.pool.begin().await?;
let item = sqlx::query_as::<_, Item>(
"INSERT INTO items (name) VALUES (?) RETURNING id, name",
)
.bind(&input.name)
.fetch_one(&mut *tx)
.await?;
sqlx::query("INSERT INTO audit (item_id, action) VALUES (?, ?)")
.bind(item.id)
.bind("create")
.execute(&mut *tx)
.await?;
tx.commit().await?;
Ok((StatusCode::CREATED, Json(item)))
}
这段代码里,? 运算符会在任何一条语句失败时提前返回,tx 随即离开作用域并被 drop,数据库回滚。这就是「不 commit 会回滚」的实际机制,不是框架额外做的判断。RETURNING 让插入和取回新 id 在同一条语句、同一个事务连接上完成,避免了「插入用连接 A、查询用连接 B,结果看不到未提交数据」的问题。
事务的边界要尽量短。事务里不要做 HTTP 调用、不要发消息、不要等外部回调,因为这些操作可能耗时几秒,期间连接一直被占着,池子的可用容量直接减少。正确做法是把外部调用挪到事务外:先在事务里写库并提交,再发消息;如果消息失败,用补偿任务或重试表处理,而不是把事务拉长。
database is locked。单机服务里最实用的做法是缩短事务、把写操作串行化,或者开启 WAL 模式让读写不互相阻塞。WAL 的具体配置我没有在本机实测,部署前先用并发脚本验证自己的读写比例。需要提前回滚时,可以显式调用 tx.rollback().await?,比依赖 drop 更容易读;但大多数场景用 ? 提前返回就够了。嵌套事务在 SQLite 里表现为保存点,sqlx 的事务对象不直接提供嵌套 API,业务上更推荐把大事务拆成几个独立的小事务,减少锁持有时间。
错误映射与边界
数据层的最后一块是把 sqlx::Error 翻译成 HTTP 响应。如果不翻译,Axum 会把它当成未处理的错误,返回 500 加一段默认文本,日志里也缺少结构化字段。下面这个 ApiError 覆盖三类:找不到、池子超时、其他数据库错误。
use axum::{
http::StatusCode,
response::{IntoResponse, Response},
Json,
};
use serde_json::json;
enum ApiError {
NotFound,
PoolExhausted,
Db(sqlx::Error),
}
impl From<sqlx::Error> for ApiError {
fn from(error: sqlx::Error) -> Self {
match error {
sqlx::Error::PoolTimedOut => ApiError::PoolExhausted,
other => ApiError::Db(other),
}
}
}
impl IntoResponse for ApiError {
fn into_response(self) -> Response {
match self {
ApiError::NotFound => (
StatusCode::NOT_FOUND,
Json(json!({ "error": "not found" })),
)
.into_response(),
ApiError::PoolExhausted => (
StatusCode::SERVICE_UNAVAILABLE,
Json(json!({ "error": "pool exhausted" })),
)
.into_response(),
ApiError::Db(error) => {
tracing::error!(error = %error, "database error");
(
StatusCode::INTERNAL_SERVER_ERROR,
Json(json!({ "error": "internal" })),
)
.into_response()
}
}
}
}
这个映射有三个刻意的选择。池子超时返回 503 而不是 500,因为它是暂时性的,客户端可以退避重试;数据库内部错误返回 500,并且只对外暴露 internal,具体 SQL 和错误信息只写日志,避免泄露表结构;NotFound 单独构造,因为它不是数据库错误,而是业务上「这一行不存在」。
日志里 error = %error 会把 sqlx::Error 的 Display 输出记下来,这对排查「是连接断了还是 SQL 错了」很有用。但不要把整条 SQL 和参数一起打进日志,尤其是包含用户数据的语句,日志系统往往比数据库更容易被更多人看到。
还有一点:From<sqlx::Error> 不要把所有错误都吞成 500。连接断开、池子超时、唯一键冲突、语法错误,这四类对客户端的意义完全不同。至少把「可重试」和「不可重试」分开,前者 503,后者 400 或 500,监控才能按状态码做告警。
边界方面,这套方案适合单机、数据量中等的服务。SQLite 的写入吞吐有上限,多个写事务会排队;需要横向扩展时,数据库要换成 PostgreSQL 或 MySQL,连接池参数、迁移语法、RETURNING 的支持都要重新验证。代码里的 ApiError 和查询写法可以保留,换的主要是连接串和少量方言。PostgreSQL 的连接字符串与迁移输出我没有在本机实测,不在这里给具体示例。
当天能自己验证的练习
- 把
max_connections设为 1、acquire_timeout设为 1 秒,写一个睡眠 3 秒再查库的接口,同时发两个请求占住连接,再发第三个,复现 503 和日志里的pool timed out。 - 写一个事务接口,先故意删掉
tx.commit(),请求后查询表确认数据不存在;再补上 commit,确认数据出现,理解 drop 回滚。 - 把一条查询的列名改错,分别用
query_as和query!,记录前者在运行时失败、后者在编译期失败的不同时机。 - 用
.bind()和字符串拼接各写一条按名字查询的语句,输入一个带单引号的名字,对比行为并解释注入风险。 - 把
ApiError的三个分支分别触发一次:查不存在的 id、打满池子、故意写一条错误 SQL,确认返回 404、503、500,且日志字段可读。
数据层写稳之后,下一篇处理身份。接口一旦对外,就必须回答「这个请求是谁发的」。无状态令牌怎么签发、放在哪个头、签名怎么比较、过期和吊销怎么办,这些会直接影响后面所有的权限判断。下一篇会用本机实测的登录与鉴权返回,把这条链路跑通。
小结
三句话收束:query! 编译期校验但要求连库,query_as 运行期校验但构建简单,按团队环境选;池子的 max_connections 和 acquire_timeout 要一起看,池满超时应映射成 503,调大之前先查慢查询;事务从 begin 到 commit,不 commit 就回滚,事务里不要做慢的外部调用。
把 ApiError 和建表逻辑留在工程里,下一篇的登录接口会直接复用这套错误映射,不需要再写一遍。