SQLx

SQLx 是一个异步、纯 Rust_† SQL 库，支持编译时检查查询而不使用 DSL。

• 真正异步。从头开始使用 async/await 以实现最大并发。

• 编译时检查查询（如果需要）。请参阅 SQLx 不是 ORM。

• 数据库无关。支持 PostgreSQL、MySQL、MariaDB、SQLite。

  • 版本 0.7 之前支持 MSSQL，但由于 SQLx Pro 初始化中的驱动程序全面重写，现已移除。

• 纯 Rust。Postgres 和 MySQL/MariaDB 驱动程序使用纯 Rust 编写，使用 零 不安全_††代码。

• 运行时无关。在不同的运行时（async-std / tokio / actix）和 TLS 后端（native-tls、rustls）上工作。

• 跨平台。作为原生 Rust，SQLx 将在任何支持 Rust 的地方编译。

• 内置连接池，使用 sqlx::Pool。

• 行流。数据异步地从数据库中读取，并在需要时进行解码。

• 自动语句准备和缓存。当使用高级查询 API（sqlx::query）时，语句按连接进行准备和缓存。

• 简单的（未准备）查询执行，包括将结果检索到与高级 API 使用的相同 Row 类型中。支持批量执行并从所有语句返回结果。

• 在支持的情况下使用传输层安全性 (TLS)（MySQL、MariaDB 和 PostgreSQL）。

• 使用 LISTEN 和 NOTIFY 进行异步通知，以支持 PostgreSQL。

• 支持保存点的嵌套事务。

• Any 数据库驱动程序，可以在运行时更改数据库驱动程序。一个 AnyPool 连接到 URL 方案指示的驱动程序。

安装

SQLx 与 async-std、tokio 和 actix 运行时兼容；以及 native-tls 和 rustls TLS 后端。添加依赖项时，必须选择一个具有 runtime + tls 的运行时功能。

# Cargo.toml
[dependencies]
# PICK ONE OF THE FOLLOWING:

# tokio (no TLS)
sqlx = { version = "0.7", features = [ "runtime-tokio" ] }
# tokio + native-tls
sqlx = { version = "0.7", features = [ "runtime-tokio", "tls-native-tls" ] }
# tokio + rustls
sqlx = { version = "0.7", features = [ "runtime-tokio", "tls-rustls" ] }

# async-std (no TLS)
sqlx = { version = "0.7", features = [ "runtime-async-std" ] }
# async-std + native-tls
sqlx = { version = "0.7", features = [ "runtime-async-std", "tls-native-tls" ] }
# async-std + rustls
sqlx = { version = "0.7", features = [ "runtime-async-std", "tls-rustls" ] }

Cargo 功能标志

出于向后兼容性原因，运行时和 TLS 功能可以作为一个单独的功能选择，也可以单独选择。

为了向前兼容性，应使用单独的运行时和 TLS 功能，因为组合功能可能在将来被删除。

• runtime-async-std：使用 async-std 运行时而不启用 TLS 后端。

• runtime-async-std-native-tls：使用 async-std 运行时和 native-tls TLS 后端（已软弃用）。

• runtime-async-std-rustls：使用 async-std 运行时和 rustls TLS 后端（已软弃用）。

• runtime-tokio：使用 tokio 运行时而不启用 TLS 后端。

• runtime-tokio-native-tls：使用 tokio 运行时和 native-tls TLS 后端（已软弃用）。

• runtime-tokio-rustls：使用 tokio 运行时和 rustls TLS 后端（已软弃用）。

  • Actix-web 与 Tokio 完全兼容，因此不再需要单独的运行时功能。

• tls-native-tls：使用 native-tls TLS 后端（在 *nix 上为 OpenSSL，在 Windows 上为 SChannel，在 macOS 上为 Secure Transport）。

• tls-rustls：使用 rustls TLS 后端（跨平台后端，仅支持 TLS 1.2 和 1.3）。

• postgres：添加对 Postgres 数据库服务器的支持。

• mysql：添加对 MySQL/MariaDB 数据库服务器的支持。

• mssql：添加对 MSSQL 数据库服务器的支持。

• sqlite：添加对自包含的 SQLite 数据库引擎的支持。

• any：添加对 Any 数据库驱动程序的支持，该驱动程序可以在运行时代理到数据库驱动程序。

• macros：添加对 query*! 宏的支持，该宏允许编译时检查查询。

• migrate：添加对迁移管理和 migrate! 宏的支持，该宏允许编译时嵌入迁移。

• uuid：添加对 UUID（在 Postgres 中）的支持。

