罗罗编程学习记录
本页内容 展开查看

04.4.8.1 SQLx 查询宏与运行时

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.4 Rust / 04.4.8 数据访问

04.4.8.1-001 query! 宏与 query 函数的核心差异是什么?

一句话结论

sqlx::query! 是编译期宏:编译时连开发库(或读离线元数据)校验 SQL 并由数据库返回列信息,自动生成返回类型;sqlx::query 是运行时函数:SQL 字符串原样下发,列与类型在运行时从 Row 手动解码,编译期不校验 SQL。

概念解释

两者都走同一套异步执行与参数绑定管线,区别只在「校验时机」和「类型推导」。宏版本依赖 macros feature,需要在编译期可访问数据库 schema;函数版本不依赖编译期数据库,适合 SQL 完全动态、或编译环境无法连库的场景。宏版本返回匿名记录类型,函数版本返回通用 Row,需要配合 query_as 或手动 row.try_get。

原理流程

  1. 宏展开时读取 SQL 文本与绑定参数类型,向数据库(或 .sqlx 离线缓存)发起 prepare。
  2. 数据库返回列名、类型、可空性,宏据此生成结构体字段与 Rust 类型。
  3. 函数版本不做 prepare 校验,运行时把 SQL 与绑定参数发给服务端。
  4. 结果行通过 FromRow 或 try_get 在运行时解码,类型不匹配会在取数时报错。

代码或图示

// 宏:编译期校验,返回匿名记录,字段名来自列名
let row = sqlx::query!("SELECT id, name FROM users WHERE id = $1", id)
    .fetch_one(&pool)
    .await?;

// 函数:运行时下发,手动解码
let row = sqlx::query("SELECT id, name FROM users WHERE id = $1")
    .bind(id)
    .fetch_one(&pool)
    .await?;
let name: String = row.try_get("name")?;

常见误区

  • 以为 query! 不需要数据库也能在本地编译:默认需要开发库,离线模式依赖 .sqlx 元数据。
  • 以为函数版本和宏版本性能有本质差别:性能差异主要来自语句缓存与解码方式,而非校验时机。

追问

  • 想把结果直接映射到已有结构体用哪个?答:宏用 query_as!,函数用 query_as::<_, T>。
  • SQL 字符串在运行时才拼出来怎么办?答:只能走 query / query_as 函数版本或 QueryBuilder,宏要求 SQL 字面量在编译期可见。

04.4.8.1-002 SQLx 在 Rust 数据访问生态里的定位是什么?

一句话结论

SQLx 是「异步纯 Rust SQL 工具包」,不是 ORM:它直接写 SQL,提供编译期查询校验、类型映射、内置连接池与迁移工具,不做表到对象的关系映射与关联预加载。

概念解释

与 Diesel 这类 DSL/ORM 不同,SQLx 不把表操作翻译成链式表达式,而是让开发者写原生 SQL,再通过宏或 FromRow 把行映射到结构体。它支持 PostgreSQL、MySQL/MariaDB、SQLite,驱动以纯 Rust 实现为主(SQLite 驱动内部依赖 C 绑定,待确认:具体绑定实现以 docs.rs 当前版本为准)。定位决定了它更适合「熟 SQL、想保留 SQL 控制力、又要类型安全」的后端项目。

原理流程

  1. 选择后端 feature 与异步运行时 feature,装配驱动与连接池。
  2. 业务代码写 SQL 文本,通过宏或函数提交。
  3. 驱动完成协议交互、语句准备与缓存、行流式读取。
  4. 解码层按 Rust 类型把列值转成 Option<T> / T,映射到结构体。

代码或图示

SQLx 定位分层
├── 驱动层:Postgres / MySql / Sqlite 协议实现
├── 连接层:Pool、Connection、Transaction、语句缓存
├── 查询层:query/query_as/query! 系列、QueryBuilder
├── 映射层:FromRow、Type、Encode、Decode
└── 工程层:migrate 迁移、sqlx::test 测试、离线元数据

常见误区

  • 把 SQLx 当成轻量 ORM:它没有 model 关联、has_many 预加载那套抽象。
  • 以为 SQLx 屏蔽了方言:占位符、枚举、JSON 类型仍需按后端方言处理。

追问

  • 项目要求复杂对象关联预加载,SQLx 够吗?答:需要自己用多次查询或 join 组装,关联预加载能力弱于 Diesel/SeaORM。
  • SQLx 支持 MSSQL 吗?答:旧版本曾支持,0.7 之后 MSSQL 驱动已移除重写,当前以 docs.rs 当前版本为准。

04.4.8.1-003 Cargo.toml 中 SQLx 的 feature 体系怎么拆?

一句话结论

SQLx 的 feature 分成三类:异步运行时与 TLS(如 runtime-tokio-rustls)、数据库后端(postgres/mysql/sqlite)、额外类型与工具(chrono/uuid/json/migrate/macros/derive 等),按需开启,避免编译不需要的驱动。

概念解释

运行时 feature 决定挂在哪个异步执行器上、用哪个 TLS 栈:常见组合是 Tokio + rustls,也有 Tokio + native-tls、async-std 组合。后端 feature 决定编译进哪个驱动。类型扩展 feature 把对应 crate 的类型接入编解码;macros 提供 query! 系列,derive 提供 FromRow/Type/Encode/Decode derive,migrate 提供迁移管理与 migrate! 宏。

原理流程

  1. 在 [dependencies] 里选一个运行时 TLS 组合作为必填项。
  2. 按目标数据库勾选对应后端 feature。
  3. 按字段类型需要勾选 chrono/uuid/json/time/bigdecimal 等。
  4. 用到宏或 derive 时再开 macros/derive,启动迁移时开 migrate。

代码或图示

[dependencies]
sqlx = { version = "0.8", features = [
    "runtime-tokio-rustls",
    "postgres",
    "chrono",
    "uuid",
    "json",
    "macros",
    "derive",
    "migrate",
] }

常见误区

  • 同时开多个后端:包体积与编译时间上升,还可能引入类型歧义。
  • 开了 chrono 又用 time 类型:两者并存时宏的类型选择以 feature 优先级与文档为准,混用容易解码报错。

追问

  • 只连 MySQL 却开了 postgres feature 有什么问题?答:多编一份驱动,且离线元数据与类型映射容易混淆,应关闭。
  • macros 与 derive 能只开一个吗?答:可以;只用手写 query/FromRow 时不必开 macros,不用 derive 时不必开 derive。

04.4.8.1-004 三种数据库后端与 Any 驱动如何取舍?

一句话结论

确定只连一种数据库就直接用 Pool<Postgres> / Pool<MySql> / Pool<Sqlite>,拿编译期类型保证;需要同一套代码在运行时按连接串切换驱动,才用 Any 后端与 AnyPool,代价是类型与方言能力被收敛到公共子集。

概念解释

单后端模式下,查询类型、错误类型、列类型都绑定具体后端,宏校验也针对该方言。Any 是一个运行时驱动抽象:连接串 scheme 决定实际后端,AnyConnection 在内部分发到对应后端实现。Any 适合中间件、通用框架等需要兼容多库的场景;业务系统通常不建议为了「以后可能换库」而提前上 Any。

原理流程

  1. 勾选对应后端 feature;使用 Any 时额外启用 any feature。
  2. Pool::connect 根据 URL scheme 选择驱动后端。
  3. 查询通过 Executor 下发,Any 层做后端适配与错误归一。
  4. 解码时只能依赖三端公共类型,后端特有类型需要降级处理。

代码或图示

// 单后端
let pool: sqlx::PgPool = sqlx::PgPool::connect(&url).await?;

// Any 后端:运行时按 scheme 选择 postgres / mysql / sqlite
let pool: sqlx::AnyPool = sqlx::AnyPool::connect(&url).await?;

常见误区

  • 以为 Any 能抹平方言差异:占位符、JSON、枚举、分页语法仍需自己兼容。
  • 在业务核心路径默认 Any:丢失单后端的类型检查与宏校验精度。

追问

  • AnyPool 与 Pool<AnyConnection> 是什么关系?答:AnyPool 是 Pool<Any> 的类型别名,内部连接为 AnyConnection。
  • 同一进程能混连两种数据库吗?答:可以分别建立 PgPool 与 MySqlPool,但不要把它们塞进同一个 AnyPool 后期望方言互通。

04.4.8.1-005 连接串格式与 DATABASE_URL 分别是什么样?

一句话结论

连接串按后端 scheme 组织:postgres://、mysql://、sqlite://,常见字段含用户名、密码、主机、端口、库名与参数;SQLx 约定从环境变量 DATABASE_URL 读取,宏与 CLI 默认都认这个变量。

概念解释

PostgreSQL 形如 postgres://user:password@host:port/dbname,也支持 postgresql:// scheme;MySQL 形如 mysql://user:password@host:port/dbname;SQLite 形如 sqlite://path/to/db.sqlite,内存库常用 sqlite::memory:。连接串尾部可带 ?sslmode=require 等参数。密码含特殊字符时需要 URL 编码。DATABASE_URL 是约定俗成的环境变量名,并非 SQLx 独有,CLI 与测试同样依赖它。

原理流程

  1. 启动程序时读取 DATABASE_URL 环境变量(常由 dotenvy 从 .env 载入)。
  2. 连接选项解析 scheme,选择对应后端驱动。
  3. 解析主机、凭证、库名与查询参数,建立连接。
  4. 宏在编译期也读取同一变量去 prepare 查询。

代码或图示

postgres://app:secret@db.internal:5432/shop?sslmode=require
mysql://app:secret@db.internal:3306/shop
sqlite://./data/shop.sqlite?mode=rwc
sqlite::memory:

常见误区

  • 密码里有 @、/ 未编码,导致解析错位。
  • 把生产库连接串写进源码或提交进版本库;应放环境变量或 .env(.env 进 .gitignore)。

追问

  • 连接超时、SSL 模式能在连接串里配吗?答:部分可在串上配,精细控制用各后端的 ConnectOptions 类型,以 docs.rs 当前版本为准。
  • SQLite 的 mode=rwc 是什么含义?答:打开读写并在文件不存在时创建;具体取值以后端文档为准。

04.4.8.1-006 .env 与 dotenvy 加载 DATABASE_URL 的顺序要注意什么?

一句话结论

通常在 main 最开头调用 dotenvy::dotenv()(或等价加载)把 .env 中的变量注入进程环境,再读 DATABASE_URL;宏在编译期由 cargo 构建脚本阶段读取环境变量,与运行时加载不是同一时机,离线/在线编译都要保证变量可见。

概念解释

dotenvy 在程序启动时解析项目根的 .env,覆盖或补齐环境变量;运行时 Pool::connect 读到的是进程环境。但 query! 宏在 cargo 编译阶段执行,此时若终端未导出 DATABASE_URL、也没有 .env 被构建工具加载,宏会因连不上库而报错。CI 中要么注入环境变量,要么走离线元数据。

原理流程

  1. 本地开发:.env 写 DATABASE_URL,main 开头 dotenvy::dotenv().ok()。
  2. 编译期:宏需要环境里有 DATABASE_URL(或离线模式),IDE 与 cargo 各自的环境要对齐。
  3. 运行期:进程环境变量被连接池读取建立连接。
  4. 部署环境:由容器环境变量或密钥管理注入,不依赖 .env 文件。

代码或图示

// main 入口尽早加载
fn main() -> Result<(), sqlx::Error> {
    dotenvy::dotenv().ok();
    let url = std::env::var("DATABASE_URL")?;
    // ... 构建运行时与连接池
    Ok(())
}

常见误区

  • 先建连接池再 dotenv():读到的是空变量。
  • 以为运行时 .env 加载了,编译期宏就能连上库:两者时机不同。

追问

  • .env 该不该提交仓库?答:不应提交真实凭证;可提交 .env.example 列出需要的变量名。
  • 多环境配置怎么区分?答:按环境加载不同文件(如 .env.development),或直接由部署平台注入环境变量。

04.4.8.1-007 Pool<DB>、AnyPool 与单连接 Connection 有什么区别?

一句话结论

Pool<DB> 是可克隆共享的连接池,AnyPool 是多后端池别名,Connection 是单条物理连接;Web 服务全局共享池,业务代码从池里借连接,只有长事务或批量脚本才直接持有单连接。

概念解释

池内部维护空闲连接队列与在借计数,Pool 自身实现 Clone,可放进应用状态到处传递;借连接通过 acquire 得到 PoolConnection,归还发生在其 drop 时。Connection 没有池化复用,反复建立/销毁成本高,且一次只能服务一条链路。AnyPool 对应 Pool<Any>,内部连接是 AnyConnection。

原理流程

  1. 启动时用 PoolOptions 构建池,按最小连接数预热。
  2. 请求到达时从池里 acquire 一个连接。
  3. 查询执行完,连接包装器 drop,连接回到空闲队列。
  4. 池关闭后再借连接会返回 PoolClosed 类错误。

代码或图示

let pool = sqlx::postgres::PgPoolOptions::new()
    .max_connections(10)
    .connect(&url)
    .await?;

// Pool 可克隆,放入 axum State
let conn = pool.acquire().await?; // 显式借连接
let row = sqlx::query("SELECT 1").fetch_one(&pool).await?; // 也可直接传池

常见误区

  • 把 Connection 放进全局状态长期持有:失去并发复用。
  • 以为传 &pool 和传 &mut conn 完全等价:前者每次取借连接,后者复用已借连接。

追问

  • 池包装器 drop 时连接一定归还吗?答:正常 drop 归还;若连接中途出错被判定不可用,池会丢弃并重建。
  • 一个请求里多次查询该传池还是传连接?答:同一事务内必须传同一个 &mut tx;无事务的多次独立查询可传池,由池决定复用哪条连接。

04.4.8.1-008 连接串之外,ConnectOptions 能控制哪些细节?

一句话结论

连接串负责基本定位与凭证,精细控制(连接超时、语句缓存、TLS 配置、应用名等)走各后端的 ConnectOptions 类型构建后再传给池;不同后端的选项字段不完全一致。

概念解释

Postgres 对应 PgConnectOptions,MySQL 对应 MySqlConnectOptions,SQLite 对应 SqliteConnectOptions。它们提供 TLS、statement cache、应用名、命令选项等设置。连接串能表达常见参数,复杂场景(自定义 TLS 根证书、关闭语句缓存、设置后端参数)需要结构化选项。具体字段名以后端 docs.rs 当前版本为准,不确定项标注待确认。

原理流程

  1. 从 URL 解析出基础选项,或直接 ::new()。
  2. 链式调用选项方法设置超时、TLS、缓存等。
  3. PoolOptions::connect_with(options) 用选项建池。
  4. 每条新连接按同一选项模板建立。

代码或图示

use sqlx::postgres::PgConnectOptions;

let opts = PgConnectOptions::new()
    .host("db.internal")
    .database("shop")
    .username("app")
    .password("secret");

let pool = sqlx::postgres::PgPoolOptions::new()
    .max_connections(10)
    .connect_with(opts)
    .await?;

常见误区

  • 在连接串里塞后端不识别的参数,被静默忽略。
  • 把所有调优都堆在池选项上:池负责复用,连接级参数归 ConnectOptions。

追问

  • 语句缓存在哪一层?答:默认在连接级别缓存预处理语句,ConnectOptions 可调整缓存容量或行为;具体配置项以文档为准。
  • 想要每条连接带统一会话参数怎么做?答:用 ConnectOptions 或 PoolOptions::after_connect 钩子执行初始化语句。

04.4.8.1-009 SQLx 与 tokio-postgres、SeaORM、Diesel 的定位差异是什么?

一句话结论

tokio-postgres 是最底层的异步协议客户端,SQLx 在其上提供池化、宏校验与多后端抽象,Diesel 是编译期 DSL ORM,SeaORM 是异步 ORM/实体框架;选型沿「底层控制 → 类型安全 SQL → ORM 抽象」递进。

概念解释

tokio-postgres 只做 Postgres 协议通信,连接池、映射、迁移都要自己组合。SQLx 收编了池、宏校验、类型映射与迁移,但 SQL 仍由人写。Diesel 用 Rust 表达式 DSL 生成 SQL,类型检查在编译期,模型与关联抽象强,但默认同步、生态围绕 Postgres 最早成熟。SeaORM 提供实体定义、关系、查询构建器与异步运行,偏 ORM 体验。

原理流程

  1. 先确定团队对 SQL 控制力与 ORM 抽象的偏好。
  2. 只服务 Postgres 且要协议级控制,考虑 tokio-postgres。
  3. 要原生 SQL + 编译期校验 + 多后端,选 SQLx。
  4. 要强类型 DSL、模型关联与同步工程,选 Diesel;要异步实体 ORM,选 SeaORM。

代码或图示

抽象层级(由低到高)
tokio-postgres / mysql_async / rusqlite
  → SQLx(池 + 宏校验 + 类型映射 + 迁移)
    → SeaORM(实体 / 关系 / 异步查询构建器)
    → Diesel(编译期 DSL / model / 关联,默认同步)

常见误区

  • 把 Diesel 当异步库直接在 tokio handler 里跑:标准 Diesel 是同步的,异步要走 diesel-async。
  • 以为 SQLx 和 SeaORM 是同一层:SeaORM 内部可基于 SQLx 驱动,抽象层级更高。

追问

  • 已有大量手写 SQL 的项目迁到 Rust,优先哪个?答:SQLx 最平滑,SQL 文本可直接复用。
  • 团队希望少写 SQL、靠模型 CRUD,选哪个?答:SeaORM 或 Diesel 更贴合,按同步/异步偏好定。

04.4.8.1-010 为什么要用 no-default-features 裁剪 SQLx feature?

一句话结论

SQLx 默认 feature 会带上常用后端与运行时,显式 default-features = false 后按需勾选,可以避免编入用不到的驱动、TLS 栈与类型扩展,缩短编译时间、缩小产物体积。

概念解释

默认特性组合面向开箱即用,可能包含你不需要的后端或 TLS 后端。生产依赖裁剪时,先关闭默认 feature,再列出运行时、后端、类型扩展与工具宏。feature 选择还影响离线元数据目录内容:只声明实际启用的后端,prepare 生成的缓存才与构建配置一致。

原理流程

  1. 写 sqlx = { version = "0.8", default-features = false, features = [...] }。
  2. 勾选唯一运行时 TLS 组合与目标后端。
  3. 补齐字段类型与工程工具所需 feature。
  4. cargo build 后检查编译树,确认无多余驱动被拉入。

代码或图示

sqlx = { version = "0.8", default-features = false, features = [
    "runtime-tokio-rustls",
    "sqlite",
    "macros",
    "derive",
] }

常见误区

  • 关闭默认 feature 后忘了开 macros,导致 query! 找不到宏。
  • 为图省事保留默认全量 feature,产物里带上用不到的数据库驱动。

追问

  • dev-dependencies 与 dependencies 的 feature 会合并吗?答:cargo feature 是按 crate 合并的,dev 依赖开启的 feature 也会进常规构建,需要留意。
  • 裁剪后编译报「feature 未启用某类型」怎么办?答:按报错补对应后端或类型扩展 feature。

04.4.8.1-011 SQLx 的版本与 edition 前提怎么表述才稳妥?

一句话结论

面试与文档中统一表述为「Rust stable 工具链、edition 2021,SQLx 版本以 docs.rs 当前版本为准」;具体次版本 API 差异不写死,遇到版本敏感行为标注「待确认」并给验证方式。

概念解释

SQLx 跨 0.7 到 0.9 期间有错误类型、特性名、API 签名调整,写死 0.7/0.8 容易与读者本地版本不符。工程实践中应在 Cargo.toml 锁定实际版本,文档描述只保留稳定概念(池、事务、宏、迁移)。规范要求:不确定的 API 名、feature、CLI 子命令写「待确认」,并注明去 docs.rs/crates.io 核对。

原理流程

  1. Cargo.toml 声明语义化版本区间,Cargo.lock 锁定实际解析版本。
  2. 文档与题库描述稳定概念与通用流程。
  3. 版本敏感 API 在阅读源码或文档时二次核对。
  4. 升级时按 release notes 迁移签名与 feature 调整。

