SQLx 编译期查询检查需 DATABASE_URL 指向结构一致且可访问的 MySQL 数据库,依赖 nightly Rust、sqlx-cli 生成 schema 缓存,并要求列名大小写严格匹配、使用 MySqlPool 异步连接。

SQLx 的 compile-time query checking 依赖 DATABASE_URL 环境变量
SQLx 的编译期检查(sqlx::query 系列宏)不是靠本地 MySQL 实例运行时验证,而是通过环境变量 DATABASE_URL 指向一个**结构一致、可访问的数据库**,在编译时连接并解析 SQL。如果你看到 error: failed to load schema 或 sqlx::migrate! cannot find database,大概率是 DATABASE_URL 没设、格式错,或数据库不可达。
必须确保:
-
DATABASE_URL=mysql://user:pass@localhost:3306/mydb(注意协议前缀是mysql://,不是mysql+async://或mysql://...后带?ssl-mode=disabled等参数时需 URL 编码) - 该库存在且用户有
SELECT权限(SQLx 只读取INFORMATION_SCHEMA,不需要写权限) - 网络可达、端口开放、MySQL 服务正在运行(5.7+ 或 8.0,8.0 默认 require_secure_transport 可能拦截,建议临时关掉或配 SSL)
启用 compile-time checking 需要 nightly Rust 和 sqlx-cli
稳定版 Rust 不支持 proc-macro 在编译期发起网络请求,所以 SQLx 的 query! 宏强制要求 #![feature(proc_macro_hygiene)] —— 实际上就是要求用 nightly 工具链。别试图绕过它,否则会卡在 macro expansion ends in an error。
同时,sqlx::query! 依赖 sqlx-cli 提供的 schema cache,必须提前生成:
- 运行
sqlx database create(如果库还不存在) - 运行
sqlx migrate run(如有 migration) - 运行
sqlx prepare --check --database-url $DATABASE_URL生成.sqlx/目录
这一步失败常见于:MySQL 用户没开 INFORMATION_SCHEMA.STATISTICS 查询权限,或表名含大写而 MySQL 配置了 lower_case_table_names=1 导致元数据不匹配。
async MySQL 连接必须用 sqlx::MySqlPool 而非 MySql
sqlx::MySql 是类型标记(用于泛型),不能直接实例化;真正做异步 I/O 的是 sqlx::MySqlPool。漏掉 Pool 就会遇到 the trait `Executor` is not implemented 或 no method named 'fetch_one' found。
安装、修复、更新或打包一个基于 Python 和 PyMySQL 实现的 Windows `mysql` 命令。适用于用户希望在 PowerShell/CMD 中输入 `mysql` 时重定向到 Python 实现、需要交互式输入 MySQL 连接信息、需要同步到当前用户本地 bin 目录,或需要将该能力封装成可公开复用的 Codex skill。
典型初始化写法:
use sqlx::MySqlPool;
#[tokio::main]
async fn main() -> Result<(), sqlx::Error> {
let pool = MySqlPool::connect(&std::env::var("DATABASE_URL")?).await?;
let row = sqlx::query("SELECT 1").fetch_one(&pool).await?;
Ok(())
}
注意:MySqlPool::connect 是异步函数,必须 await;query! 返回的是编译期校验过的 QueryAs 类型,执行时仍需传入 &pool 或 &mut transaction。
query!() 中的列名必须与数据库实际字段大小写完全一致
MySQL 在 Linux 下默认区分表名大小写但不区分列名大小写——但 SQLx 的编译期检查是按字面量严格比对的。比如数据库里字段是 user_id,你写 SELECT User_ID FROM users,即使 MySQL 执行成功,query!() 也会报 column `User_ID` not found in query。
更隐蔽的问题是 JSON 字段或生成列(generated column):SQLx 不识别 AS 别名以外的“逻辑列”,所以 SELECT data->>'$.name' AS name 是安全的,但 SELECT data->>'$.name' 会被当成无名字段,无法绑定到 struct。
建议始终显式用 AS,并在 struct 字段上加 #[sqlx(rename = "col_name")] 显式对齐。
编译期检查不是银弹:它只校验语法、表/列存在性、类型兼容性,不校验外键约束是否满足、触发器副作用、或存储过程逻辑。一旦切换数据库版本或迁移 DDL,记得重新 sqlx prepare,否则缓存过期会导致编译通过但运行时报错。

