• chrono：添加对来自 chrono 的日期和时间类型的支持。

• time：添加对来自 time crate 的日期和时间类型的支持（作为 chrono 的替代方案，由 query! 宏首选，如果两者都启用）

• bstr：添加对 bstr::BString 的支持。

• bigdecimal：使用 bigdecimal crate 添加对 NUMERIC 的支持。

• rust_decimal：使用 rust_decimal crate 添加对 NUMERIC 的支持。

• ipnetwork：使用 ipnetwork crate 添加对 INET 和 CIDR（在 postgres 中）的支持。

• json：使用 serde_json crate 添加对 JSON 和 JSONB（在 postgres 中）的支持。

• 离线模式现在始终启用。请参阅 sqlx-cli/README.md。

SQLx 不是一个 ORM！

SQLx 支持 编译时检查查询。然而，它不是通过提供 Rust API 或 DSL（领域特定语言）来构建查询来实现的。相反，它提供宏，这些宏接受常规 SQL 作为输入并确保它对您的数据库有效。这种工作的方式是 SQLx 在编译时连接到您的开发数据库，以便数据库本身验证（并返回有关您的 SQL 查询的一些信息）。这有一些潜在的意外影响

• 由于 SQLx 从不需要解析 SQL 字符串本身，因此可以（包括数据库扩展添加的内容）使用开发数据库接受的任何语法。
• 由于数据库允许检索查询信息的不同数量，因此从查询宏获得的 SQL 验证程度取决于数据库。

如果您正在寻找一个（异步）ORM，您可以查看基于 SQLx 构建的 ormx 或 SeaORM。

用法

请参阅 examples/ 文件夹以获取更深入的用法。

快速入门

use sqlx::postgres::PgPoolOptions;
// use sqlx::mysql::MySqlPoolOptions;
// etc.

#[async_std::main] // Requires the `attributes` feature of `async-std`
// or #[tokio::main]
// or #[actix_web::main]
async fn main() -> Result<(), sqlx::Error> {
    // Create a connection pool
    //  for MySQL/MariaDB, use MySqlPoolOptions::new()
    //  for SQLite, use SqlitePoolOptions::new()
    //  etc.
    let pool = PgPoolOptions::new()
        .max_connections(5)
        .connect("postgres://postgres:password@localhost/test").await?;

    // Make a simple query to return the given parameter (use a question mark `?` instead of `$1` for MySQL/MariaDB)
    let row: (i64,) = sqlx::query_as("SELECT $1")
        .bind(150_i64)
        .fetch_one(&pool).await?;

    assert_eq!(row.0, 150);

    Ok(())
}

连接

可以使用任何数据库连接类型建立一个单一连接，并调用 connect()

use sqlx::Connection;

let conn = SqliteConnection::connect("sqlite::memory:").await?;

let pool = MySqlPool::connect("mysql://user:pass@host/database").await?;

// low-level, Executor trait
conn.execute("BEGIN").await?; // unprepared, simple query
conn.execute(sqlx::query("DELETE FROM table")).await?; // prepared, cached query

sqlx::query("DELETE FROM table").execute(&mut conn).await?;
sqlx::query("DELETE FROM table").execute(&pool).await?;

// provides `try_next`
use futures::TryStreamExt;

let mut rows = sqlx::query("SELECT * FROM users WHERE email = ?")
    .bind(email)
    .fetch(&mut conn);

while let Some(row) = rows.try_next().await? {
    // map the row into a user-defined domain type
    let email: &str = row.try_get("email")?;
}

let mut stream = sqlx::query("SELECT * FROM users")
    .map(|row: PgRow| {
        // map the row into a user-defined domain type
    })
    .fetch(&mut conn);

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

let mut stream = sqlx::query_as::<_, User>("SELECT * FROM users WHERE email = ? OR name = ?")
    .bind(user_email)
    .bind(user_name)
    .fetch(&mut conn);

let countries = sqlx::query!(
        "
SELECT country, COUNT(*) as count
FROM users
GROUP BY country
WHERE organization = ?
        ",
        organization
    )
    .fetch_all(&pool) // -> Vec<{ country: String, count: i64 }>
    .await?;

// countries[0].country
// countries[0].count

// no traits are needed
struct Country { country: String, count: i64 }

let countries = sqlx::query_as!(Country,
        "
SELECT country, COUNT(*) as count
FROM users
GROUP BY country
WHERE organization = ?
        ",
        organization
    )
    .fetch_all(&pool) // -> Vec<Country>
    .await?;

// countries[0].country
// countries[0].count

[profile.dev.package.sqlx-macros]
opt-level = 3