代码或图示

# 工程内锁定实际版本;文档不写死次版本细节
sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres"] }

常见误区

  • 把某版本才有的方法当成长期稳定 API 写入答案。
  • 看到本地版本行为与教程不一致就怀疑代码错误,实际是版本差异。

追问

  • 如何确认某个 API 是否存在于当前版本?答:查 docs.rs/sqlx 当前版本文档,或 cargo doc --open 本地生成。
  • 大版本升级要注意什么?答:先看 release notes 的迁移章节,重点核对 feature 改名、错误类型与宏行为。

04.4.8.1-012 「纯 Rust 驱动」在 SQLx 语境下意味着什么?

一句话结论

纯 Rust 指 Postgres/MySQL 协议用 Rust 实现,不依赖 libpq、libmysqlclient 这类 C 客户端库;SQLite 后端因 SQLite 本身是 C 库,仍通过绑定接入,属于例外。

概念解释

纯 Rust 驱动避免了 C 编译链、原生库链接与跨平台 ABI 问题,交叉编译更简单,内存安全边界也更清晰。但「纯 Rust」不等于零 unsafe:协议解析与绑定层内部仍可能有 unsafe,对外 API 保持安全。理解这一点可以避免在选型时把「纯 Rust」误读成「无 C 依赖」。

原理流程

  1. 驱动按数据库协议在 Rust 内完成握手、认证、消息编解码。
  2. 连接池与事务管理建立在协议连接之上。
  3. SQLite 路径通过绑定调用 SQLite C 库完成存储访问。
  4. 对外暴露统一的 Database/Connection/Executor 抽象。

代码或图示

Postgres 协议   → Rust 实现(纯 Rust)
MySQL 协议      → Rust 实现(纯 Rust)
SQLite 存储引擎 → C 库 + Rust 绑定(例外)

常见误区

  • 认为纯 Rust 驱动性能一定超过 C 客户端:实际取决于协议实现与缓存策略,需压测。
  • 以为纯 Rust 就没有 unsafe:内部实现细节不对外承诺无 unsafe。

追问

  • 交叉编译时纯 Rust 驱动有什么好处?答:不需要目标平台对应的 C 客户端开发库,工具链链上少一层原生依赖。
  • SQLite 绑定用的是哪个 crate?答:待确认,以当前 SQLx 文档依赖树为准。

04.4.8.1-013 query、query_as、query_scalar 三个运行时函数怎么选?

一句话结论

query 返回原始 Row 手动解码;query_as 把整行映射到实现 FromRow 的结构体;query_scalar 只取单列标量值;按「需要整行结构体 / 单列值 / 手动取列」选择。

概念解释

三者返回的都是可流式执行的查询对象,差异在结果映射阶段。query_as::<_, T> 在取行时尝试把列按名称或位置塞进 T;query_scalar::<_, T> 取第一列并按标量解码,适合 SELECT count(*)、SELECT id 这类单值查询。原始 query 留给需要动态读列、列结构不固定的场景。

原理流程

  1. 写 SQL 文本并 bind 参数。
  2. 选择映射方式:结构体 / 标量 / 原始行。
  3. 调用 fetch_one/fetch_optional/fetch_all/fetch 执行。
  4. 解码错误在取行阶段以 Decode 类错误返回。

代码或图示

#[derive(sqlx::FromRow)]
struct User { id: i64, name: String }

let user: User = sqlx::query_as::<_, User>("SELECT id, name FROM users WHERE id = $1")
    .bind(id)
    .fetch_one(&pool)
    .await?;

let count: i64 = sqlx::query_scalar("SELECT count(*) FROM users")
    .fetch_one(&pool)
    .await?;

常见误区

  • query_scalar 用于多列查询:它只取第一列,其余列被忽略。
  • 结构体字段名与列名不一致又不做映射:FromRow 按默认列名匹配失败。

追问

  • query_as 要求 T 实现什么?答:FromRow,通常 #[derive(FromRow)] 即可。
  • 标量是可空列时类型写什么?答:写 Option<T>,与列可空性对齐。

04.4.8.1-014 query!、query_as!、query_scalar! 宏各自生成什么类型?

一句话结论

query! 生成匿名记录结构体;query_as! 把结果映射到你指定的结构体;query_scalar! 直接生成单列标量类型;列名、类型与可空性都来自编译期数据库返回的元数据。

概念解释

宏在编译期 prepare SQL,拿到每列的名称、类型 OID、是否可空,再据此生成 Rust 类型。query! 的返回行是宏内联生成的匿名记录,字段即列名;query_as! 在生成代码里完成到目标结构体的赋值;query_scalar! 跳过行包装直接产出标量。宏要求 SQL 是字面量,参数通过 bind 位置传入。

原理流程

  1. 宏解析 SQL 字面量与参数列表。
  2. 连接开发库 prepare(或读 .sqlx 离线缓存)取列元数据。
  3. 按元数据生成记录字段与 Rust 类型,可空列包 Option。
  4. 执行阶段把行解码进生成类型或目标结构体。

代码或图示

// 匿名记录:row.id、row.name
let row = sqlx::query!("SELECT id, name FROM users WHERE id = $1", id)
    .fetch_one(&pool)
    .await?;

// 映射到已有结构体
let user: User = sqlx::query_as!(User, "SELECT id, name FROM users WHERE id = $1", id)
    .fetch_one(&pool)
    .await?;

// 单列标量
let count: i64 = sqlx::query_scalar!("SELECT count(*) FROM users")
    .fetch_one(&pool)
    .await?;

常见误区

  • 以为 query_as! 不检查结构体字段与列是否对应:不匹配仍会在编译期或取数时报错。
  • 把宏生成的匿名记录传给其它函数当具体类型用:匿名类型无法在函数签名间直接传递,需要转结构体。

追问

  • 匿名记录能赋值给结构体吗?答:不能自动转换;需要 query_as! 指定结构体,或手动构造。
  • 列别名会成为字段名吗?答:会,宏按结果列名(含 AS 别名)生成字段。

04.4.8.1-015 宏生成的匿名记录与 FromRow 结构体有什么区别?

一句话结论

匿名记录由宏按查询结果现场生成,类型只在当前作用域可见;FromRow 结构体是你自己定义、可跨函数复用的模型类型;接口边界处应暴露结构体而非匿名记录。

概念解释

匿名记录的字段集合由 SQL 决定,换一条查询字段就不同,无法作为稳定函数签名。FromRow 结构体与表/DTO 对应,可在 handler、service、测试间传递。工程实践里:内部快速取数可用匿名记录,对外返回与跨层传递一律定义结构体并用 query_as!/query_as 映射。

原理流程

  1. 写宏查询时先判断结果是否要跨函数传递。
  2. 仅当前作用域使用:接受匿名记录。
  3. 需要复用或进响应 DTO:定义结构体并 derive FromRow,用 query_as!。
  4. 重构时把匿名记录字段逐个对齐到结构体字段。

代码或图示

#[derive(sqlx::FromRow, Debug)]
struct UserSummary { id: i64, name: String }

async fn summarize(pool: &sqlx::PgPool, id: i64) -> Result<UserSummary, sqlx::Error> {
    let u = sqlx::query_as!(
        UserSummary,
        "SELECT id, name FROM users WHERE id = $1",
        id
    )
    .fetch_one(pool)
    .await?;
    Ok(u)
}

常见误区

  • 把匿名记录作为 async fn 返回类型:编译期类型写不出来,只能存成内部类型。
  • 为了省事全部用匿名记录,导致 service 层到处泄漏 SQL 列结构。

追问

  • FromRow 支持按位置还是按名称映射?答:derive 默认按列名匹配字段;位置映射需手写实现,以文档为准。
  • 结构体字段比查询列多会怎样?答:缺失列按可空性处理,非空字段取不到值会解码失败。

04.4.8.1-016 query_as! 绑定结构体时字段名与列名如何映射?

一句话结论

默认按列名与结构体字段名同名匹配(忽略大小写差异由 derive 规则处理),列名与字段名不一致时用 SQL 别名对齐,或在结构体上用字段属性指定列名。

概念解释

FromRow derive 读取结果集的列标签,与结构体字段一一对应:同名直接赋值;数据库列带下划线、字段用 camelCase 时,需要在 SQL 里 AS 成字段名,或借助 derive 属性声明映射。列缺失或类型不匹配会在编译期(宏)或解码期(函数版本)暴露。

原理流程

  1. 定义结构体,字段名对齐预期列名。
  2. SQL 中用 AS 把异构列名映射成字段名。
  3. query_as! 把列值解码到对应字段。
  4. 某列为空而字段非 Option 时返回解码错误。

代码或图示

#[derive(sqlx::FromRow)]
struct User {
    id: i64,
    display_name: String,
}

let u = sqlx::query_as!(
    User,
    "SELECT id, display_name AS display_name FROM users WHERE id = $1",
    id
)
.fetch_one(&pool)
.await?;

常见误区

  • 列名是 user_name,字段是 userName,又不写别名:匹配失败。
  • 给字段加了 serde 属性就以为 FromRow 也认:serde 与 FromRow 是两套属性,不要混用。

追问

  • 能不能给字段起个别名而不改 SQL?答:查 FromRow derive 支持的列映射属性;具体属性名以 docs.rs 当前版本为准,不确定写待确认。
  • 一个结构体映射多个查询时怎么办?答:保持字段与列命名约定一致,或为不同视图定义不同 DTO。

04.4.8.1-017 fetch_one、fetch_optional、fetch_all、fetch、fetch_scalar 有何差异?

一句话结论

fetch_one 要求恰好一行,零行报 RowNotFound、多行取第一行并视情况报错;fetch_optional 零行返回 None、一行返回 Some;fetch_all 取全部行成 Vec;fetch 返回流式 Stream;fetch_scalar 取单列标量。

概念解释

选择取决于结果基数:明确唯一用 fetch_one;可能不存在用 fetch_optional;列表用 fetch_all;大数据集用 fetch 流式拉取;单值聚合用 fetch_scalar。fetch_one 对多行的处理以当前版本文档为准,常见语义是期望单行,多行会触发错误或取首行,不要假设其静默忽略多余行。

原理流程

  1. 确定业务上结果是 0/1/多/流式。
  2. 选择对应 fetch 方法。
  3. 执行查询并按映射方式解码。
  4. 基数不符时返回对应错误或 None。

代码或图示

let one: User = query_as(...).fetch_one(&pool).await?;
let opt: Option<User> = query_as(...).fetch_optional(&pool).await?;
let all: Vec<User> = query_as(...).fetch_all(&pool).await?;
let mut stream = query_as(...).fetch(&pool); // 逐行消费
let scalar: i64 = query_scalar(...).fetch_one(&pool).await?;

常见误区

  • 可能查不到记录却用 fetch_one,把正常空结果变成 404 错误链路。
  • 大表用 fetch_all 一次性加载,内存被全部结果撑爆。

追问

  • fetch_optional 多行时行为如何?答:以当前版本文档为准;需要严格单行应加 LIMIT 1。
  • 流式 fetch 中途出错怎么处理?答:在流的 next 循环里处理 Err,并确保流被消费或丢弃以归还连接。

04.4.8.1-018 一行多列与单列标量查询分别怎么取值?

一句话结论

多列用结构体、元组或匿名记录按列读取;单列用 query_scalar/query_scalar! 直接得到标量;多列也可以按位置取元组 (T1, T2, ...)。

概念解释

SQLx 支持把行解码为元组:列顺序与元组位置一一对应,适合临时返回两三个值的统计查询。单列场景走标量路径,避免再包一层单行结构体。元组列数有限制(常用上限以文档为准,超出建议定义结构体)。列值可空时对应位置必须是 Option<T>。

原理流程

  1. 判断结果列数:一列走标量,多列走结构体或元组。
  2. 元组按 SQL 列顺序排列类型。
  3. fetch 时按位置或名称解码。
  4. 类型与可空性不匹配返回 Decode 错误。

代码或图示

let pair: (i64, String) = sqlx::query_as(
    "SELECT id, name FROM users ORDER BY id LIMIT 10"
).fetch_all(&pool).await?;

let name: String = sqlx::query_scalar(
    "SELECT name FROM users WHERE id = $1", id
).fetch_one(&pool).await?;

常见误区

  • 元组顺序与 SQL 列顺序写反:编译可能通过,运行时解码类型报错。
  • 用结构体只取一列,多写样板代码。

追问

  • 元组支持多少列?答:常见为固定上限(如 10 余个),超出定义结构体;具体数字以 docs.rs 为准。
  • 标量列是可空枚举怎么办?答:标量类型写 Option<枚举类型>,解码规则同普通列。

04.4.8.1-019 execute 与 fetch_* 的区别是什么?

一句话结论

execute 用于不关心返回行的写操作(INSERT/UPDATE/DELETE/DDL),返回 PgQueryResult 之类结果,可取 rows_affected();fetch_* 用于读取结果集,逐行解码。

概念解释

写语句没有结果集需要遍历,execute 把语句发到服务端并返回执行摘要,包括影响行数、最后插入行号(后端支持时)。读语句用 fetch 系列拿行。混用后果:写操作误用 fetch 会多走行解码路径;读操作误用 execute 则拿不到数据。

原理流程

  1. 判断语句类型:写/DDL 走 execute,读走 fetch。
  2. execute 完成后取 rows_affected 做业务判断。
  3. fetch 系列按映射方式逐行解码。
  4. 批量写可结合多行 VALUES 一次 execute。

代码或图示

let result = sqlx::query("UPDATE users SET name = $2 WHERE id = $1")
    .bind(id)
    .bind(new_name)
    .execute(&pool)
    .await?;

println!("affected: {}", result.rows_affected());

常见误区

  • 用 rows_affected() == 0 判断记录不存在:要先区分是条件未命中还是数据问题,必要时配合 fetch_optional。
  • 以为 execute 不返回行就不需要事务:多步写仍要在事务里保证一致性。

追问

  • 最后自增 ID 怎么拿?答:Postgres 用 RETURNING id 配合 fetch;MySQL 可从结果的 last insert id 取,具体 API 以后端文档为准。
  • DDL 语句能在事务里跑吗?答:取决于后端,Postgres 多数 DDL 可事务化,MySQL 部分 DDL 隐式提交。

04.4.8.1-020 各后端的占位符写法有什么不同?

一句话结论

PostgreSQL 用 $1、$2 位置占位符;MySQL 与 SQLite 用 ? 占位符;绑定顺序与占位符位置对应,跨后端移植 SQL 时首先要改占位符语法。

概念解释

SQLx 的 bind 按位置提交参数,占位符方言由后端决定。PG 命名参数支持情况以后端文档为准;MySQL/SQLite 的 ? 不编号,重复出现时按绑定先后对应。编写跨库代码时,占位符是少数无法被驱动完全抹平的方言差异之一,Any 模式下尤其要注意。

原理流程

  1. 按目标后端写对应占位符。
  2. bind 调用顺序与占位符出现顺序一致。
  3. 驱动把参数按协议编码随语句发送。
  4. 占位符数量与绑定数量不符时在 prepare 或执行阶段报错。

代码或图示

// PostgreSQL
sqlx::query("SELECT id FROM users WHERE name = $1 AND age > $2")
    .bind(name).bind(age);

// MySQL / SQLite
sqlx::query("SELECT id FROM users WHERE name = ? AND age > ?")
    .bind(name).bind(age);

常见误区

  • PG 语句里混用 ?,prepare 直接失败。
  • 多个 ? 时 bind 顺序写反,导致条件错位且不易察觉。

追问

  • 能不能用命名占位符?答:PG 驱动支持情况以文档为准;工程上通常统一位置占位符最稳妥。
  • 绑定数组展开成多个占位符怎么做?答:动态场景用 QueryBuilder 生成片段与参数,不要手写字符串拼占位符。

04.4.8.1-021 为什么宏要求参数类型可在编译期推断,动态参数列表怎么办?

一句话结论

宏在编译期要把每个绑定参数的类型发给数据库做类型校验,因此参数必须是编译期可知类型;参数数量或取值完全运行时决定时,改用 query/query_as 函数版本配合 QueryBuilder。

概念解释

query! 的参数出现在宏调用语法里,编译器能推导出 String、i64 等具体类型,宏据此生成绑定代码。运行时才决定「绑定几个参数、每个参数什么类型」的场景,宏无法展开出固定绑定列表,只能走运行时 API。这也是动态 SQL 必须退出宏路径的根本原因。

原理流程

  1. 参数固定且类型明确:使用宏,获得编译期校验。
  2. 参数数量/类型运行时变化:放弃宏。
  3. 用 QueryBuilder 按条件 append 片段与 bind。
  4. 最终 query_as 执行并映射结构体。

代码或图示

// 固定参数:宏可用
sqlx::query!("SELECT * FROM users WHERE id = $1", id);

// 参数动态:函数版本 + QueryBuilder
let mut qb = sqlx::QueryBuilder::<sqlx::Postgres>::new("SELECT * FROM users WHERE 1=1");
if let Some(name) = name_filter {
    qb.push(" AND name = ").push_bind(name);
}
let rows = qb.build_query_as::<User>().fetch_all(&pool).await?;

常见误区

  • 试图把 Vec<Value> 直接塞进宏的绑定列表:宏不接受动态参数集合。
  • 为了用宏把动态条件硬写成多条 SQL 分支,维护成本高于运行时构造。

追问

  • QueryBuilder 的 push_bind 与宏 bind 的类型检查强度一样吗?答:运行时解码校验,编译期不做 SQL 与类型对账。
  • 动态参数都是同一种类型能否简化?答:可以用数组绑定或展开占位符的 QueryBuilder 写法,具体语法以后端支持为准。

04.4.8.1-022 SQL 列名不存在或语法错误,宏在什么时机暴露?

一句话结论

宏在编译期(连库 prepare 或读离线元数据时)暴露列名不存在、语法错误、类型不匹配;函数版本则在运行时执行到该语句才报错。

概念解释

宏把 SQL 交给数据库解析器做 prepare:语法错误、表/列不存在、类型无法隐式转换都会在 prepare 阶段返回错误,宏把它转成编译错误。离线模式下,校验依据是 .sqlx 缓存的元数据;缓存过期时错误信息可能与真实库状态不符。函数版本不做 prepare 校验,问题延迟到运行时,配合测试与日志才能发现。

原理流程

  1. 编写带宏的查询,触发 cargo 编译。
  2. 宏环境连库 prepare(或读离线缓存)。
  3. 数据库返回解析/绑定错误,宏转为编译错误并标注 SQL 片段。
  4. 修复 SQL 或 schema 后重新编译;函数版本问题在运行期 Error::Database 中体现。

代码或图示

编译期(宏)
  SQL 文本 → prepare → 数据库解析 → 列/类型校验 → 生成 Rust 类型

运行时(函数)
  SQL 文本 → 下发服务端 → 执行 → 错误经 sqlx::Error 返回

常见误区

  • 以为宏报错是 Rust 类型问题,实际是数据库拒绝了 SQL。
  • 离线元数据没更新,编译通过但线上库 schema 已变。

追问

  • 离线模式下宏还能查出列名拼错吗?答:能比对缓存元数据;但缓存本身过期时,新列名错误可能查不出来。
  • 如何在 CI 保证宏校验不过期?答:CI 跑 cargo sqlx prepare --check,元数据与代码一起提交。

04.4.8.1-023 宏生成记录的字段命名与可空性规则是什么?

一句话结论

字段名取结果列名(含别名),Rust 标识符不合法时宏做规范化;列可空则字段类型为 Option<T>,非空为 T;类型映射遵循后端类型到 Rust 类型的默认规则。

概念解释

数据库列的可空性来自 prepare 返回的元数据:允许 NULL 的列在宏结果里包一层 Option,避免取出空值时直接解引用panic。字段命名按列名转换为 Rust 习惯的标识符形式;若列名是关键字或含特殊字符,需要用别名规避。想把可空列当非空使用,应在 SQL 层 COALESCE 或在结构体里自行处理。

