SQLx for Rust: 完整指南及示例

什么是 SQLx 以及为什么需要它？

\n\n

SQLx 是一个异步的、纯 Rust 数据库库，它实现了“无 ORM 的 SQL”方法。与 Diesel 或 SeaORM 等 ORM 解决方案不同，SQLx 不会将 SQL 查询隐藏在抽象层之后，而是允许您编写纯 SQL 代码，同时在编译时提供完全的類型安全。

\n\n

SQLx 的主要优点：

\n

\n
• 编译时类型安全 — SQLx 在项目构建期间直接根据数据库模式检查您的 SQL 查询。
\n
• 开箱即用的异步支持 — 该库完全支持 async/await，非常适合高负载的 Web 应用程序。
\n
• 支持多种数据库管理系统 — PostgreSQL、MySQL、SQLite 和 MSSQL。
\n
• 无魔法 — 您编写标准 SQL，该库仅帮助安全地传递参数和获取结果。
\n
• 迁移 — 内置的数据库模式迁移管理系统。
\n

\n\n

SQLx 非常适合那些需要完全控制查询、性能和类型安全，但又不想学习复杂 ORM DSL（领域特定语言）的项目。

\n\n

安装

\n\n

SQLx 通过 Cargo 包管理器安装。将依赖项添加到 Cargo.toml 文件中：

\n\n

[dependencies]\nsqlx = { version = "0.7", features = ["runtime-tokio-rustls", "postgres"] }\ntokio = { version = "1", features = ["full"] }\nanyhow = "1.0"

\n\n

根据您使用的数据库，选择相应的 feature 标志：

\n

\n
• postgres — 用于 PostgreSQL
\n
• mysql — 用于 MySQL
\n
• sqlite — 用于 SQLite
\n
• mssql — 用于 Microsoft SQL Server
\n

\n\n

对于运行时，您可以选择 runtime-tokio-rustls（推荐）或 runtime-async-std-rustls。

\n\n

快速入门

\n\n

让我们创建一个连接到 PostgreSQL 并执行查询的简单应用程序：

\n\n

use sqlx::postgres::PgPoolOptions;\nuse anyhow::Result;\n\n#[tokio::main]\nasync fn main() -> Result<()> {\n    // 创建连接池\n    let pool = PgPoolOptions::new()\n        .max_connections(5)\n        .connect("postgres://user:password@localhost/mydb")\n        .await?;\n\n    // 执行一个简单查询\n    let row: (i64,) = sqlx::query_as("SELECT $1::bigint")\n        .bind(42_i64)\n        .fetch_one(&pool)\n        .await?;\n\n    println!("结果: {}", row.0);\n\n    Ok(())\n}

\n\n

此代码创建一个包含 5 个数据库连接的连接池，执行一个带参数的查询并输出结果。

\n\n

SQLx 的主要方法和函数

\n\n

1. sqlx::query

\n

功能： 创建一个新的 SQL 查询，支持参数绑定。这是所有操作的基本构建块。

\n

参数：

\n

\n
• sql: &str — 带有占位符的 SQL 查询字符串（PostgreSQL 使用 $1, $2；MySQL/SQLite 使用 ?）
\n

\n

示例：

\n

use sqlx::query;\n\nlet query = sqlx::query("SELECT * FROM users WHERE id = $1 AND active = $2")\n    .bind(1)\n    .bind(true);

\n\n

2. .bind()

\n

功能： 将值绑定到查询参数。调用的顺序对应于 SQL 中占位符的顺序。

\n

参数：

\n

\n
• value: impl Encode + Type<DB> — 任何可以编码为数据库类型的值（i32、String、bool、Option 等）
\n

\n

示例：

\n

let user_id: i32 = 42;\nlet user_name: &str = "Alice";\n\nsqlx::query("INSERT INTO users (id, name) VALUES ($1, $2)")\n    .bind(user_id)\n    .bind(user_name)\n    .execute(&p