原理流程

  1. prepare 返回每列的类型 OID 与 nullability。
  2. 按类型映射表选 Rust 基础类型。
  3. 可空列在外层包 Option。
  4. 列名规范化为合法字段名,冲突时用别名区分。

代码或图示

let row = sqlx::query!(
    "SELECT id, name, nickname FROM users WHERE id = $1", id
).fetch_one(&pool).await?;
// row.id: i64
// row.name: String
// row.nickname: Option<String>

常见误区

  • 把可空字段当成非空类型直接用,编译期就会因 Option 类型不匹配报错。
  • 列名重复(多表同名列)不写别名,生成字段冲突。

追问

  • 数据库标记可空但业务上不可能为 NULL,怎么取非空?答:SQL 用 COALESCE 给默认值,或在代码里 unwrap/ok_or 显式处理。
  • 字段名大小写怎么处理?答:以宏生成规则为准, camelCase 列建议用 AS 别名对齐结构体。

04.4.8.1-024 FromRow derive 与手写实现分别适用什么场景?

一句话结论

常规结构体用 #[derive(FromRow)] 按列名映射即可;列名异构、需要按位置解码或做字段级转换时手写 FromRow 实现。

概念解释

derive 覆盖了大多数「结构体字段 = 结果列」的场景。复杂情况包括:列名与字段名无规则对应、需要把多个列合并成一个嵌套结构、解码后做二次校验或类型转换。手写实现时从 Row 取列,调用 row.try_get 并自行处理缺失与解码错误。FromRow 与 query_as/query_as! 配合使用。

原理流程

  1. 先尝试 derive,检查字段与列名是否对齐。
  2. 映射规则不满足时移除 derive,手写 impl FromRow。
  3. 逐列 try_get,失败时返回解码错误。
  4. 嵌套结构可在实现里递归调用内部类型的 FromRow。

代码或图示

use sqlx::{FromRow, Row};

#[derive(FromRow)]
struct User { id: i64, name: String }

struct Profile { display: String }

impl FromRow<'_, sqlx::postgres::PgRow> for Profile {
    fn from_row(row: &sqlx::postgres::PgRow) -> sqlx::Result<Self> {
        let first: String = row.try_get("first")?;
        let last: String = row.try_get("last")?;
        Ok(Profile { display: format!("{first} {last}") })
    }
}

常见误区

  • 把 serde 的 rename 属性套到 FromRow 上:两套属性互不认识。
  • 手写实现时忽略列不存在错误,直接 unwrap 导致运行期 panic。

追问

  • FromRow 的生命周期参数是什么含义?答:实现绑定行类型与借用生命周期,保证解码不持有超越行的引用;具体签名以 docs.rs 为准。
  • 同一结构体被不同后端复用时怎么办?答:按后端分别实现,或用 AnyRow 抽象,注意公共类型子集。

04.4.8.1-025 多语句批处理与流式查询的边界在哪里?

一句话结论

简单 unprepared 查询可一次发送多条语句并取所有结果集;高层 query API 走预处理语句缓存并按行流式读取;批处理写操作建议用多行 VALUES 单条 execute,不要依赖多语句拼接。

概念解释

SQLx 区分高层预处理查询与简单查询路径:高层 API 自动 prepare 并按连接缓存语句;简单查询路径支持批量执行多条语句。生产代码里动态多语句拼接有注入与权限风险,批量插入优先 INSERT ... VALUES (...), (...), ...。流式读取通过 fetch 返回 Stream,逐行从网络解码,避免一次性落内存。

原理流程

  1. 判断是单条读、单条写还是批量写。
  2. 批量写构造多行 VALUES,一次 execute。
  3. 大结果集用 fetch 流式消费。
  4. 多语句仅在可信 DDL/初始化脚本场景使用。

代码或图示

// 批量插入:多行 VALUES
let mut qb = sqlx::QueryBuilder::<sqlx::Postgres>::new(
    "INSERT INTO users (name) VALUES "
);
qb.push_values(names, |mut b, name| { b.push_bind(name); });
qb.build().execute(&pool).await?;

常见误区

  • 用字符串拼接把多条 SQL 拼成一条执行,既难绑定参数又扩大注入面。
  • 误以为流式 fetch 会自动把连接归还:流未耗尽时连接仍被占用。

追问

  • 预处理语句缓存在哪一层?答:按连接缓存,缓存容量与行为由连接选项控制,以文档为准。
  • 流式消费到一半返回错误,连接怎么处理?答:丢弃流后连接回到池前会做可用性判定,坏连接被重建。

04.4.8.1-026 query! 宏的编译期校验是如何工作的?

一句话结论

编译到含宏的代码时,宏进程读取 SQL 文本与参数类型,连接开发数据库执行 prepare,由数据库解析 SQL 并返回列信息,宏据此生成 Rust 类型;这一步把 SQL 语法、表列存在性与类型可绑定性提前到编译期检查。

概念解释

校验主体是数据库本身,SQLx 不内置 SQL 解析器:宏只是把语句发给服务端做 prepared statement 解析。参数类型按绑定位置编码发送,数据库据此校验类型兼容。校验需要编译期环境可访问开发库;离线模式下改为读取 .sqlx 目录中缓存的 prepare 元数据,不再连库。

原理流程

  1. cargo 编译到宏调用,宏展开为构建期检查逻辑。
  2. 读取 DATABASE_URL,连接开发库(或走离线缓存)。
  3. 发送 prepare,数据库返回列名、类型、可空性。
  4. 宏生成对应 Rust 代码;prepare 失败转为编译错误。
  5. 正常编译产物运行时只做执行与解码。

代码或图示

源码 query!("SELECT id, name FROM users WHERE id = $1", id)
  → 编译期 prepare("SELECT ...", 参数类型)
  → 数据库返回列元数据
  → 生成记录 { id: i64, name: String }
  → 运行时 fetch_one 解码到记录

常见误区

  • 以为 SQLx 本地解析 SQL 做静态检查:实际依赖服务端解析能力。
  • 以为编译期校验覆盖所有运行期问题:数据约束冲突、连接故障仍在运行期暴露。

追问

  • 没有开发库能否做编译期校验?答:不能连库时只能用离线元数据;两者都没有则宏无法生成类型。
  • 校验发生在 cargo 的哪个阶段?答:宏展开在编译期,不是运行时;IDE 插件也会单独发起一次 prepare 以提供补全与报错。

04.4.8.1-027 离线模式解决什么问题?

一句话结论

离线模式让 query! 系列宏在编译期不连接数据库,改读本地缓存的 prepare 元数据,解决 CI、无库开发机、构建容器里没有数据库也能编译的问题。

概念解释

默认在线模式要求编译环境能访问开发库,流水线和干净检出的 CI 通常不挂数据库。离线模式把某次连库 prepare 的结果(SQL 哈希、列类型、可空性等)序列化到 .sqlx 目录并提交版本库;之后编译按缓存对账,不发网络请求。代价是缓存必须随 schema 演进及时刷新,否则校验依据过期。

原理流程

  1. 开发机连库跑一次 cargo sqlx prepare,生成离线元数据。
  2. 提交 .sqlx 目录到版本库。
  3. CI 或无库环境设置离线模式,宏只读缓存。
  4. schema 或 SQL 变更后重新 prepare 并提交更新缓存。

代码或图示

在线:宏 → 开发库 prepare → 生成类型
离线:宏 → .sqlx/<查询哈希>.json 缓存 → 生成类型

常见误区

  • 认为离线模式等于「不校验 SQL」:仍按缓存元数据校验,只是数据源变成本地快照。
  • 把 .sqlx 加进 .gitignore:CI 离线编译会直接失败。

追问

  • 离线缓存什么时候必须刷新?答:改了 SQL 文本、表结构、列类型或可空性之后。
  • 离线模式下新增一条宏查询会怎样?答:缓存里找不到该查询,按配置报错或回退尝试连库,取决于环境变量与配置。

04.4.8.1-028 cargo sqlx prepare 具体做了什么?

一句话结论

cargo sqlx prepare 编译工程并为每个 query! 宏收集 prepare 元数据,写入项目 .sqlx 目录,供离线编译使用;它是 sqlx-cli 提供的 cargo 子命令入口。

概念解释

prepare 流程触发一次带宏检查的构建,把每条宏 SQL 的 prepare 结果落盘。默认目录为项目根的 .sqlx/,按查询内容哈希组织文件。执行前需要本地有可连的开发库,DATABASE_URL 指向它。prepare 之后 .sqlx 目录应当随源码一起提交,保证他人与 CI 能离线复现相同校验。

原理流程

  1. 安装 sqlx-cli,设置 DATABASE_URL 指向开发库。
  2. 在工程根执行 cargo sqlx prepare。
  3. 工具编译并收集所有宏查询的元数据。
  4. 元数据写入 .sqlx/。
  5. 检查 git 状态,把新增/变更的缓存文件一并提交。

代码或图示

cargo install sqlx-cli
# 确保 DATABASE_URL 指向开发库
cargo sqlx prepare

常见误区

  • 把 sqlx migrate 命令与 cargo sqlx prepare 混为一谈:前者管 schema 版本,后者管宏缓存。
  • prepare 后不检查 .sqlx 变更,新查询的缓存没进版本库。

追问

  • prepare 会不会修改数据库?答:只做 prepare 元数据收集,不执行 DDL/DML;结构变更走 migrate。
  • 多 crate workspace 里缓存放在哪?答:以当前版本工具约定为准,通常与含宏的 crate 对应;不确定时查 sqlx-cli 文档。

04.4.8.1-029 cargo sqlx prepare --check 在 CI 里怎么用?

一句话结论

--check 模式只比对现有 .sqlx 缓存与当前宏查询是否一致,不一致就以非零退出码失败,用于 CI 拦截「改了 SQL 却没刷新离线元数据」的提交。

概念解释

常规 prepare 会写缓存文件,--check 不写盘,只报告差异。CI 流水线在构建前跑一次:如果开发者本地改了 query! 但忘记 prepare 并提交 .sqlx,check 失败,防止离线缓存落后于源码。这与 cargo fmt --check、cargo clippy 同属提交前质量门禁。

原理流程

  1. CI 检出代码,.sqlx 已在版本库。
  2. 执行 cargo sqlx prepare --check(离线环境亦可)。
  3. 工具逐条对账宏查询与缓存。
  4. 一致则通过;不一致列出过期/缺失查询并退出非零。
  5. 修复方式:本地连库 prepare,提交更新后的缓存。

代码或图示

CI 步骤:
1. cargo sqlx prepare --check
2. cargo build / cargo test

常见误区

  • CI 里只跑 cargo build 不开 check:缓存过期不会被门禁发现。
  • 用普通 prepare 替代 check:普通命令会写盘掩盖差异,失去拦截意义。

追问

  • check 需要连数据库吗?答:离线缓存齐全时不需要;行为以当前版本为准。
  • check 报某查询缺失,开发者本地怎么做?答:连开发库执行 cargo sqlx prepare,把 .sqlx 变更提交。

04.4.8.1-030 SQLX_OFFLINE 环境变量如何控制在线与离线?

一句话结论

SQLX_OFFLINE=true 强制宏只读离线缓存、不尝试连库;未设置或为 false 时优先连开发库 prepare,连不上再按缓存/报错处理;它是编译期行为开关,不影响运行时连接。

概念解释

该变量作用于宏的编译期解析路径,用于在 CI、干净环境里强制离线,避免环境里残留的 DATABASE_URL 指向不可达库导致编译卡住。反过来,本地开发想强制刷新校验时要确保不处于离线状态。运行时建池读的仍是 DATABASE_URL,与这个开关无关。

原理流程

  1. 编译期宏读取 SQLX_OFFLINE。
  2. 为真:直接查 .sqlx 缓存,不发起网络连接。
  3. 为假:连接 DATABASE_URL 对应数据库 prepare。
  4. 运行期忽略该变量,按连接串建池。

代码或图示

# 强制离线编译
$env:SQLX_OFFLINE = "true"
cargo build

常见误区

  • 以为 SQLX_OFFLINE 控制运行时是否连库:它只影响编译期宏路径。
  • 本地忘记取消离线,schema 已变仍用旧缓存编译。

追问

  • 离线缓存缺失时 SQLX_OFFLINE=true 会怎样?答:宏报错并提示离线元数据缺失,需本地 prepare。
  • 能否在 .env 里设这个变量?答:可以作为环境约定,但 CI 通常显式注入,避免本地配置污染流水线。

04.4.8.1-031 为什么 .sqlx 目录要提交进版本库?

一句话结论

.sqlx 是离线编译与 CI 校验的输入,不提交则他人检出代码后宏无法离线生成类型,prepare --check 也失去对账基准;它属于构建元数据而非生成物,应当入库。

概念解释

与 target/ 不同,.sqlx 不依赖本机工具链产物,而是源码查询的 prepare 快照,必须随代码演进保持一致。提交它的代价是多一批 JSON 文件,收益是干净环境可复现编译与校验。仓库策略上要把它纳入代码评审:缓存变更与 SQL/schema 变更一起看。

原理流程

  1. 本地 prepare 后 .sqlx 出现新增或修改文件。
  2. 评审确认变更与 SQL 改动对应。
  3. 随源码 commit 入库。
  4. 他人与 CI 检出后直接离线编译或 check。

代码或图示

不应提交:target/、_site/、真实 .env
应当提交:.sqlx/ 离线元数据、migrations/ 迁移脚本

常见误区

  • 把 .sqlx 当构建产物加入 .gitignore。
  • 只提交 .rs 不提交缓存变更,导致 CI 离线失败。

追问

  • 缓存文件太大怎么办?答:按后端与 feature 裁剪,避免同时开用不到的后端;具体目录结构以当前版本为准。
  • 回退代码后缓存会冲突吗?答:缓存按查询哈希组织,回退后旧查询哈希对应文件仍在;多余文件一般不影响编译,必要时重新 prepare 整理。

04.4.8.1-032 schema 变更后离线元数据为什么会过期?

一句话结论

缓存保存的是某次 prepare 时的列名、类型与可空性快照;表结构或列类型改了之后,快照与真实库不一致,宏继续按旧快照生成类型,可能编译通过但运行期解码失败,必须重新 prepare。

概念解释

典型过期场景:加列、删列、改列类型、把列从可空改非空、改枚举值。迁移应用到开发库后,未刷新的 .sqlx 仍是旧结构。离线模式不会主动连库发现差异,只有重新 prepare 才能拿到新元数据。prepare --check 可以在 CI 暴露这种滞后。

原理流程

  1. 迁移改了表结构并应用到开发库。
  2. 代码中的宏查询尚未重新 prepare。
  3. 离线编译按旧缓存生成类型。
  4. 运行期真实列类型/可空性与生成类型不符,解码报错。
  5. 修复:连库 cargo sqlx prepare 并提交新缓存。

代码或图示

旧缓存:nickname: Option<String>
迁移后:nickname NOT NULL
未刷新 → 代码按 Option 解码 → 运行期行为与实际 schema 脱节

常见误区

  • 只跑了数据库迁移,忘记刷新 .sqlx。
  • 以为 CI 在线构建能自动纠正缓存:CI 若走离线模式不会连库纠错。

追问

  • 怎么发现缓存过期?答:cargo sqlx prepare --check 报差异;运行期出现类型解码错误也要回头核对缓存。
  • 改了列名但 SQL 里写了别名,缓存还会过期吗?答:prepare 仍按新列结构解析,缓存哈希与元数据会变,需要重新 prepare。

04.4.8.1-033 新增或修改一条 query! 后的完整流程是什么?

一句话结论

改 SQL → 确保开发库 schema 最新 → 本地编译触发在线 prepare → cargo sqlx prepare 刷新缓存 → 提交源码与 .sqlx → CI 跑 check 与构建。

概念解释

这套流程保证「代码、迁移、离线缓存」三者一致。任何一步跳过都会留下隐患:schema 没更新会 prepare 失败;缓存没提交会让 CI 离线失败;不跑 check 会让过期缓存溜进主干。团队约定里应把 prepare 作为改宏查询后的固定动作。

原理流程

  1. 编写或修改 query!/query_as! 查询。
  2. 应用相关迁移到本地开发库。
  3. 本地编译,确认宏校验通过、类型正确。
  4. 执行 cargo sqlx prepare 更新 .sqlx。
  5. 评审并提交源码与缓存;CI 执行 --check 与构建。

代码或图示

sqlx migrate run
cargo build
cargo sqlx prepare
git add .sqlx src

常见误区

  • 先提交代码再补缓存,中间状态 CI 失败。
  • 多人并行改查询,缓存合并冲突时直接选一边:应重新 prepare 解决。

追问

  • 缓存合并冲突怎么处理?答:保留双方源码,连库重新 cargo sqlx prepare 生成合并后的缓存,不要手动编辑 JSON。
  • 只改注释不改 SQL 会刷新缓存吗?答:SQL 文本哈希不变则缓存不变;注释不影响 prepare 内容。

04.4.8.1-034 离线模式下宏还能校验什么,不能校验什么?

一句话结论

离线模式仍能比对 SQL 文本与缓存元数据、检查列名/类型/可空性是否与快照一致;不能校验快照之外的真实库状态,也无法发现缓存生成之后线上 schema 的漂移。

概念解释

校验依据从「实时服务端」换成「本地快照」:快照里有的列与类型对账照常进行;快照本身的时效性不被验证。新查询缺缓存、SQL 与缓存哈希不符都会报错;但缓存生成后开发库又改了结构,离线编译察觉不到。因此离线模式不能替代对 schema 一致性的流程管控。

原理流程

  1. 宏按 SQL 文本哈希查 .sqlx 缓存。
  2. 命中:按快照列元数据生成类型并对账参数类型。
  3. 未命中:报错要求 prepare。
  4. 快照与真实库是否漂移:离线模式不检查。

代码或图示

离线可校验:SQL 与缓存是否匹配、列名/类型/可空性对账
离线不可校验:缓存生成后库端 schema 变化、服务端新版本语法兼容性

常见误区

  • 以为离线编译通过就等于 SQL 在当前库里合法。
  • 在离线模式下排查「编译过但运行报错」,反复改 Rust 类型而不刷新缓存。

追问

  • 如何兼顾离线速度与真实校验?答:CI 中除离线 check 外,用测试库跑真实查询与集成测试。
  • 缓存里保存了哪些信息?答:查询 SQL、参数与结果列的类型/可空性等 prepare 结果;具体字段结构以 .sqlx 实际文件与文档为准。

04.4.8.1-035 开发库与生产库 schema 不一致有什么风险?

一句话结论

宏按开发库校验,生产库结构不同会让编译期安全承诺失效:索引、约束、列类型、可空性差异可能在运行期才暴露,甚至只有特定数据量下触发。

概念解释

常见差异包括:开发库缺迁移、列类型宽松、唯一索引未建、默认值不同、扩展(如 Postgres 扩展)未安装。编译期校验只反映开发库状态,生产执行时可能遇到约束冲突、类型无法解码、功能不可用。治理手段是迁移纳入版本管理、测试库与生产同构、CI 用临时库跑迁移后测试。

原理流程

  1. 开发库通过迁移保持与目标环境同构。
  2. 宏校验基于该结构生成类型。
  3. 部署前在测试库执行同一批迁移。
  4. 集成测试暴露结构与约束问题。
  5. 生产发布时结构已是最新。

代码或图示

迁移脚本 → 开发库(宏校验)→ 测试库(集成测试)→ 生产库
          三者结构必须来自同一批 migrations/

常见误区

  • 直接在生产库手动改表结构,不走迁移脚本。
  • 开发库为了调试放宽约束(去掉唯一索引),问题被带到生产。

追问

  • 怎么检测环境间结构漂移?答:对比各库 information_schema/系统目录,或让迁移在所有环境按同一版本记录执行。
  • 跨环境类型差异(如字符集)影响解码吗?答:会,字符集与排序规则差异可能导致字符串解码或比较异常,需在环境配置层对齐。

04.4.8.1-036 宏连不上数据库且离线元数据缺失时会报什么错?

一句话结论

编译期宏既无法连接 DATABASE_URL 对应库、又在 .sqlx 找不到缓存时,编译失败并提示需要建立数据库连接或运行 cargo sqlx prepare;错误归属为宏校验错误,而不是普通运行时错误。

概念解释

报错信息通常包含连接失败原因(DNS、认证、拒绝连接)或离线元数据缺失提示。排查顺序:先确认 DATABASE_URL 是否存在且可达,再确认是否应离线构建、.sqlx 是否完整。这类错误发生在 cargo build 阶段,不要去运行日志里找。

原理流程

  1. 编译到宏调用,读取环境变量与离线配置。
  2. 在线尝试连接失败,记录连接错误。
  3. 回退查离线缓存,未命中。
  4. 宏终止编译并给出提示。
  5. 修复连接或补齐缓存后重新编译。

代码或图示

cargo build
  → query! 宏准备校验
  → 连接 dev DB 失败 / 离线缓存缺失
  → 编译错误:无法完成查询校验
  → 处理:检查 DATABASE_URL,或执行 cargo sqlx prepare

常见误区

  • 在运行日志里找编译期宏错误。
  • 看到连接错误就改运行时池配置:先区分是编译期宏连接还是运行期连接。

追问

  • 如何让编译明确走离线而不尝试连库?答:设置 SQLX_OFFLINE=true,避免残留环境变量引发长等待。
  • 密码错误导致的连接失败怎么定位?答:先手动用 CLI 或客户端连同一连接串,确认凭证与网络。

04.4.8.1-037 prepare 之后改了 SQL 却没重新 prepare 会发生什么?

一句话结论

离线编译会按旧缓存对账,SQL 文本哈希已变,通常直接报查询未在缓存中找到;在线编译则重新 prepare 并覆盖旧结果,若此时不刷新提交,他人离线构建又会失败。

概念解释

缓存按查询内容关联:SQL 文本一改,对应哈希就变。未重新 prepare 时,离线模式找不到新哈希;在线模式虽然本地能编译,但仓库里的 .sqlx 仍是旧版本。两种情况都需要把 prepare 作为 SQL 改动后的收尾动作。

原理流程

  1. 修改宏内 SQL 文本。
  2. 离线编译:新哈希无缓存,宏报错。
  3. 在线编译:本地重新 prepare 成功,但缓存文件未更新入库。
  4. 他人检出后离线构建失败。
  5. 补跑 cargo sqlx prepare 并提交。

代码或图示

改 SQL → 在线本地编译通过(看似正常)
       → 忘记 prepare
       → CI 离线:缓存哈希不匹配,构建失败

常见误区

  • 以为本地在线编译通过就完成了改动。
  • 只改了 WHERE 条件不认为影响缓存:任何 SQL 文本变化都改变哈希。

追问

  • 旧缓存文件会残留吗?答:被替换的查询对应文件可能保留在目录中,下次 prepare 会整理;不影响编译,但目录会随版本增长。
  • 批量重构 SQL 后怎么快速核对?答:跑 prepare --check,列出所有未对齐查询。

04.4.8.1-038 多后端或多 feature 组合下离线元数据如何存放?

一句话结论

离线缓存按启用的后端/feature 组合分别记录 prepare 结果;同时开启多个后端时,缓存需要覆盖每个组合的校验,具体目录组织与命名以 sqlx 当前版本文档为准(待确认:跨 feature 缓存是否分目录隔离)。

概念解释

宏校验结果与后端方言、启用类型 feature 有关:同一条 SQL 在 Postgres 与 MySQL 下列类型映射可能不同。工程上推荐一个服务只绑定一个后端,避免缓存矩阵膨胀。若确需多后端编译,要在每种 feature 组合下分别 prepare,并确认 .sqlx 内容完整。

原理流程

  1. 确定需要编译的 feature 组合。
  2. 切换到对应后端连接串执行 prepare。
  3. 检查缓存覆盖该组合的全部宏查询。
  4. 多组合时重复 prepare,避免某组合缺缓存。

代码或图示

待确认:.sqlx 是否按 feature/后端分子目录隔离;
验证方式:docs.rs/sqlx 当前版本离线模式章节,或 prepare 后查看目录结构。

常见误区

  • 用 Postgres 的缓存去离线编译 MySQL 构建:方言与类型映射对不上。
  • 临时加 feature 调试后不还原,缓存与默认 feature 配置脱节。

追问

  • 库只服务一种数据库还需要考虑多缓存吗?答:不需要,单后端单连接串 prepare 即可。
  • feature 增减后旧缓存怎么清理?答:重新 prepare 生成当前配置所需缓存;历史文件处理以工具行为为准。

04.4.8.1-039 SQL 列类型到 Rust 基础类型如何映射?

一句话结论

常见映射:整数按宽度对应 i16/i32/i64,浮点 f32/f64,布尔 bool,文本 String,字节 Vec<u8>,可空列外层包 Option;具体映射随后端类型与启用的类型 feature 变化。

概念解释

映射由解码层按后端列类型 OID/类型名选择 Rust 类型。数据库整数可能有 signed/unsigned 差异,字符串有 text/varchar/char,时间与 JSON 需要额外 feature。编写结构体时先对齐列类型,解码错误通常就是 Rust 类型与 SQL 类型对不上。完整对照表以 docs.rs 各后端「类型映射」章节为准。

原理流程

  1. 查看表结构的列类型与可空性。
  2. 按映射表选 Rust 基础类型。
  3. 可空列加 Option。
  4. 编译或解码期校验,不匹配返回 Decode 错误。

代码或图示

int2/smallint  → i16
int4/integer   → i32
int8/bigint    → i64
boolean        → bool
text/varchar   → String
bytea/BLOB     → Vec<u8>
numeric/decimal → bigdecimal::BigDecimal(需对应 feature)

常见误区

  • 把数据库 bigint 映射成 i32:宽位不匹配,解码失败。
  • 忽略无符号类型在 Rust 侧的对应方式,按有符号类型取值。

追问

  • 金额字段用 f64 还是定点类型?答:金额避免浮点,用 BigDecimal 或定点整数分单位存储,具体以后端与 feature 支持为准。
  • 字符串列允许 NULL 时结构体怎么写?答:字段为 Option<String>,不要写 String。

04.4.8.1-040 可空列为什么映射成 Option<T>?

一句话结论

数据库 NULL 没有对应的非空 Rust 值,解码层只能用 Option 表达「可能为空」;非空列在元数据上标记 NOT NULL,宏/解码直接产出 T。

概念解释

这样设计把空值检查从运行期解引用提前到类型系统:编译器强制你在使用前判断 Some/None,避免 NULL 取数后直接解包 panic。列可空性来自 prepare 元数据;函数版本手写映射时也要主动用 Option 接收可空列。COALESCE 可以在 SQL 层把可空列变成非空默认值。

原理流程

  1. prepare 元数据标记列是否可空。
  2. 可空:生成/解码为 Option<T>。
  3. 取数时按 Option 分支处理。
  4. 非空列误写 Option 通常可兼容,可空列误写非空类型会解码失败。

代码或图示

#[derive(sqlx::FromRow)]
struct User {
    id: i64,
    name: String,          // NOT NULL
    nickname: Option<String>, // 允许 NULL
}

常见误区

  • 可空字段直接 unwrap:把数据库空值变成运行期 panic。
  • 以为结构体里写 Option 就能让非空列变可空:映射方向由列元数据决定。

追问

  • 查询用了 COALESCE(nickname, ''),字段还需要 Option 吗?答:结果不再可能为 NULL,可按非空 String 接收,以 prepare 元数据为准。
  • 两表 join 后外表列为空怎么标?答:左连接外表列可空,对应字段用 Option。

04.4.8.1-041 Uuid 类型怎么映射,需要哪个 feature?

一句话结论

启用 uuid feature 后,SQLx 支持把 Postgres uuid、MySQL/SQLite 的对应字符/字节列与 Rust uuid::Uuid 互相编解码;主键常用 Uuid 作为应用层标识。

概念解释

Uuid 类型来自 uuid crate,SQLx 通过 Type/Encode/Decode 实现接入。Postgres 原生 uuid 类型直接映射;其它后端若用字符或二进制存储,列类型需与编解码约定一致。结构体字段类型写 Uuid(非空)或 Option<Uuid>(可空)。版本(v4 等)由应用生成,与数据库映射无关。

原理流程

  1. Cargo.toml 开启 uuid feature,并引入 uuid crate。
  2. 表主键定义为对应后端 UUID 列类型。
  3. 结构体字段写 Uuid。
  4. 插入时绑定 Uuid 值,查询时解码为 Uuid。

代码或图示

sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres", "uuid"] }
uuid = { version = "1", features = ["v4", "serde"] }
use uuid::Uuid;

#[derive(sqlx::FromRow)]
struct Account { id: Uuid, name: String }

常见误区

  • 开启了 SQLx 的 uuid feature 却没引 uuid crate,类型名找不到。
  • MySQL 用字符列存 UUID 却按二进制解码,格式不匹配。

追问

  • UUID 作主键有什么取舍?答:无序插入可能影响聚簇索引页分裂,存储空间比自增大;权衡以业务写入模式为准。
  • 字符串形式的 UUID 列能直接解码成 Uuid 吗?答:以后端类型映射支持为准;不支持时先解 String 再 Uuid::parse_str。

04.4.8.1-042 chrono 与 time 两套日期时间 crate 怎么选?

一句话结论

SQLx 同时提供 chrono 与 time 两套类型 feature,二选一接入项目现有时间体系;两者都启用时宏的类型选择优先级与文档为准,避免混用导致解码歧义。

概念解释

chrono 是生态中历史最久的时间库,time 是较新的替代品。SQLx 各自提供对应类型编解码。工程选型跟随项目既有依赖:项目已用 chrono 就开 chrono,新项目可评估 time。不要在同一模型里混用两套时间类型,跨边界转换要显式进行。日期时间列的时区语义(带时区/不带时区)比 crate 选择更影响正确性。

原理流程

  1. 盘点项目现有时间依赖。
  2. 在 SQLx 开启对应 feature。
  3. 结构体字段使用对应 crate 类型。
  4. 按列类型(timestamp/ timestamptz/date/time)选择精确到字段的类型。

代码或图示

features = ["runtime-tokio-rustls", "postgres", "chrono"]
# 或
features = ["runtime-tokio-rustls", "postgres", "time"]

常见误区

  • 两个 feature 都开,字段类型在两者间摇摆,编译报类型歧义。
  • 忽略时区:把带时区列解码成无时区类型,丢失偏移信息。

追问

  • DateTime<Utc> 与 NaiveDateTime 分别对应什么列?答:前者适合带时区列,后者适合无时区本地时间列;具体对应以后端文档为准。
  • 跨服务传递时间用什么格式?答:对外序列化为 UTC 时间字符串,内部再解码为对应本地类型。

04.4.8.1-043 JSON/JSONB 列如何映射到 Rust 类型?

一句话结论

启用 json feature 后,JSON 列可解码为 sqlx::Json<T>(包裹实现 serde::Serialize/Deserialize 的结构体)或 serde_json::Value;Postgres 常用 jsonb,MySQL/SQLite 用 JSON/文本列,方言细节有差异。

概念解释

Json<T> 是 newtype 包装,取出 .0 得到 T;Value 适合结构不固定的动态 JSON。编解码依赖 serde:T 要实现 Serialize/Deserialize。把 JSON 整列映射为结构体,避免在应用层再做字符串解析。注意 JSON 列内的查询条件走后端 JSON 函数,不属于 Rust 映射层。

原理流程

  1. 开启 json feature,引入 serde 与对应结构体。
  2. 表列定义为后端 JSON/JSONB 类型。
  3. 结构体字段写 Json<T> 或 Value。
  4. 写入时绑定包装值,读出时解构使用。

代码或图示

use sqlx::types::Json;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct Meta { theme: String }

#[derive(sqlx::FromRow)]
struct Article {
    id: i64,
    meta: Json<Meta>,
}

// 读取
let meta: Meta = row.meta.0;

常见误区

  • 字段直接写 Meta 而不包 Json:解码类型不匹配。
  • 把 JSON 列当字符串读出再手动 from_str,丢掉类型安全。

追问

  • serde_json::Value 什么时候用?答:列结构不稳定、需要动态遍历字段时;结构稳定时优先 Json<T>。
  • JSON 列建索引/查询怎么处理?答:依赖后端 JSON 表达式与索引,SQLx 只负责存取映射。

04.4.8.1-044 Postgres 枚举如何映射到 Rust 枚举?

一句话结论

Postgres 原生 enum 可通过 sqlx::Type derive(配合相应 feature)映射到 Rust 枚举;Rust 枚举变体名与数据库枚举值对齐,写入绑定、读出解码都走同一映射。

概念解释

PG enum 是数据库内独立类型,建表时 CREATE TYPE ... AS ENUM (...)。SQLx 的 derive 读取类型元数据生成映射;变体命名要与枚举标签一致,命名风格差异需用属性调整。无法映射的取值会在解码期报错。MySQL/SQLite 没有同等级原生 enum,通常用字符串或整数列表达。

原理流程

  1. 迁移中创建 PG enum 类型并用于列。
  2. Rust 枚举 derive Type(及必要的 Encode/Decode)。
  3. 变体名与枚举值对齐。
  4. 查询解码为 Rust 枚举,写入绑定枚举值。

代码或图示

#[derive(sqlx::Type, Debug, Clone, Copy)]
#[sqlx(type_name = "order_status")]
enum OrderStatus { Pending, Paid, Shipped }

常见误区

  • Rust 变体用 camelCase 而库值是 snake_case,未做映射导致解码失败。
  • 数据库新增枚举值后,Rust 枚举未加变体,读到新值解码报错。

追问

  • 枚举映射需要哪个 feature?答:通常依赖 derive 与对应后端 feature;具体 derive 可用性以 docs.rs 当前版本为准。
  • 枚举值改名怎么办?答:迁移要处理旧值转换,Rust 侧同步变体并重新 prepare。

04.4.8.1-045 MySQL/SQLite 下枚举一般用什么表示?

一句话结论

MySQL 有 ENUM 列类型,SQLite 无原生枚举;工程上更常见的做法是用字符串列或整数列在应用层用 Rust 枚举约束,避免后端方言绑定过深。

概念解释

MySQL ENUM 在 schema 层约束取值,SQLx 对其映射支持以文档为准;SQLite 只有亲和类型,枚举完全靠应用层保证。跨后端项目倾向统一用 TEXT 列存枚举标签,Rust 枚举负责编解码校验。这样迁移到其它后端时列结构不用改。

原理流程

  1. 确定后端是否有原生枚举类型。
  2. 原生可用则按原生映射;否则选字符串/整数列。
  3. Rust 枚举实现序列化/解码到列表示。
  4. 非法值在解码层转换为错误或默认值。

代码或图示

Postgres:原生 enum 类型 + sqlx::Type 映射
MySQL:ENUM 列或 VARCHAR,映射方式以文档为准
SQLite:TEXT/INTEGER,应用层枚举约束

常见误区

  • 把 PG 原生 enum 方案照搬到 SQLite,列类型不存在。
  • 整数枚举不记录取值含义,后续维护困难。

追问

  • 字符串枚举如何防止脏数据写入?答:在应用层枚举校验,必要时数据库加 CHECK 约束。
  • 跨后端模型复用同一枚举可行吗?答:可行,前提是列表示统一(如都用 TEXT),映射层按后端分别适配。

04.4.8.1-046 自定义类型如何实现 Type、Encode、Decode?

一句话结论

常用 newtype 或枚举直接 derive 相关 trait;类型需要特殊编解码规则时手写实现 Type(声明后端类型)、Encode(写入绑定)、Decode(读取转换),三者配合完成映射。

概念解释

Type 声明 Rust 类型对应哪个后端 SQL 类型;Encode 负责把值编码进绑定参数;Decode 负责从行列值还原为 Rust 值。derive 覆盖标准映射;手写场景包括:自定义金额类型、包装加密值、把内部结构映射到二进制/文本列。实现要考虑可空性与错误转换。

原理流程

  1. 判断标准 derive 是否满足列映射。
  2. 不满足时声明结构体/枚举并手写三个 trait。
  3. Type 绑定后端 SQL 类型元数据。
  4. Encode 写值,Decode 读值并处理失败。
  5. 在查询中作为字段或绑定参数使用。

代码或图示

struct Money(i64);

// 标准场景优先 derive;以下仅示意为手写边界,
// 具体 trait 方法签名与关联类型以 docs.rs 当前版本为准。

常见误区

  • 只实现 Encode 忘了 Decode,能写不能读。
  • 手写解码不处理 NULL,对可空列直接解包导致 panic。

追问

  • 外部 crate 类型无法 impl trait(孤儿规则)怎么办?答:用 newtype 包装本地类型,在包装上实现 trait。
  • 自定义类型要进宏校验需要什么?答:确保其实现的映射类型在后端存在,宏才能对账参数与列类型。

04.4.8.1-047 Vec<u8>、bytea、BLOB 如何映射?

一句话结论

二进制列在 Rust 侧通常映射为 Vec<u8>,读取也可用 &[u8] 视图;Postgres 为 bytea,MySQL/SQLite 为 BLOB/二进制类型,大字段要考虑流式与内存占用。

概念解释

二进制内容(图片字节、序列化负载、文件片段)走字节列。Vec<u8> 拥有所有权,适合结构体字段;借用切片仅在行存活期间有效。大对象不建议整列加载进内存,应分块或落盘。二进制与文本列的编解码路径不同,不要把字节列当字符串解码。

原理流程

  1. 表列定义为后端二进制类型。
  2. 结构体字段写 Vec<u8>(或按文档使用字节类型)。
  3. 写入绑定字节切片,读出得到 Vec<u8>。
  4. 大对象评估内存与分块策略。

代码或图示

#[derive(sqlx::FromRow)]
struct Attachment { id: i64, payload: Vec<u8> }

sqlx::query("INSERT INTO attachments (payload) VALUES ($1)")
    .bind(&bytes[..])
    .execute(&pool)
    .await?;

常见误区

  • 二进制列解码成 String:非 UTF-8 内容解码失败。
  • 数据库存大文件(如整图)而应用一次性 fetch_all:内存峰值过高。

追问

  • 大文件在数据库里的取舍?答:大对象通常存对象存储,库里只存引用;数据库内大字段要评估行宽与缓存影响。
  • 字节列可空怎么写?答:字段为 Option<Vec<u8>>。

04.4.8.1-048 numeric/decimal 与 f64 如何取舍?

一句话结论

金额、计量等要求精确小数的字段用定点类型(如 BigDecimal,需对应 feature),不要用 f64;f64 只适合可容忍误差的科学计算与统计场景。

概念解释

浮点二进制表示无法精确表达十进制小数,累加后产生舍入误差,财务场景不可接受。数据库 numeric/decimal 是定点类型,Rust 侧对应 BigDecimal(或项目约定的定点类型)。启用对应 feature 后编解码自动完成;若未启用,可先读写字符串/整数再转换。选择前先确认后端列类型与 Rust 侧类型都精确。

原理流程

  1. 字段语义判断:金额/计费 → 定点;采样/统计 → 可浮点。
  2. 表列用 numeric/decimal。
  3. 开启定点类型 feature,结构体字段用对应类型。
  4. 序列化对外时明确精度与小数位。

代码或图示

features = ["runtime-tokio-rustls", "postgres", "bigdecimal"]
use bigdecimal::BigDecimal;

#[derive(sqlx::FromRow)]
struct Product { id: i64, price: BigDecimal }

常见误区

  • 金额列用 double precision + f64,对账出现尾差。
  • 定点类型未开 feature,编译找不到类型。

追问

  • 不用 BigDecimal 还有什么精确方案?答:用最小货币单位整数(分)存储,展示层换算;避免浮点参与累加。
  • numeric 精度与标度在哪里定义?答:建表 DDL 中声明,解码后类型保留值,展示层按业务格式化。

04.4.8.1-049 日期时间精度与时区有哪些坑?

一句话结论

先分清列是带时区还是不带时区,Rust 类型与之对齐;跨服务、跨时区统一以 UTC 存储与传输,本地展示再转换;精度(秒/毫秒/微秒)由后端列类型决定。

概念解释

Postgres timestamp with time zone 存 UTC 瞬时点,timestamp without time zone 是本地墙上时间;MySQL/SQLite 语义各有差异。混用类型容易出现时区偏移错误、夏令时问题。应用内部统一 DateTime<Utc> 一类 UTC 类型,落库列语义保持一致;日志与 API 输出再格式化。

原理流程

  1. 确认表列时区语义与精度。
  2. 选择对应 Rust 时间类型(UTC 瞬时 / 无时区本地时间)。
  3. 业务内部统一 UTC 计算与传递。
  4. 展示层按用户时区转换。

代码或图示

timestamptz  → DateTime<Utc>(瞬时时间)
timestamp    → NaiveDateTime(无时区本地时间)
date         → NaiveDate / chrono::NaiveDate 类

常见误区

  • 把无时区列当带时区时间用,部署到不同时区后时间偏移。
  • 序列化本地时间不带偏移,跨服务接收方误判时区。

追问

  • 数据库服务器时区影响结果吗?答:不带时区列的解释受会话/服务器时区影响;带时区列按 UTC 存储,影响较小。
  • 历史时间迁移要注意什么?答:记录原始时区信息,转换时避免重复偏移。

04.4.8.1-050 类型解码失败在哪个阶段暴露?

一句话结论

宏路径下列类型对账在编译期;实际值解码失败(值与 Rust 类型不符、空值进非空字段)发生在取行阶段,返回 Decode 类 sqlx::Error。

概念解释

编译期只能校验类型与可空性元数据,无法检查具体行的值。运行时每行解码:字符串到数字转换失败、字节列转 UTF-8 失败、枚举值无对应变体、空值进非空字段,都会在 fetch_one/fetch_all/流的下一步返回错误。定位时先看错误类型与列名,再回表核对数据与类型映射。

原理流程

  1. 编译期完成 SQL 与类型元数据对账。
  2. 运行期服务端返回结果行。
  3. 解码层逐列按目标类型转换。
  4. 转换失败返回 Decode 错误,携带列名与原因。
  5. 业务层映射为应用错误或记录脏数据。

代码或图示

编译期:SQL/列/类型元数据对账
运行期:行 → 逐列 Encode/Decode → 解码失败 → sqlx::Error::Decode

常见误区

  • 编译通过就认定数据读取一定成功:脏数据仍会触发解码错误。
  • 解码错误笼统当成「数据库连接问题」处理。

追问

  • 解码错误里能看到是哪一列吗?答:错误通常携带列名或索引,按 Error 提供的字段排查;具体字段以当前版本 API 为准。
  • 如何容忍个别脏数据?答:按需在映射层降级为默认值或记录异常行,不要全局吞掉解码错误。

04.4.8.1-051 为什么不能用 format! 把用户输入拼进 SQL?

一句话结论

用户输入进入 SQL 文本会被数据库当作语句的一部分解析,拼接引号、注释符或语句片段即可篡改查询逻辑;必须把值作为绑定参数下发,SQL 文本本身只由代码常量构成。

概念解释

参数化查询把「SQL 结构」与「参数值」分开传输:服务端先解析语句结构,再按占位符代入值,值永远不参与语法解析。format! 拼字符串则把值混进结构文本,输入里的引号、--、OR 1=1 都会改变语义。Rust 字符串安全只保证内存安全,不保证 SQL 注入安全。

原理流程

  1. 区分 SQL 片段(代码常量)与值(外部输入)。
  2. 片段直接写进查询文本。
  3. 值通过 bind 或 QueryBuilder::push_bind 提交。
  4. 服务端解析结构后绑定值执行。

代码或图示

// 危险:输入进入 SQL 文本
let bad = format!("SELECT * FROM users WHERE name = '{}'", input);

// 安全:值走绑定
let rows = sqlx::query("SELECT * FROM users WHERE name = $1")
    .bind(input)
    .fetch_all(&pool)
    .await?;

常见误区

  • 以为转义引号就能安全拼接:转义规则随后端方言变化,遗漏即出漏洞。
  • 内部系统、后台接口就不防注入:后台账号权限同样可被利用。

追问

  • 存储过程/动态执行语句里也有注入风险吗?答:有,只要外部输入进入被执行的 SQL 文本就存在风险。
  • 绑定参数能防哪些攻击?答:防值层面的语句篡改;标识符与排序方向仍需另做白名单。

04.4.8.1-052 QueryBuilder 是什么,基本使用流程是什么?

一句话结论

QueryBuilder<DB> 是 SQLx 的动态 SQL 构造器:以可变对象逐步 push SQL 片段、push_bind 绑定参数,最终生成可执行查询;解决条件不确定、片段动态组合的场景。

概念解释

宏与固定函数查询要求 SQL 文本在编译期基本确定;QueryBuilder 在运行期按条件追加片段和参数,内部维护 SQL 文本与参数列表。它仍然通过绑定提交值,不把参数拼进文本。常用方法包括 push(片段)、push_bind(值)、push_values(批量 VALUES)、build_query/build_query_as(产出查询对象)。

原理流程

  1. 以基础 SQL 片段初始化 QueryBuilder。
  2. 按条件 push 片段、push_bind 参数。
  3. 需要分隔符时用 separated 模式处理列表拼接。
  4. 调用 build_query_as 等生成查询对象并执行。

代码或图示

let mut qb = sqlx::QueryBuilder::<sqlx::Postgres>::new(
    "SELECT id, name FROM users WHERE 1=1"
);

if let Some(name) = name_filter {
    qb.push(" AND name LIKE ").push_bind(format!("%{name}%"));
}
if let Some(min_age) = age_filter {
    qb.push(" AND age >= ").push_bind(min_age);
}

let users = qb.build_query_as::<User>().fetch_all(&pool).await?;

常见误区

  • 用 push 直接追加用户输入的值:片段接口不做转义,必须走 push_bind。
  • 忘记基础片段里的 WHERE 1=1 之类锚点,首个条件拼不出合法 WHERE。

追问

  • QueryBuilder 生成的查询还能被宏校验吗?答:不能,动态文本在运行期下发,校验强度等同函数版本。
  • 用完的 QueryBuilder 能复用吗?答:实例按单次查询构建;需要多次构建时新建实例,具体复用行为以文档为准。

04.4.8.1-053 QueryBuilder 的片段与参数是怎么分离提交的?

一句话结论

push 只写 SQL 文本片段,push_bind 把值追加到独立参数表;最终语句由片段拼出的模板加位置占位符组成,值随协议绑定发送,二者在生成阶段就已分离。

概念解释

构造器内部维护 SQL 字符串与绑定参数队列。每 push_bind 一次,模板里追加对应后端占位符,值进参数队列。执行时驱动按占位符顺序编码参数。这与手写 query("... $1 ...").bind(v) 是同一机制,只是片段组合由构造器完成。

原理流程

  1. push 片段追加到模板文本。
  2. push_bind 追加占位符并登记参数。
  3. 模板完成后,参数队列按占位符顺序排列。
  4. build_query* 产出查询对象,执行时下发模板与参数。

代码或图示

push(" AND age >= ")
push_bind(18)
→ 模板片段:AND age >= $1
→ 参数表:[18]

常见误区

  • 以为 push_bind 会把值转义后写进文本:它进参数表,不进入模板。
  • 占位符编号随 push_bind 顺序递增,中间插入片段不影响参数顺序对应。

追问

  • 同一参数重复使用要绑定几次?答:按占位符出现次数绑定,或用后端命名参数能力;位置参数不做去重复用。
  • 构造器支持 push_bind 一个结构体吗?答:批量场景用 push_values;单结构体展开写法以后端与文档为准。

04.4.8.1-054 可选过滤条件动态拼 WHERE 的标准写法是什么?

一句话结论

以 WHERE 1=1(或等价恒真条件)作为锚点,每个可选条件各自 push " AND 片段" 并 push_bind 对应值;条件为空就不追加,避免处理首个条件要不要写 AND 的分支。

概念解释

动态 WHERE 的麻烦在于条件数量不定、连接词难处理。恒真锚点让每个条件都能统一加 AND,代码分支只判断「加不加」。条件内部的值仍走绑定;列名、操作符来自代码白名单,不来自输入。这种写法可读性好,也便于测试各条件组合。

原理流程

  1. 初始化带恒真条件的查询模板。
  2. 逐个判断可选参数是否存在。
  3. 存在则追加 AND 片段与绑定值。
  4. 最终执行查询,空条件集合等价于无过滤。

代码或图示

let mut qb = sqlx::QueryBuilder::<sqlx::Postgres>::new(
    "SELECT id, name FROM users WHERE 1=1"
);
if let Some(q) = keyword {
    qb.push(" AND name ILIKE ").push_bind(format!("%{q}%"));
}
if let Some(status) = status {
    qb.push(" AND status = ").push_bind(status);
}
let users = qb.build_query_as::<User>().fetch_all(&pool).await?;

常见误区

  • 首个条件单独判断「有没有 WHERE」,后续条件再拼 AND,分支容易漏。
  • 把可选列名也做成参数传入,绕过白名单。

追问

  • WHERE 1=1 在性能上有影响吗?答:优化器通常忽略恒真条件;保留它是为了代码结构,不是性能需要。
  • 条件很多时如何组织?答:把过滤参数收敛到一个结构体,构造器方法按字段批量处理。

04.4.8.1-055 IN 列表如何绑定参数?

一句话结论

IN 的值集合要展开成占位符列表再逐个绑定;Postgres 可用数组绑定配合 = ANY($1),MySQL/SQLite 通常展开多个 ?;空列表要单独处理成永假条件,不能生成空 IN ()。

概念解释

参数不能直接代表「一组值展开成多个占位符」,需要在构造器里生成与列表长度对应的占位符。Postgres 数组绑定是另一种路径:把数组作为单个参数传给 ANY。空列表在 SQL 里没有合法的 IN () 形式,应显式拼 AND 1=0 或在应用层提前返回空结果。

原理流程

  1. 接收 ID 列表,判断是否为空。
  2. 非空:生成占位符序列,逐个 push_bind。
  3. Postgres 可选数组 + ANY 路径。
  4. 空列表:拼接永假条件或短路返回空集。

代码或图示

let ids: &[i64] = &[1, 2, 3];
let mut qb = sqlx::QueryBuilder::<sqlx::Postgres>::new(
    "SELECT id, name FROM users WHERE id IN ("
);
qb.push_values(ids.iter(), |mut b, id| { b.push_bind(*id); });
qb.push(")");
let users = qb.build_query_as::<User>().fetch_all(&pool).await?;

常见误区

  • 把整个列表 format! 拼进 IN (...):既是注入面又类型不安全。
  • 空列表生成 IN ():语法错误或语义错误。

追问

  • 列表很长有什么风险?答:占位符数量与数据包大小上升,需分批处理;后端占位符上限也要留意。
  • ANY($1) 绑定什么类型?答:Postgres 数组类型(如 Vec<i64>),具体映射以后端文档为准。

04.4.8.1-056 表名、列名、排序方向为什么不能参数化?

一句话结论

绑定参数只能替换值,不能替换标识符与语法结构;表名、列名、排序方向、函数名都属于 SQL 结构,必须由代码白名单校验后内联,不能接受任意输入。

概念解释

数据库协议里参数占位符只绑定字面量值,标识符位置不接受参数。动态排序、动态选列是常见注入点:前端传 sort=name,若直接拼 ORDER BY {sort},传入 id; DROP TABLE ... 就出问题。正确做法是在代码里维护输入到合法标识符的映射,命中白名单才内联,否则拒绝。

原理流程

  1. 接收前端字段名/排序方向输入。
  2. 与代码内白名单映射表比对。
  3. 命中:取对应的合法列名/方向关键字内联进片段。
  4. 未命中:返回参数错误,不拼接 SQL。

代码或图示

let sort_col = match sort.as_str() {
    "name" => "name",
    "age" => "age",
    _ => return Err(ApiError::InvalidSort),
};
let dir = match direction.as_str() {
    "asc" => "ASC",
    "desc" => "DESC",
    _ => return Err(ApiError::InvalidSort),
};
qb.push(format!(" ORDER BY {sort_col} {dir}"));

常见误区

  • 以为绑定参数能覆盖标识符:协议层就不支持。
  • 白名单只校验排序方向,不校验列名。

追问

  • 表名动态选择怎么防注入?答:同样走枚举映射到固定表名,不直接拼接请求字符串。
  • 白名单映射放哪里?答:放在查询构造模块内,与 SQL 片段同处一层,便于审计。

04.4.8.1-057 参数化查询下仍可能出现注入的位置有哪些?

一句话结论

值绑定安全,但标识符、动态表/列名、排序方向、LIKE 模式构造、动态 SQL 函数调用、拼接进文本的存储过程参数仍是注入面;审计要逐一看「是否有外部输入进入 SQL 片段」。

概念解释

只要输入最终出现在 SQL 文本而非参数表,就脱离了参数化保护。典型位置:ORDER BY 字段、SELECT 列名、JOIN 表名、LIKE 通配处理、COLLATE 子句、后端 EXECUTE 动态语句。参数化降低了值层面风险,不能自动消除结构层面拼接风险。

原理流程

  1. 列出查询中所有来自外部的片段。
  2. 值类输入确认走 bind/push_bind。
  3. 结构类输入确认经过白名单映射。
  4. 无法归类的动态片段按高风险处理,重构为固定 SQL 分支。

代码或图示

安全:值 → bind
风险:表名 / 列名 / 排序方向 / 函数名 / 分隔符 → 必须白名单内联

常见误区

  • 用了 ORM 或参数化就认为全链路无注入。
  • 把列名校验放在前端,后端不复查。

追问

  • LIKE 里的用户关键词本身安全吗?答:值可绑定,但 %/_ 通配符会改变匹配范围;按产品需要决定是否转义通配符。
  • 审计时先看哪类代码?答:先找 format!、字符串 push、字符串拼接出现在 SQL 构造处的位置。

04.4.8.1-058 LIKE/ILIKE 模糊匹配要做什么转义处理?

一句话结论

关键词作为值绑定,但其中的 %、_(以及后端转义符)是通配符,需要按产品预期决定转义;不要把用户输入直接包成 %{q}% 就忽略通配符语义。

概念解释

% 匹配任意串、_ 匹配单字符,用户输入本身含这些字符时会被当通配符,导致匹配范围扩大。严格关键词匹配应转义通配符并声明 ESCAPE;仅做宽松搜索时可接受通配行为,但要在产品说明里明确。转义规则随后端 LIKE 实现,不要假设通用转义字符。

原理流程

  1. 确认搜索是否允许通配符语义。
  2. 需要严格匹配:转义关键词中的通配符与转义符。
  3. 绑定转义后的值,必要时带 ESCAPE 子句。
  4. 前后通配包裹由代码控制,不来自输入。

代码或图示

// 宽松搜索:值绑定,通配符由代码包裹
let pattern = format!("%{keyword}%");
qb.push(" AND name ILIKE ").push_bind(pattern);

// 严格搜索时:先转义 keyword 中的 % _ 与转义符,具体转义写法以后端文档为准

常见误区

  • 关键词里的 _ 被当成单字符通配,返回意外结果。
  • 转义规则按其它数据库方言照抄到当前后端。

追问

  • 大小写不敏感用哪个?答:Postgres 用 ILIKE;MySQL 依赖列排序规则;SQLite 按编译选项与 COLLATE,方言不同。
  • 模糊搜索性能怎么保证?答:前后通配的 LIKE 难以走普通索引,大数据量考虑全文检索方案。

04.4.8.1-059 QueryBuilder 与宏查询混合使用的边界是什么?

一句话结论

同一条查询要么是固定文本走宏/固定函数,要么完全由 QueryBuilder 动态构造;不要尝试把宏返回的片段与运行时拼接结果混进同一条语句,校验边界与方言占位符都不一致。

概念解释

宏在编译期生成固定查询对象,QueryBuilder 在运行期产出查询对象,二者是不同构造路径。工程上按查询形态拆分:条件固定、字段固定的报表查询用宏拿类型校验;筛选条件动态的列表接口用构造器。混合场景(基础固定 + 少量动态)一般整体走构造器,宏不参与片段拼装。

原理流程

  1. 评估查询文本是否在编译期完全确定。
  2. 确定:选 query!/query_as!。
  3. 含运行时分支:整体用 QueryBuilder。
  4. 两种路径的结果分别映射到对应结构体。

代码或图示

固定查询 → query_as!(User, "SELECT ... WHERE id = $1", id)
动态查询 → QueryBuilder → build_query_as::<User>()

常见误区

  • 想让宏「校验一部分」再拼接剩余片段:宏不输出可拼接片段。
  • 动态构造后又套用宏生成的类型,可空性与列名未必对齐。

追问

  • 构造器结果怎么映射结构体?答:build_query_as::<T>(),T 实现 FromRow。
  • 动态查询还想保留编译期校验怎么办?答:无法两全;把动态条件收敛成固定分支,或在集成测试覆盖各组合。

04.4.8.1-060 动态排序与动态分页参数如何安全构造?

一句话结论

排序列与方向走白名单映射后内联;页码、页大小作为数值参数绑定,并限制页大小上限;分页偏移量由数值计算,不接受字符串拼接。

概念解释

动态排序是结构拼接,必须白名单;分页数值是值,走绑定。页大小要设上限防止一次拉取过大结果;页码偏移量公式 (page - 1) * size 在应用层计算并校验非负。深分页性能问题(大 offset)另由 keyset 分页解决,不属于注入范畴。

原理流程

  1. 解析排序字段与方向,白名单映射到合法列/方向。
  2. 校验页码与页大小,限制 size 上限。
  3. 计算偏移量,作为参数绑定。
  4. 构造 ORDER BY ... LIMIT ... OFFSET ... 执行。

代码或图示

let limit: i64 = page_size.clamp(1, 100);
let offset: i64 = (page - 1) * limit;
qb.push(format!(" ORDER BY {sort_col} {dir} "))
  .push(" LIMIT ").push_bind(limit)
  .push(" OFFSET ").push_bind(offset);

常见误区

  • 页大小不设上限,请求 size=100000 打垮内存。
  • 排序字段直接来自请求字符串内联。

追问

  • 大偏移分页有什么优化?答:用 keyset/游标分页,按排序键继续翻页,避免扫描前导行。
  • 排序键不唯一会导致分页重复/丢行吗?答:排序键需唯一(通常追加主键兜底),保证分页稳定。

04.4.8.1-061 批量插入多行 VALUES 怎么构造?

一句话结论

用 QueryBuilder::push_values 遍历值列表生成多行 VALUES (...), (...),每行字段逐个 push_bind,一次 execute 提交;避免循环单行插入造成多次往返。

概念解释

批量插入把多条记录合并成一条多值语句,减少网络往返与事务开销。push_values 接收迭代器,闭包里为每行绑定各列值。值列表为空时不要生成空语句,应提前返回或按业务跳过。多行插入仍受后端参数数量上限约束,超大列表要分批。

原理流程

  1. 收集待插入结构体或值列表。
  2. 非空时初始化 INSERT INTO table (cols) VALUES。
  3. push_values 遍历生成行元组与绑定。
  4. 一次 execute,取受影响行数。

代码或图示

let mut qb = sqlx::QueryBuilder::<sqlx::Postgres>::new(
    "INSERT INTO users (name, age) VALUES "
);
qb.push_values(items, |mut b, item| {
    b.push_bind(item.name).push_bind(item.age);
});
qb.build().execute(&pool).await?;

常见误区

  • 循环 INSERT 单行提交,往返次数等于行数。
  • 列表过大不分批,超出后端参数上限或数据包大小限制。

追问

  • 批量插入冲突如何处理?答:在语句上加 ON CONFLICT 子句(PG)或对应后端 upsert 语法,列冲突目标写死在片段里。
  • 批量插入要回主键吗?答:用 RETURNING 配合 fetch 取回,逐行主键回填,具体以支持情况为准。

04.4.8.1-062 一份防注入审计清单应包含哪些检查项?

一句话结论

逐项确认:SQL 片段只来自代码常量,外部值全部绑定,标识符经白名单,排序/表名/列名不接受裸输入,LIKE 通配有处理,无字符串拼接语句,动态执行语句单独评审。

概念解释

审计从代码入口追到查询构造:请求参数、配置值、消息体内容是否进入 SQL 文本。值走绑定即安全;结构位置必须有映射表。历史遗留的 format! 拼 SQL、存储过程动态执行是重点排查对象。清单结果应落到具体查询与责任人,而不是笼统「已评审」。

原理流程

  1. 列出所有查询构造点(宏、函数、构造器、原生 SQL 调用)。
  2. 标注每个外部输入的去向:绑定 / 片段 / 未使用。
  3. 片段输入核对白名单。
  4. 风险项重构为固定分支或绑定。
  5. 补充针对注入用例的测试。

代码或图示

审计项:
[ ] 外部值是否全部 bind
[ ] 表/列/排序方向是否走白名单
[ ] 是否存在 format! / 字符串拼接进 SQL
[ ] LIKE 通配是否按预期处理
[ ] 动态执行语句是否隔离评审

常见误区

  • 只看新增代码,不扫遗留查询。
  • 认为绑定了主条件就放过动态排序片段。

追问

  • 自动化工具能覆盖哪些?答:依赖扫描与静态分析可发现部分拼接模式;标识符白名单与业务上下文仍需人工评审。
  • 测试怎么模拟注入用例?答:在集成测试里用含引号、注释、OR 1=1 的输入断言结果未被篡改。

04.4.8.1-063 如何启动一个事务?

一句话结论

从池或连接调用 begin() 得到 Transaction,后续查询借用该事务句柄执行,最后 commit() 提交或 rollback() 回滚;未显式结束时 drop 自动回滚。

概念解释

Pool::begin 从池借一条连接并在其上开启事务,返回 Transaction<'c, DB>;Connection::begin 对已有连接开启。事务句柄实现 Executor,查询通过 &mut *tx 借用执行。事务期间连接被占用,结束后连接归还池。事务返回的是拥有事务状态的包装,不是单独的连接句柄。

原理流程

  1. pool.begin().await? 借连接并 BEGIN。
  2. 把 &mut tx 传给各数据访问函数。
  3. 所有语句在同一连接上执行。
  4. 成功 tx.commit().await?;失败或早退 tx.rollback().await? 或 drop。

代码或图示

let mut tx = pool.begin().await?;

sqlx::query("UPDATE accounts SET balance = balance - $1 WHERE id = $2")
    .bind(amount).bind(from_id)
    .execute(&mut *tx)
    .await?;

sqlx::query("UPDATE accounts SET balance = balance + $1 WHERE id = $2")
    .bind(amount).bind(to_id)
    .execute(&mut *tx)
    .await?;

tx.commit().await?;

常见误区

  • 事务内一部分查询传 &pool:那些语句不在事务连接上,脱离事务边界。
  • begin 后忘记 commit,函数返回时 drop 触发回滚。

追问

  • begin 失败属于哪类错误?答:获取连接或执行 BEGIN 阶段错误,通常归类为连接/IO 或数据库错误,按 sqlx::Error 变体判断。
  • 事务能跨多个连接吗?答:不能,一个事务绑定一条物理连接,跨库一致性需要分布式事务方案。

04.4.8.1-064 commit、rollback 与 drop 时的回滚语义是什么?

一句话结论

commit(self) 提交事务并消耗句柄,rollback(self) 显式回滚;事务仍在进行中就被 drop(未 commit 也未 rollback),析构时自动回滚,避免半成品事务残留。

概念解释

事务句柄持有「未结束事务」的状态。commit/rollback 按值消费句柄;中途 panic 或提前返回导致句柄 drop,析构兜底执行回滚。自动回滚是安全网,但显式 rollback 能拿到回滚错误并记录日志。注意 drop 回滚是异步语义的析构钩子,具体行为以当前版本文档为准。

原理流程

  1. 事务开启后持有句柄。
  2. 业务成功:调用 commit,服务端提交。
  3. 业务失败:调用 rollback 或返回错误触发 drop。
  4. drop 路径检测事务未结束,执行回滚兜底。

代码或图示

let mut tx = pool.begin().await?;
match do_work(&mut tx).await {
    Ok(_) => tx.commit().await?,
    Err(e) => { tx.rollback().await?; return Err(e); }
}

常见误区

  • 依赖 drop 自动回滚却不记录原因,线上只看到事务被撤销。
  • commit 之后继续使用原句柄:句柄已被消耗,类型上不允许。

追问

  • 自动回滚失败怎么办?答:兜底回滚出错只能记录告警,连接可能被池丢弃重建;关键路径显式 rollback 便于观测。
  • commit 是异步的吗?答:是,commit().await 等待服务端确认提交。

04.4.8.1-065 为什么事务句柄要以 &mut tx 传递给业务函数?

一句话结论

事务绑定一条可变借用的连接,多个查询共享同一事务必须独占借用该句柄;传 &mut Transaction 让各函数在同一事务连接上执行,避免并发借用破坏事务一致性。

概念解释

Transaction 实现 Executor 的可变借用形式:查询执行需要 &mut 访问内部连接。业务函数签名接收 &mut Transaction<'_, DB>,调用链逐层传递。不能把事务句柄克隆成多个并行分支,否则两条语句会争用同一连接。函数返回后借用结束,句柄仍归上层控制 commit/rollback。

原理流程

  1. 上层 begin 得到事务句柄。
  2. 把 &mut tx 传入 service 函数。
  3. 函数内查询借用句柄执行。
  4. 返回后上层决定 commit 或 rollback。

代码或图示

async fn transfer(
    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
    from: i64, to: i64, amount: i64,
) -> Result<(), sqlx::Error> {
    sqlx::query("UPDATE accounts SET balance = balance - $1 WHERE id = $2")
        .bind(amount).bind(from)
        .execute(&mut **tx)
        .await?;
    Ok(())
}

let mut tx = pool.begin().await?;
transfer(&mut tx, from, to, amount).await?;
tx.commit().await?;

常见误区

  • 把 tx 按值传给子函数又在上层 commit:所有权转移后上层无法再提交。
  • 在事务函数里借池连接做附加查询:脱离事务。

追问

  • &mut **tx 与 &mut tx 都能传吗?答:按 Executor 实现要求选择可变借用形式;编译期 trait bound 会指出正确写法。
  • 事务句柄能存进全局状态吗?答:不建议,事务生命周期应局限在单次业务用例内。

04.4.8.1-066 嵌套事务与 savepoint 是怎么支持的?

一句话结论

在活动事务上再次 begin() 会建立 savepoint:内层事务提交对应 release savepoint,回滚对应 rollback 到 savepoint;外层事务的提交/回滚决定整体最终结果。

概念解释

数据库不支持真正嵌套的顶层事务,SQLx 用 savepoint 模拟嵌套作用域。内层 Transaction 拥有自己的深度计数,其 commit/rollback 映射到 savepoint 操作。这样工具函数可以在不破坏外层事务的前提下划分可回滚区间。后端对 savepoint 的支持程度不同,MySQL/PG 支持,SQLite 行为以文档为准。

原理流程

  1. 外层 pool.begin() 开启事务。
  2. 内层 tx.begin().await? 建立 savepoint。
  3. 内层语句在 savepoint 之后执行。
  4. 内层 commit 释放 savepoint;内层 rollback 恢复到 savepoint。
  5. 外层最终 commit/rollback 决定整体。

代码或图示

let mut tx = pool.begin().await?;
{
    let mut inner = tx.begin().await?;
    // inner 内的操作
    inner.commit().await?;
}
tx.commit().await?;

常见误区

  • 以为内层 commit 会把外层一起提交:内层只释放 savepoint。
  • 内层回滚后继续使用内层句柄:已被消耗,需重新开始区间。

追问

  • savepoint 名称由谁生成?答:由 SQLx 内部按深度/计数生成;自定义语句入口以当前版本 API 为准。
  • 嵌套层级很深有什么风险?答:savepoint 链增加开销与排错复杂度,合理划分业务边界即可。

04.4.8.1-067 Connection::transaction 闭包式 API 有什么优缺点?

一句话结论

闭包式 transaction(|tx| async { ... }) 自动按返回结果提交或回滚:闭包返回 Ok 提交,返回 Err 回滚;优点是不易漏 commit,缺点是错误类型要满足 From<Error> 约束,复杂控制流不如手动句柄直观。

概念解释

该 API 把事务生命周期收进闭包:进入时 begin,闭包成功返回 commit,失败返回 rollback。业务错误类型需要能从 sqlx::Error 转换(E: From<sqlx::Error>)。闭包是 FnOnce 异步块,捕获变量要满足 Send。手动 begin/commit 则保留显式控制,适合需要中间观察、分步回滚决策的场景。

原理流程

  1. 调用 conn.transaction,传入异步闭包。
  2. 闭包内拿到 &mut Transaction 执行业务。
  3. 返回 Ok(R):框架 commit。
  4. 返回 Err(E):框架 rollback,错误向上传播。

代码或图示

conn.transaction(|tx| async move {
    sqlx::query("UPDATE ...").execute(&mut *tx).await?;
    sqlx::query("UPDATE ...").execute(&mut *tx).await?;
    Ok::<(), sqlx::Error>(())
}).await?;

常见误区

  • 闭包错误类型无法从 sqlx::Error 转换,编译报 trait bound。
  • 在闭包外持有事务句柄引用,生命周期超出闭包。

追问

  • 闭包内想根据业务错误类型决定是否回滚怎么办?答:任何 Err 都触发回滚;需要部分提交就拆分手动事务或用 savepoint。
  • 闭包返回值类型如何标注?答:用 Ok::<R, E>(...) 帮助编译器推断返回类型。

04.4.8.1-068 事务如何与 axum handler 集成?

一句话结论

全局共享 Pool 放进应用状态;handler 内按需 pool.begin() 开事务,把 &mut tx 传给 service 层,提交或回滚后返回响应;事务生命周期不跨请求,连接随句柄结束归还池。

概念解释

axum 应用状态里存的是可克隆的 Pool,不是单连接。每个请求在需要原子性的用例内开启事务。handler 错误类型要能包装 sqlx::Error;service 函数接收事务句柄而非池,保证多条语句在同一事务。事务不要存在扩展状态里跨请求复用。

原理流程

  1. 启动时构建 Pool,注入 axum State。
  2. handler 从状态取 Pool。
  3. 用例需要原子性时 pool.begin()。
  4. service 层借 &mut tx 执行,handler 决定 commit/rollback。
  5. 响应返回后句柄结束,连接归还池。

代码或图示

async fn create_order(
    State(pool): State<sqlx::PgPool>,
    Json(req): Json<CreateOrder>,
) -> Result<Json<Order>, AppError> {
    let mut tx = pool.begin().await?;
    let order = Order::create(&mut tx, req).await?;
    tx.commit().await?;
    Ok(Json(order))
}

常见误区

  • 把事务句柄塞进 Extension 跨 handler 传递:生命周期与连接占用失控。
  • service 方法内部自己 pool.begin(),外层事务被绕过。

追问

  • 多步业务在一个 handler 里,事务放哪一层?答:放在用例/服务方法边界,handler 只负责调用与错误转换。
  • 事务内调用外部 HTTP 接口合适吗?答:长事务持有连接等待外部响应,应尽量把外部调用移到事务外。

04.4.8.1-069 事务里跨 .await 持有连接会不会阻塞池?

一句话结论

会:事务未结束期间对应连接一直被占用,其它请求只能等待空闲连接;事务内每个 .await 只要还持有 tx,连接就不归还池,长等待会快速耗尽池。

概念解释

事务句柄活着即连接在借状态。事务内等待外部 API、锁、消息或慢查询,连接都不释放。池大小有限,并发事务积压时后续 acquire 超时返回错误。实践原则:事务内只做数据库操作,把非数据库 IO 移到事务前后;保持事务短而紧凑。

原理流程

  1. begin 后连接进入在借状态。
  2. 事务内每个 await 期间连接仍被占用。
  3. 外部等待越长,占用越久。
  4. 并发上升后空闲连接耗尽,新请求 acquire 等待。
  5. commit/rollback 后连接归还。

代码或图示

反模式:
begin → 调用外部 HTTP(等待数百毫秒)→ DB 写入 → commit
改进:
先调外部接口拿到结果 → begin → DB 写入 → commit

常见误区

  • 以为异步等待时连接会自动让出给别的请求:连接占用是所有权问题,与任务调度无关。
  • 事务内做批量慢操作,占用连接时间被放大。

追问

  • 如何观测事务占用时长?答:结合连接在借状态、慢查询日志与链路跨度,测量 begin 到 commit 的时间。
  • 必须在事务内调用外部服务怎么办?答:缩小事务范围、提高失败重试设计,必要时考虑最终一致与补偿方案。

04.4.8.1-070 事务超时与长事务有什么风险?

一句话结论

长事务持有连接与锁,阻塞其它写入、推高回滚段与 Vacuum 压力,还可能让池耗尽;应设置合理的事务边界与语句超时,避免把多个用例塞进同一事务。

概念解释

数据库层面长事务影响锁持有、MVCC 版本可见性与清理;应用层表现为连接长时间不归还。风险包括:其它会话等待锁超时、备份/清理受阻、连接池被少数长事务占满。控制手段:事务内不做无关 IO、拆分大事务、设置语句/事务超时、监控事务持续时间。

原理流程

  1. 划分用例的原子性边界,只把必须同生共死的操作放进事务。
  2. 事务内语句尽量短。
  3. 配置语句超时与 acquire 超时兜底。
  4. 监控长事务与锁等待,定位异常用例。

代码或图示

长事务信号:
- 单事务内多次外部等待
- 批量大更新包在一个事务
- 事务跨越人工确认环节

常见误区

  • 为了「保险」把整个请求流程都包进事务。
  • 长事务出错后依赖回滚恢复,忽略期间已占用的资源。

追问

  • 批量处理怎么避免单个超长事务?答:按批次提交,每批独立事务,记录进度支持断点续跑。
  • 数据库侧怎么看长事务?答:查对应后端的活动会话/事务视图,找运行时间长、未提交的会话。

04.4.8.1-071 事务回滚后这条连接还能复用吗?

一句话结论

回滚结束后连接回到池可被复用;若回滚过程中连接已损坏(网络中断、协议异常),池会判定不可用并丢弃重建,不会把坏连接再借出。

概念解释

事务回滚清理的是数据库状态,连接本身在协议层通常仍可用。池在连接归还与再借出时按配置做可用性检查(如 test_before_acquire)。回滚错误、中途断连会让连接进入不可用路径。复用连接时上一个事务状态不会残留,下一次 begin 是全新事务。

原理流程

  1. 事务回滚完成,句柄 drop。
  2. 连接归还空闲队列。
  3. 再借出时按配置做存活检测。
  4. 检测通过则复用;失败则关闭并补建新连接。

代码或图示

rollback → 句柄结束 → 连接归还池 → 借出前检测 → 复用 / 丢弃重建

常见误区

  • 以为回滚过的连接被标记脏、必须关闭:正常回滚后连接可复用。
  • 回滚失败后仍继续在该连接上发查询:应丢弃连接并记录错误。

追问

  • 如何配置借出前检测?答:PoolOptions::test_before_acquire,具体探针行为以后端实现为准。
  • 连接复用会带上会话级设置吗?答:之前在连接上执行的会话参数可能残留,必要时用 after_connect 统一初始化。

04.4.8.1-072 多步写入「要么全成要么全败」的边界怎么设计?

一句话结论

先列出必须原子成功的写入步骤,把它们放进同一事务;事务外的查询、外部通知、补偿动作单独划分;明确失败时的补偿与重试边界,不要把不可回滚的外部动作塞进事务。

概念解释

事务只能保证数据库内多语句原子性,管不了外部接口、消息发送、缓存写入。设计时区分:强一致部分(库内多表写入)进事务;最终一致部分(发消息、调外部)走事务后或补偿机制。跨服务场景用本地消息表、outbox 等模式衔接。边界不清会导致事务内调外部接口拉长占用,或事务外写库留下半成品。

原理流程

  1. 梳理用例涉及的所有写操作与副作用。
  2. 标注可随事务回滚的库内操作。
  3. 不可回滚的外部动作移出事务,设计补偿。
  4. 事务内执行库内写入并提交。
  5. 事务后触发外部动作,失败走重试/补偿。

代码或图示

事务内:扣减库存、创建订单、写余额(库内多表)
事务后:发送消息、推送通知、调用外部服务(失败可重试/补偿)

常见误区

  • 把发 MQ、调支付接口放进数据库事务等待回调。
  • 多个独立用例共用一个大事务,失败互相牵连。

追问

  • 事务提交后发消息失败怎么办?答:用 outbox/本地消息表,事务内落消息记录,后台任务投递并重试。
  • 跨库操作如何保证?答:单库事务不覆盖,需分布式事务协议或最终一致补偿方案。

04.4.8.1-073 死锁在事务里如何暴露,重试边界在哪里?

一句话结论

死锁由数据库检测并中止其中一个事务,错误表现为数据库错误(含死锁特征码/种类);应用层可对有限次数的死锁做幂等重试,业务冲突导致的唯一键/更新冲突不应盲目重试。

概念解释

事务交叉持有锁时,数据库回滚牺牲一方,应用收到错误。重试前要区分错误类型:死锁、锁等待超时属于可重试并发冲突;唯一键冲突、数据不存在是业务状态问题,重试不解决。重试必须保证操作幂等,次数有限并记录告警。获取锁顺序一致、缩小事务范围也能减少死锁。

原理流程

  1. 事务内多条写语句按固定顺序访问表/行。
  2. 发生死锁时服务端中止当前事务。
  3. 错误分类:识别死锁/锁等待超时。
  4. 可重试且操作幂等:有限次数退避重试。
  5. 业务冲突错误:直接返回业务错误。

代码或图示

// 伪代码:识别可重试错误后有限重试
for attempt in 0..3 {
    match run_tx(&pool).await {
        Ok(v) => return Ok(v),
        Err(e) if is_deadlock(&e) && attempt < 2 => continue,
        Err(e) => return Err(e),
    }
}

常见误区

  • 对所有数据库错误无差别重试,放大唯一键冲突。
  • 重试非幂等操作,重复扣款/重复下单。

追问

  • 怎么判断错误是死锁?答:读取 DatabaseError 的错误码/种类字段,匹配后端死锁标识;具体枚举以当前版本 ErrorKind 为准。
  • 降低死锁概率还有哪些手段?答:统一加锁顺序、缩短事务、降低并发交叉访问、合理索引减少锁范围。

04.4.8.1-074 SQLx 连接池内部是怎么组织连接的?

一句话结论

池内部维护空闲连接队列与在借计数,按需创建连接;借出时从空闲队列取或新建,归还时放回队列;连接异常或超期则被清理,整体受 PoolOptions 配置约束。

概念解释

Pool<DB> 是线程/任务安全的共享结构,自身 Clone 只是增加一个池句柄,不复制连接。借连接是异步动作:无空闲且未达上限时新建,达到上限则等待空闲。池内部还跟踪连接生命周期(空闲时长、最大存活、健康检测)。理解内部结构有助于排查「连接为什么借不到」。

原理流程

  1. 构建池,按最小连接数预热。
  2. 请求 acquire:空闲有连接则取出;无则判断是否达上限。
  3. 未达上限新建连接;达上限进入等待队列。
  4. 连接 drop 归还空闲队列,唤醒等待者。
  5. 后台清理超期/损坏连接。

代码或图示

Pool
├── 空闲连接队列(可借出)
├── 在借连接集合(被任务持有)
├── 等待借出的任务队列
└── 配置:上限/预热/超时/生命周期/检测

常见误区

  • 克隆 Pool 以为复制了一套连接:多个句柄共享同一池。
  • 以为借出后连接由调用者销毁:drop 包装器即归还。

追问

  • 池关闭后等待中的请求会怎样?答:返回池已关闭类错误;具体变体以当前版本为准。
  • 如何查看池状态?答:池提供状态信息接口(在借/空闲计数等),具体方法名以 docs.rs 为准。

04.4.8.1-075 PoolOptions 有哪些核心配置项?

一句话结论

核心项包括 max_connections、min_connections、acquire_timeout、idle_timeout、max_lifetime、test_before_acquire、connect_timeout、after_connect;按数据库承载能力与并发模型取值。

概念解释

max_connections 是池上限,min_connections 是预热空闲数。acquire_timeout 等待借连接的最长时间,connect_timeout 新建连接握手超时。idle_timeout 空闲多久后回收,max_lifetime 连接最长存活时间,防止长期老化连接。test_before_acquire 借出前探测可用性。after_connect 钩子做连接初始化。各方法签名以后端当前文档为准。

原理流程

  1. 按数据库最大连接数与实例数推算池上限。
  2. 设置预热与等待超时。
  3. 配置空闲/最大存活回收策略。
  4. 开启借出检测或定义初始化钩子。
  5. 构建池并压测校准。

代码或图示

let pool = sqlx::postgres::PgPoolOptions::new()
    .max_connections(10)
    .min_connections(2)
    .acquire_timeout(std::time::Duration::from_secs(3))
    .idle_timeout(std::time::Duration::from_secs(600))
    .max_lifetime(std::time::Duration::from_secs(1800))
    .test_before_acquire(true)
    .connect(&url)
    .await?;

常见误区

  • 池上限设得超过数据库 max_connections 可承受范围。
  • 不配 acquire_timeout,故障时请求无限等待。

追问

  • min_connections 越大越好吗?答:预热减少冷启动,但常驻占用数据库连接,按实例规模权衡。
  • max_lifetime 为什么要短于数据库侧连接超时?答:避免使用已被服务端单方面关闭的老化连接,具体阈值结合后端配置。

04.4.8.1-076 min_connections 预热与冷启动要权衡什么?

一句话结论

min_connections 让池启动时先建立若干空闲连接,消除首批请求的建连延迟;代价是常驻占用数据库连接,实例数多时要与数据库最大连接数一起核算。

概念解释

服务冷启动时按需建连包含握手、认证、会话初始化成本,首批请求延迟明显。预热把这部分成本前移到启动阶段。预热数量不是越大越好:每个实例都常驻最小连接,实例乘以预热数不能超过数据库连接预算。弹性伸缩频繁的场景,预热数应偏保守,避免空闲连接浪费。

原理流程

  1. 启动构建池,按 min_connections 建立初始连接。
  2. 首批请求直接取空闲连接。
  3. 并发上升到超过预热数后按需新建到上限。
  4. 低峰期按空闲回收策略回落。

代码或图示

let pool = PgPoolOptions::new()
    .min_connections(2)
    .max_connections(10)
    .connect(&url)
    .await?;

常见误区

  • 预热数设得与上限相同,所有实例常驻满连接。
  • 忽略多实例总和:单池 10 连接 × 20 实例可能超过数据库上限。

追问

  • 预热失败会怎样?答:按构建池时的错误处理;预热连接建立失败的行为以当前版本实现为准。
  • 无预热可以吗?答:可以,靠按需建连,代价是冷启动请求变慢。

04.4.8.1-077 acquire_timeout 什么时候触发,报什么错?

一句话结论

池中无空闲连接、已达上限且等待超时仍借不到连接时触发 acquire_timeout,返回池超时类错误;它是并发过高、连接被长期占用或池上限过小的信号。

概念解释

acquire_timeout 限制任务等待空闲连接的时长。触发场景:慢查询占用连接、事务未及时释放、池上限偏小、数据库拒绝新连接。错误属于池获取阶段,不是 SQL 执行错误。排查时先看在借连接是否被长事务/慢查询占住,再评估调大上限或优化查询。

原理流程

  1. 任务请求借连接。
  2. 空闲队列空且达上限,进入等待。
  3. 等待期间有连接归还则被唤醒取走。
  4. 超时仍无连接:返回 acquire 超时错误。
  5. 上层按容量问题或故障处理。

代码或图示

acquire → 空闲? 有 → 取出
              无 → 达上限? 否 → 新建
                          是 → 等待空闲 → 超时 → PoolTimedOut 类错误

常见误区

  • 把 acquire 超时当成 SQL 报错去优化语句。
  • 不设超时,请求在连接积压时永久挂起。

追问

  • 超时后连接会被新建吗?答:等待超时直接返回错误,不会强行突破上限建连。
  • 如何区分池超时与建连超时?答:connect_timeout 管握手阶段,acquire_timeout 管从池等待阶段,错误变体不同。

04.4.8.1-078 test_before_acquire 与断连探测是怎么做的?

一句话结论

开启后每次借出连接前先做存活探测,确认连接未被服务端断开;探测通过才交给任务,避免拿到半开连接导致首条语句报错。

概念解释

空闲连接可能被数据库、防火墙或负载均衡单方面关闭,应用侧并不知情。借出前探测发一条轻量探针(具体探针 SQL 以后端实现为准),失败则丢弃该连接并补建。代价是每次借出多一次探测开销;网络稳定、连接生命周期配置合理时可权衡关闭。after_connect 与借出检测是两个不同时机。

原理流程

  1. 任务借出连接。
  2. 若开启检测,对空闲连接执行探针。
  3. 探针成功:交给任务。
  4. 探针失败:关闭坏连接,按需要新建后再交付。

代码或图示

let pool = PgPoolOptions::new()
    .test_before_acquire(true)
    .connect(&url)
    .await?;

常见误区

  • 以为池能自动知道服务端断连:没有探测时,断连要等到下一次使用才暴露。
  • 把探测配置成重查询,反而拖慢借出。

追问

  • 探针具体执行什么语句?答:以后端驱动实现为准,通常是轻量存活查询;不确定时查当前版本文档。
  • 关闭检测有什么风险?答:半开连接被借出,首条业务语句报 IO/协议错误。

04.4.8.1-079 idle_timeout 与 max_lifetime 分别解决什么问题?

一句话结论

idle_timeout 回收长期空闲的连接以释放数据库侧资源;max_lifetime 限制连接总存活时间,避免老化连接遇到服务端超时、配置变更或内存累积问题。

概念解释

空闲连接在低峰期没有存在必要,idle_timeout 让闲置超期的连接被关闭。max_lifetime 面向连接整体寿命:即使一直活跃,达到寿命也会被替换,防止长期连接积累状态问题或撞上数据库/中间件的连接超时。两者配合:空闲回收应对波谷,寿命轮换应对长期老化。

原理流程

  1. 连接归还后记录空闲起始时间。
  2. 空闲超过 idle_timeout:后台回收。
  3. 连接存活超过 max_lifetime:下次归还后替换。
  4. 新建连接补足池规模。

代码或图示

.idle_timeout(Duration::from_secs(600))
.max_lifetime(Duration::from_secs(1800))

常见误区

  • 只设空闲超时不设最大寿命:老化连接长期复用。
  • max_lifetime 设得比数据库侧连接超时还长:先被服务端断开。

追问

  • 连接达到寿命时正在被借用怎么办?答:等其归还后再替换,不会强行切断在借连接;具体行为以实现为准。
  • 短寿命连接有什么代价?答:轮换频繁,建连开销上升,需在稳定性与开销间平衡。

04.4.8.1-080 连接池耗尽的排查路径是什么?

一句话结论

按「在借连接是否被占住 → 占住的是哪些任务/事务 → 慢查询或外部等待 → 池上限与数据库承载」逐层排查,先定位连接持有者,再决定优化语句、缩短事务还是调参。

概念解释

池耗尽表现为 acquire 超时、请求排队。排查顺序:看池状态在借/空闲计数;追踪在借连接对应的请求与事务;检查慢查询日志与事务持续时间;确认是否有连接未归还(泄漏);最后核对池上限与数据库最大连接数。不要一上来就调大上限,可能把压力转嫁给数据库。

原理流程

  1. 采集池状态:在借数、等待队列、错误计数。
  2. 关联链路日志,找出持有连接的请求。
  3. 检查这些请求是否卡在慢 SQL、外部调用或未结束事务。
  4. 确认连接是否被遗忘未 drop。
  5. 针对性优化后再评估池参数。

代码或图示

池耗尽
├── 在借数打满 → 慢查询 / 长事务 / 外部等待
├── 连接泄漏 → 句柄被长期持有或存进全局状态
├── 上限过小 → 并发需求超过配置
└── 数据库侧拒绝 → 服务端连接数/资源限制

常见误区

  • 直接调大 max_connections 缓解表象,根因未除。
  • 只看应用错误,不查数据库侧会话与锁等待。

追问

  • 怎么确认是泄漏而非慢?答:泄漏连接长期不归还且对应请求已结束;慢连接对应仍在运行的查询。结合链路时间线判断。
  • 池状态怎么暴露给监控?答:读取池状态计数接入 metrics,按在借数与等待超时告警。

04.4.8.1-081 连接泄漏如何识别与避免?

一句话结论

连接泄漏指连接包装器未被 drop、连接长期在借且无对应活跃任务;识别靠在借计数只增不减、请求结束后连接不归还;避免方式是事务/连接句柄严格限定在作用域内,不存入长生命周期结构。

概念解释

PoolConnection/Transaction 包装器 drop 时归还连接。若句柄被存进全局状态、缓存、静态变量,或跨任务移动后不再被丢弃,连接就一直占用。常见写法错误:把事务句柄放进 Extension、把连接存进复用结构体。识别信号:空闲连接逐步归零、在借数单调上升、acquire 超时增多。

原理流程

  1. 句柄在函数作用域内借出。
  2. 函数结束时正常 drop 归还。
  3. 若句柄被移出作用域保存,归还时机丢失。
  4. 监控发现在借数持续增长。
  5. 代码审查找出长期持有句柄的位置。

代码或图示

// 正确:句柄随作用域结束归还
async fn handler(pool: &PgPool) -> Result<(), sqlx::Error> {
    let mut tx = pool.begin().await?;
    do_work(&mut tx).await?;
    tx.commit().await?;
    Ok(())
}

常见误区

  • 在结构体内保存 PoolConnection 字段供多次调用复用。
  • spawn 的任务里持有句柄却不结束,连接被挂起任务长期占用。

追问

  • 语言层面怎么防止泄漏?答:PoolConnection 不 Clone,所有权与作用域受限;审查句柄传递路径即可。
  • 泄漏后重启能恢复吗?答:重启释放连接,但根因仍在,会再次积累。

04.4.8.1-082 池大小如何与 CPU、数据库最大连接数协调?

一句话结论

池上限主要受数据库最大连接数与实例数约束,不是越大越好;公式上各实例池上限之和应小于数据库 max_connections,预留管理连接;CPU 核数影响并发任务数,不直接决定连接数。

概念解释

数据库连接是稀缺资源,每个连接占用服务端内存与工作区。多实例部署时:单实例池上限 × 实例数 + 预留连接 < 数据库最大连接数。异步应用单实例可在较少连接上支撑较多并发任务,但连接数仍要匹配数据库处理能力。压测时观察等待队列、查询延迟与数据库负载来校准,而非照搬教程数值。

原理流程

  1. 查数据库最大连接配置。
  2. 按实例数与预留管理连接推算总可用连接。
  3. 单实例池上限 = 可用连接 / 实例数,留余量。
  4. 压测观察 acquire 等待与查询耗时。
  5. 按需微调上限与超时。

代码或图示

数据库 max_connections = 100
预留管理/故障切换 = 20
应用实例 = 8
单实例池上限 ≈ (100 - 20) / 8 = 10

常见误区

  • 单实例池设 50,十个实例直接打满数据库。
  • 按 CPU 核数等比放大连接数:IO 型负载与连接数无直接换算。

追问

  • 异步服务连接数可以比同步服务少吗?答:异步在单连接上交替服务任务,但仍受单连接查询串行约束;按压测结果定。
  • 连接数过小会怎样?答:请求在池等待,吞吐被连接数卡住。

04.4.8.1-083 sqlx-cli 如何安装,对环境有什么要求?

一句话结论

通过 cargo install sqlx-cli 安装命令行工具;迁移与 prepare 命令需要 DATABASE_URL 指向可访问数据库,CLI 按启用的后端编译对应驱动。

概念解释

sqlx-cli 提供数据库创建、迁移管理与离线 prepare 能力。安装时可按目标后端裁剪 feature(如只装 postgres)。运行命令时从环境变量、.env 或 --database-url 读取连接串。CLI 是开发/运维工具,不影响运行时依赖;生产镜像通常不需要打包 CLI。

原理流程

  1. cargo install sqlx-cli(按需选后端 feature)。
  2. 配置 DATABASE_URL。
  3. CLI 连接数据库执行对应子命令。
  4. 迁移脚本存放在工程 migrations/ 目录。

代码或图示

cargo install sqlx-cli
# 可选:仅安装 postgres 后端,具体 feature 名以 crate 文档为准
# cargo install sqlx-cli --no-default-features --features postgres
sqlx database create

常见误区

  • 把 CLI 作为运行时依赖写进 [dependencies]。
  • 未设 DATABASE_URL 就跑迁移命令,连接失败。

追问

  • sqlx 与 cargo sqlx 两个入口有何区别?答:cargo sqlx 是 cargo 子命令包装,sqlx 是独立可执行文件;prepare 需走 cargo sqlx。
  • CLI 版本要与库版本对齐吗?答:建议版本配套,避免元数据/迁移格式不兼容。

04.4.8.1-084 migrate add、run、revert、info 各自做什么?

一句话结论

add 生成新迁移脚本,run 应用所有未执行迁移,revert 回滚最近迁移,info 查看迁移与数据库的应用状态;--source 可指定迁移目录。

概念解释

迁移按版本顺序管理:add 在 migrations/ 下生成带版本号的脚本文件;run 对比版本表与目录,应用pending 脚本;revert 执行回滚脚本(可逆迁移);info 列出各迁移在本地与库中的状态。CLI 与运行时 migrate! 使用同一目录约定。子命令细节以后端当前版本文档为准。

原理流程

  1. sqlx migrate add <name> 生成版本脚本。
  2. 编辑 up 逻辑(与 down 脚本,若可逆)。
  3. sqlx migrate run 应用 pending 迁移并记录版本。
  4. sqlx migrate info 核对状态;revert 回滚最近一条。

代码或图示

sqlx migrate add create_users
sqlx migrate run
sqlx migrate info
sqlx migrate revert

常见误区

  • 已应用的迁移脚本再手动修改内容:版本表记录与脚本不一致。
  • 把 revert 当常规发布流程:生产环境通常不回滚已上线迁移。

追问

  • 迁移目录不在默认位置怎么办?答:用 --source 指定目录,或在配置中约定。
  • info 显示某迁移未应用但库里已有表是什么原因?答:历史表未纳入版本管理,需要核对初始化方式。

04.4.8.1-085 -r 可逆迁移的 up/down 成对文件是怎么组织的?

一句话结论

migrate add -r <name> 同时生成 <version>_<name>.up.sql 与 <version>_<name>.down.sql:up 应用变更,down 回滚变更;简单迁移与可逆迁移不能混用。

概念解释

可逆迁移要求每个变更都有对应回滚脚本,revert 才能执行 down。不加 -r 生成单文件 up 脚本,无法回滚。CLI 会拒绝简单迁移与可逆迁移混合使用。编写 down 时要保证「up 后立刻 redo」让结构回到原状;数据迁移的回滚往往无法完全还原,需在脚本里说明限制。

原理流程

  1. sqlx migrate add -r <name> 生成成对文件。
  2. up.sql 写正向 DDL/DML。
  3. down.sql 写逆向逻辑。
  4. run 执行 up,revert 执行 down。

代码或图示

migrations/
├── 20261119120000_create_users.up.sql
└── 20261119120000_create_users.down.sql

常见误区

  • up 改了列类型,down 直接转回旧类型但不处理数据转换。
  • 混用单文件与成对文件,CLI 报错拒绝。

追问

  • 不可逆的数据变更怎么做回滚?答:down 尽量恢复结构,数据层面依赖备份与前镜像;不要承诺完全还原业务数据。
  • 生产可以执行 revert 吗?答:谨慎,优先用新增正向迁移修正结构;回滚仅限预发/本地排错。

04.4.8.1-086 迁移版本表里记录了什么?

一句话结论

SQLx 在数据库内维护迁移历史表(默认名 _sqlx_migrations),记录已应用迁移的版本号、描述、执行时间与脚本校验和,用于判断哪些迁移 pending。

概念解释

版本表是迁移机制的真相来源:run 读取表中已应用版本,与目录脚本对比得出待执行集合。校验和用于发现脚本被改动。表结构与列名以当前版本实现为准。新环境建库后首次 run 会创建该表并依次应用脚本。手动改版本表会破坏迁移判断,应避免。

原理流程

  1. 首次运行迁移时创建历史表。
  2. 每应用一条迁移,写入版本、描述、校验和与时间。
  3. 后续 run 对比目录版本与表记录。
  4. 脚本校验和与记录不符时给出警告或错误。

代码或图示

_sqlx_migrations
├── version(迁移版本号)
├── description(描述)
├── installed_on(执行时间)
└── checksum(脚本校验和)

常见误区

  • 直接在表里删记录想「重置迁移状态」:应走正规 revert 或重置库。
  • 改了已应用脚本内容却不处理校验和:后续环境报错。

追问

  • 校验和不匹配会怎样?答:CLI/运行时按策略警告或拒绝继续;具体行为以当前版本为准。
  • 多环境并行部署如何避免迁移冲突?答:迁移版本只增不改,变更通过新增迁移完成。

04.4.8.1-087 migrate! 宏在启动时如何内嵌并执行迁移?

一句话结论

migrate! 宏在编译期把 migrations/ 目录脚本嵌入二进制,运行时连接数据库后按版本顺序应用 pending 迁移;便于单二进制部署,无需在生产环境外挂迁移目录与 CLI。

概念解释

启用 migrate feature 后,sqlx::migrate!("./migrations") 在构建期读取脚本目录生成迁移集合。程序启动时调用运行方法,对比库内版本表执行未应用脚本。嵌入方式让部署产物自包含,但脚本更新需要重新编译。是否在应用启动时自动跑迁移,还是由独立发布步骤执行,按团队发布策略决定。

原理流程

  1. 编译期 migrate! 读取目录脚本并嵌入。
  2. 程序启动建立连接。
  3. 迁移器读取版本表,对比嵌入脚本集合。
  4. 按版本顺序执行 pending 迁移并记录。

代码或图示

let pool = sqlx::PgPool::connect(&url).await?;
sqlx::migrate!("./migrations")
    .run(&pool)
    .await?;

常见误区

  • 认为嵌入迁移后脚本目录就不用维护:源码目录仍是真相来源。
  • 多实例同时启动自动跑迁移:需确认迁移并发执行策略,避免并发应用冲突。

追问

  • 嵌入的是脚本文本还是编译后产物?答:嵌入 SQL 脚本内容,运行时在数据库执行;具体嵌入形式以实现为准。
  • 不想启动自动迁移怎么做?答:去掉启动时调用,用 CLI 在发布流程中单独执行迁移。

04.4.8.1-088 可重复迁移(repeatable migration)是什么,文件命名有何约定?

一句话结论

可重复迁移用于视图、存储过程等「脚本内容变了就重新执行」的对象,不依赖递增版本;具体文件命名与识别规则以 sqlx 当前版本文档为准(待确认),不要凭记忆写死前缀。

概念解释

普通迁移按版本号只执行一次;可重复迁移在校验和变化时重新运行,适合定义可被脚本重建的数据库对象。SQLx 的 MigrationType 区分普通与可重复类型。由于命名约定在版本间可能调整,落地前应查 docs.rs/sqlx 迁移章节确认文件命名格式与 migrate add 是否有对应标志。

原理流程

  1. 查当前文档确认可重复迁移的文件命名/生成方式。
  2. 编写可重建对象的脚本。
  3. 迁移器按校验和判断是否需要重新执行。
  4. 变更脚本内容后下次启动自动重跑。

代码或图示

待确认:可重复迁移文件命名前缀与版本号取值规则;
验证方式:docs.rs/sqlx 当前版本 migrate 模块文档,或 `sqlx migrate add --help`。

常见误区

  • 把普通 DDL 迁移写成可重复类型:重复执行可能破坏已有数据。
  • 凭旧版本记忆命名,导致迁移器识别错误。

追问

  • 视图变更适合哪种迁移?答:视图定义可由脚本完整重建,通常适合可重复迁移;最终以工具支持为准。
  • 可重复迁移也有 down 脚本吗?答:其回滚语义与普通可逆迁移不同,按文档约定处理。

04.4.8.1-089 编写迁移脚本有哪些规范?

一句话结论

迁移只增不改、按顺序可追溯;脚本自身尽量明确、可重复部署;数据变更与结构变更分开考虑;禁止手工修改已在其它环境应用过的脚本。

概念解释

迁移是团队协作的历史记录:已应用到任一环境的脚本应冻结,新需求用新增迁移解决。脚本要考虑失败回滚与并发部署。大表 DDL 要评估锁与复制延迟。纯结构迁移与数据回填分开,避免长事务锁表。脚本内容应代码评审,与应用代码同批发布。

原理流程

  1. 新增迁移脚本,版本号递增。
  2. 评审 DDL/DML 对锁、数据、回滚的影响。
  3. 本地与测试库执行验证。
  4. 提交后不再修改该脚本。
  5. 问题修正用后续迁移承接。

代码或图示

规范要点:
- 不改历史脚本
- 结构变更与数据回填分离
- 大表变更评估锁与耗时
- down 脚本尽量可逆
- 迁移纳入版本管理与评审

常见误区

  • 直接编辑已上线脚本「同步结构」,导致各环境校验和不一致。
  • 一条迁移里混大表加列与全量数据更新。

追问

  • 迁移在 CI 测试库怎么跑?答:测试前从空库执行全部迁移,验证脚本顺序与幂等行为。
  • 上线时迁移与应用代码谁先谁后?答:遵循向后兼容:先发布兼容旧代码的迁移,再部署应用;破坏性变更分阶段进行。

04.4.8.1-090 sqlx::Error 主要分哪几类?

一句话结论

sqlx::Error 大致分为数据库返回错误、连接/IO/TLS 错误、池错误、解码/编码错误、配置与协议错误、行不存在等;按变体分类后再决定业务映射与重试。

概念解释

错误顶层类型是 sqlx::Error,各变体对应失败阶段。Database 变体包裹后端 DatabaseError,携带错误码、约束名等细节;Io/Tls 是传输层问题;PoolTimedOut/PoolClosed 是池阶段;Decode/Encode 是类型转换;RowNotFound 是基数问题。完整变体列表以 docs.rs 当前版本为准,答题时按阶段归类即可。

原理流程

  1. 操作返回 Result<_, sqlx::Error>。
  2. 按阶段匹配变体:池 → 连接 → 数据库 → 解码。
  3. Database 错误再读取内部细节。
  4. 映射为应用层错误类型或决定重试。

代码或图示

sqlx::Error
├── Database(Box<dyn DatabaseError>)  服务端约束/语法/事务错误
├── Io / Tls / Protocol                传输与协议层
├── PoolTimedOut / PoolClosed          连接池阶段
├── Decode / Encode                    类型编解码
├── RowNotFound                        期望单行但无结果
└── Configuration / ...                配置与其它

常见误区

  • 把所有错误都包装成「数据库错误」,丢失阶段信息。
  • 不匹配变体直接 unwrap,把可处理错误变成 panic。

追问

  • 怎么拿到后端原始错误码?答:Error::Database 里的 DatabaseError 提供 code()/constraint() 等访问器,具体方法名以当前版本为准。
  • 错误能跨 .await 传递吗?答:sqlx::Error 通常满足 Send,异步链路可返回;具体约束按类型定义确认。

04.4.8.1-091 DatabaseError 能提供哪些细节?

一句话结论

数据库错误可读取错误消息、后端错误码、约束名、表/列信息等,用于区分唯一键冲突、外键冲突、检查约束等具体原因;细节可用随后端不同。

概念解释

DatabaseError trait 暴露规范化访问器:message() 服务端消息,code() 后端错误码,constraint() 触发的约束名,部分后端提供表/列名。上层据此把数据库错误翻译成业务错误,而不是展示原始消息。错误码语义随后端方言,映射表要按所连数据库维护。

原理流程

  1. 匹配 Error::Database(db_err)。
  2. 读 code() 或 constraint() 判断冲突类型。
  3. 结合约束名定位具体业务规则。
  4. 转换为应用错误枚举返回给接口层。

代码或图示

match sqlx::query("...").execute(&pool).await {
    Ok(r) => Ok(r.rows_affected()),
    Err(sqlx::Error::Database(e)) => {
        if let Some(constraint) = e.constraint() {
            Err(AppError::Conflict(constraint.to_string()))
        } else {
            Err(AppError::Db(e.to_string()))
        }
    }
    Err(e) => Err(AppError::Db(e.to_string())),
}

常见误区

  • 直接把数据库原始消息抛给前端:泄露表结构与内部信息。
  • 只看消息文本判断冲突类型:消息文案随版本/语言变化,应匹配错误码或约束名。

追问

  • 约束名在迁移里怎么定?答:给唯一/外键约束显式命名,便于应用层按名识别;匿名约束名难定位。
  • 后端错误码格式一致吗?答:不一致,Postgres/MySQL/SQLite 各自编码体系,映射层要分别处理。

04.4.8.1-092 唯一键冲突如何识别并转成业务错误?

一句话结论

执行写语句后匹配 Error::Database,按错误码种类或约束名判断唯一键冲突,再映射为「资源已存在」类业务错误;不要靠匹配错误消息文本。

概念解释

唯一索引/主键重复写入时服务端拒绝,应用需要返回友好的 409/业务码。识别路径:先按数据库错误种类(如唯一违例)分类,再按约束名区分是哪条业务规则。映射后日志保留原始错误详情,对外只暴露业务语义。新增唯一约束时要同步更新应用层识别与提示。

原理流程

  1. 执行插入或 upsert 语句。
  2. 捕获 Error::Database。
  3. 判断错误种类为唯一违例(或匹配约束名)。
  4. 转换为 AppError::Duplicate(...),记录原始错误。
  5. 接口层映射为对应状态码与提示。

代码或图示

let err = match insert_result {
    Ok(v) => return Ok(v),
    Err(sqlx::Error::Database(e)) if is_unique_violation(&e) => {
        AppError::Duplicate(e.constraint().unwrap_or("").to_string())
    }
    Err(e) => AppError::Db(e.to_string()),
};

常见误区

  • 用错误消息里的中文/英文关键字判断冲突,换语言或版本即失效。
  • 所有冲突都报「用户名已存在」,约束名丢失导致定位不准。

追问

  • is_unique_violation 怎么实现?答:读 DatabaseError::kind() 返回的错误种类枚举,匹配唯一违例;枚举名以当前版本为准。
  • upsert 场景还需要处理唯一冲突吗?答:ON CONFLICT 已在库内消化冲突;未走 upsert 的插入才需要应用层识别。

04.4.8.1-093 外键冲突与检查约束冲突怎么识别?

一句话结论

外键冲突分为「插入引用不存在父行」与「父行被引用仍删除」两类,检查约束冲突由 CHECK 规则触发;同样按错误种类与约束名识别,映射为对应的业务校验错误。

概念解释

外键违例错误码与唯一违例不同,约束名指向关联关系;CHECK 约束违例对应业务规则限制(如金额为正)。应用层识别后分别提示:引用关系不存在、有关联数据不能删除、字段值不满足规则。约束命名清晰是可识别的前提。删除父行前也可先做应用层存在性检查,但数据库约束仍是最后防线。

原理流程

  1. 写操作触发约束违例。
  2. 读取错误种类区分外键/CHECK。
  3. 按约束名定位业务规则。
  4. 映射为对应业务错误与提示。

代码或图示

外键违例:子行引用缺失父行 / 删除仍被子行引用
CHECK 违例:字段值不满足规则表达式
识别依据:错误种类 + 约束名,不看消息文本

常见误区

  • 把外键冲突都当成「数据不存在」返回 404,语义错误。
  • 依赖应用层先查一遍就不加数据库约束:并发下仍可能突破。

追问

  • 删除被引用记录怎么给前端提示?答:映射为「存在关联数据,无法删除」,必要时列出关联类型。
  • 约束名无法取到时怎么办?答:按错误大类兜底提示,并在日志记录原始错误;后续补命名约束。

04.4.8.1-094 RowNotFound 与 fetch_optional 怎么选?

一句话结论

业务上记录必然存在(按内部 ID 查询且已校验)用 fetch_one,缺失属于异常;可能不存在的资源用 fetch_optional,零行返回 None 再映射为 404;不要用 fetch_one 处理正常的空结果。

概念解释

fetch_one 在零行时返回 RowNotFound 错误;fetch_optional 把零行转为 Ok(None)。选择取决于空结果是异常还是预期分支。接口查询资源大概率用 fetch_optional,再把 None 映射为未找到错误;内部流程保证存在时用 fetch_one,空结果作为错误暴露。

原理流程

  1. 判断空结果是否为业务合法分支。
  2. 合法:fetch_optional,None → 404/默认值。
  3. 异常:fetch_one,RowNotFound 进入错误日志。
  4. 多结果场景另选 fetch 方法并加 LIMIT。

代码或图示

let user = sqlx::query_as::<_, User>("SELECT * FROM users WHERE id = $1", )
    .bind(id)
    .fetch_optional(&pool)
    .await?
    .ok_or(AppError::NotFound)?;

常见误区

  • 用 fetch_one 查可选资源,把正常 404 变成 500 错误链路。
  • 用 fetch_optional 查必须存在的内部记录,把缺陷掩盖成空值。

追问

  • RowNotFound 属于哪类错误?答:SQLx 顶层 Error 的一个变体,表示期望单行而结果为空。
  • 查询可能返回多行时用哪个?答:fetch_all 或流式 fetch,必要时 LIMIT 1 收窄基数。

04.4.8.1-095 如何用 thiserror 分层包装 sqlx::Error?

一句话结论

定义应用错误枚举,用 thiserror 派生变体包装 sqlx::Error 或映射后的业务错误;数据访问层返回应用错误,接口层只认识应用错误类型,底层驱动类型不泄露到边界。

概念解释

分层约定:底层把 sqlx::Error 翻译成领域错误(NotFound、Conflict、Db),保留原始错误作为来源;thiserror 负责 Display/From 实现,anyhow 用于应用层临时聚合。驱动细节(连接池、解码)收敛在数据访问模块。错误枚举区分可对外暴露的业务语义与内部故障。

原理流程

  1. 定义 AppError 枚举,含 NotFound/Conflict/Db 等变体。
  2. 实现从 sqlx::Error 到 AppError 的转换或在仓库方法内匹配。
  3. 数据访问方法返回 Result<_, AppError>。
  4. 接口层把 AppError 映射为响应;内部错误保留 source 链。

代码或图示

#[derive(Debug, thiserror::Error)]
pub enum AppError {
    #[error("未找到资源")]
    NotFound,
    #[error("资源冲突: {0}")]
    Conflict(String),
    #[error("数据库错误")]
    Db(#[from] sqlx::Error),
}

常见误区

  • 直接把 sqlx::Error 作为 handler 返回类型:驱动类型泄露到 API 边界。
  • 用 anyhow::Error 贯穿所有层,丢失可匹配的错误语义。

追问

  • #[from] sqlx::Error 会不会把业务冲突也归为 Db?答:会;需要先匹配冲突变体转换为 Conflict,剩余再走 From 兜底。
  • 错误链怎么保留?答:thiserror 变体带 source 字段包装原始错误,日志层沿 source 输出详情。

04.4.8.1-096 流式查询 fetch 与 Stream 的内存行为是什么?

一句话结论

fetch 返回异步流,结果行按需从网络读取并逐行解码,不一次性把全部结果落内存;消费时要逐行处理并在出错时正确结束流,连接随流结束归还。

概念解释

列表结果集很大时 fetch_all 会把所有行解码进 Vec,内存峰值随行数增长。fetch 配合 StreamExt::next 逐行拉取,解码一行处理一行。流未耗尽时连接被占用;处理中途返回错误要丢弃流以释放连接。背压由异步流消费节奏控制,不会无限制从网络读入。

原理流程

  1. 查询通过 fetch(&pool) 得到流。
  2. 循环 next().await 取下一行。
  3. 每行解码后处理(写入响应、聚合、转发)。
  4. 流结束或丢弃,连接归还池。
  5. 行级错误在 next 返回的 Result 中暴露。

代码或图示

use futures_util::TryStreamExt;

let mut rows = sqlx::query_as::<_, User>("SELECT * FROM users ORDER BY id")
    .fetch(&pool);

while let Some(row) = rows.try_next().await? {
    process(row);
}

常见误区

  • 对大结果集用 fetch_all,内存被撑爆。
  • 拿到流后不消费也不丢弃,连接长期被挂起流占用。

追问

  • 流能并行处理行吗?答:单连接上行读取是串行的;并行处理需要分批取数或多连接,注意连接占用。
  • 流式读取中途网络断开怎么表现?答:next 返回 IO/协议错误,停止消费并释放连接。

04.4.8.1-097 大结果集分页:offset 分页与 keyset 分页有何区别?

一句话结论

offset 分页按 LIMIT/OFFSET 跳过前导行,实现简单但深分页扫描成本高、数据变动时可能重复或丢行;keyset(游标)分页用上一页最后一个排序键作为条件继续取,深分页稳定且可走索引。

概念解释

offset 第 N 页要扫描并跳过前 N 行,页码越深成本越高;列表中途新增/删除记录会导致页边界漂移。keyset 分页要求排序键唯一稳定,查询带上 WHERE key < last_key ORDER BY key LIMIT n,每次从断点继续。游标序列化的是排序键组合,不是页码。两种方式按场景选择:后台浅分页可用 offset,面向用户的长列表用 keyset。

原理流程

  1. 确定稳定唯一的排序键(通常加主键兜底)。
  2. offset:计算 (page-1)*size,拼 LIMIT/OFFSET。
  3. keyset:保存上一页末尾键,下一页按键条件过滤。
  4. 比较各页结果,核对无重复无遗漏。

代码或图示

-- offset
SELECT * FROM users ORDER BY id LIMIT 20 OFFSET 40;

-- keyset
SELECT * FROM users WHERE id > $1 ORDER BY id LIMIT 20;

常见误区

  • 排序键不唯一就做 keyset:翻页出现重复/遗漏。
  • 深分页仍用大 offset,数据库扫描大量前导行。

追问

  • 游标里要存哪些字段?答:排序涉及的全部键(如 created_at, id),缺一不可保证稳定顺序。
  • 总条数还要不要返回?答:keyset 场景总数可单独 count 或不展示精确总数。

04.4.8.1-098 #[sqlx::test] 属性宏怎么用,隔离性如何保证?

一句话结论

#[sqlx::test] 标记的测试在独立数据库/架构上运行迁移并隔离数据,避免测试间相互污染;它需要测试环境可连接数据库或按离线方式配置,具体临时库机制以当前版本文档为准(待确认)。

概念解释

普通集成测试共享开发库会相互影响数据。sqlx::test 宏为每个测试准备隔离环境:常见做法是创建临时数据库或临时 schema,跑完清理。测试内拿到连接/池执行断言。该宏与标准 #[tokio::test] 的关系、是否自动跑迁移,需要对照当前版本文档确认;不确定点标注待确认。

原理流程

  1. 测试函数加 #[sqlx::test],签名接收连接参数。
  2. 宏在运行前准备隔离数据库环境。
  3. 执行迁移(按宏配置)与测试逻辑。
  4. 断言后清理临时环境。

代码或图示

#[sqlx::test]
async fn create_user(pool: sqlx::PgPool) -> Result<(), sqlx::Error> {
    let id = sqlx::query_scalar!("INSERT INTO users (name) VALUES ($1) RETURNING id", "anna")
        .fetch_one(&pool)
        .await?;
    assert!(id > 0);
    Ok(())
}

常见误区

  • 测试直接连开发库,用例顺序依赖导致偶发失败。
  • 以为测试宏自动回滚所有写入:隔离/回滚机制以宏实现为准,需验证。

追问

  • #[sqlx::test] 需要哪个 feature?答:以当前版本文档为准,通常与测试支持相关的 feature 配合;不确定时查 docs.rs。
  • 并行测试会不会争用同一临时库?答:隔离机制按测试分配独立环境;并行行为以文档与实际测试结果为准。

04.4.8.1-099 测试中用事务回滚包裹用例是什么模式?

一句话结论

每个测试在一个事务内写入数据,断言结束后回滚,不提交任何变更,从而在共享测试库上保持用例间数据隔离;适用于不支持临时库的场景。

概念解释

模式流程:测试开始 begin,所有仓库调用借用该事务句柄,断言后 rollback。由于不 commit,表内不留测试数据,下一用例从干净状态开始。前提是被测函数接收连接/事务句柄而非内部自取池连接;否则写入脱离事务无法回滚。注意回滚模式与真实提交路径略有差异,关键提交逻辑仍需独立集成测试覆盖。

原理流程

  1. 测试开启事务 tx。
  2. 业务方法接收 &mut tx 执行写入。
  3. 断言查询结果(同事务内可见)。
  4. 测试结束回滚,数据不落库。
  5. 下一用例重复。

代码或图示

#[tokio::test]
async fn create_user_rollback() -> Result<(), sqlx::Error> {
    let mut tx = pool.begin().await?;
    create_user(&mut tx, "anna").await?;
    let found = find_by_name(&mut tx, "anna").await?;
    assert!(found.is_some());
    tx.rollback().await?;
    Ok(())
}

常见误区

  • 业务方法内部从池里取连接:测试事务包不住其写入。
  • 测试提交了数据又依赖手动清理,残留影响其它用例。

追问

  • 这种模式能测 commit 行为吗?答:不能,提交路径需另起用例真实写入并清理。
  • 并行测试共用库会互相干扰吗?答:未提交事务内数据对其它连接不可见,回滚后无残留;前提是各用例独立事务。

04.4.8.1-100 SQLx 类型在异步运行时下的 Send/Sync 边界是什么?

一句话结论

池句柄 Pool 可克隆并跨任务共享(Send + Sync),事务句柄与连接是可变借用资源,不能在多个异步任务间共享;查询执行借用连接,跨 .await 时借用关系必须满足 Send 约束。

概念解释

Web 应用把 Pool 放入全局状态跨 handler 共享,依赖其线程安全。Transaction/Connection 持有单连接,按可变借用独占使用,不实现可共享的并发访问。查询 future 需要满足 Send 才能被 tokio 多线程运行时调度;连接与绑定参数跨 await 移动时必须 Send。违反边界会在编译期报 Send 相关错误,而不是运行期数据竞争。

原理流程

  1. Pool 作为共享状态跨任务传递。
  2. 每任务独立 acquire 或 begin,得到独占句柄。
  3. 查询 future 在 await 期间持有句柄借用。
  4. 编译器校验 future 与捕获类型满足 Send。
  5. 句柄 drop 后连接归还池。

代码或图示

// Pool 可克隆、可进 State
let pool: sqlx::PgPool = sqlx::PgPool::connect(&url).await?;
let shared = pool.clone();

// 句柄不跨任务共享:每个任务各自 begin
async fn handler(pool: &sqlx::PgPool) -> Result<(), sqlx::Error> {
    let mut tx = pool.begin().await?;
    // ... 查询借用 &mut tx
    tx.commit().await?;
    Ok(())
}

常见误区

  • 把 Transaction 放进 Arc 共享给多个任务并发使用:可变连接无法安全共享。
  • 绑定参数含非 Send 类型跨 await,future 不满足 Send,编译报错。

追问

  • 编译报 future 不满足 Send 怎么排查?答:找出跨 await 持有的非 Send 类型(如 Rc、引用跨线程),改为跨任务安全类型。
  • 连接池为什么能共享而连接不能?答:池是线程安全的句柄集合,内部用同步结构管理空闲队列;单连接一次只服务一条事务链路。