17 个版本 (稳定)

2.2.0 2024 年 5 月 31 日
2.1.0 2023 年 5 月 26 日
2.0.0 2022 年 8 月 29 日
2.0.0-rc.12022 年 7 月 22 日
0.99.0 2017 年 11 月 28 日

#2959数据库接口

Download history 69117/week @ 2024-04-21 62291/week @ 2024-04-28 59488/week @ 2024-05-05 72028/week @ 2024-05-12 66448/week @ 2024-05-19 58616/week @ 2024-05-26 66172/week @ 2024-06-02 64841/week @ 2024-06-09 62487/week @ 2024-06-16 58816/week @ 2024-06-23 52817/week @ 2024-06-30 57518/week @ 2024-07-07 62454/week @ 2024-07-14 64948/week @ 2024-07-21 61545/week @ 2024-07-28 65150/week @ 2024-08-04

257,188 每月下载量
用于 177 个 Crates(通过 diesel_migrations

MIT/Apache

22KB
349 代码行

diesel logo

一个安全、可扩展的 Rust ORM 和查询构建器

Build Status Gitter Crates.io

API 文档: 最新版本master 分支

主页

Diesel 消除了数据库交互的样板代码,消除了运行时错误,同时不牺牲性能。它充分利用 Rust 的类型系统,创建了一个低开销的查询构建器,感觉就像 Rust。

支持的数据库

  1. PostgreSQL
  2. MySQL
  3. SQLite

您可以在 Cargo.toml 中配置数据库后端

[dependencies]
diesel = { version = "<version>", features = ["<postgres|mysql|sqlite>"] }

入门指南

在我们的详细入门指南中查找 https://diesel.rs/guides/getting-started。有关更多特定功能的指南即将推出。

寻求帮助

如果您遇到问题,Diesel 有一个非常活跃的 Gitter 房间。您可以在 gitter.im/diesel-rs/diesel 上寻求帮助。有关更长时间的问题和关于 Diesel 将来的讨论,请在 GitHub 讨论中 提开讨论。

用法

简单查询

简单查询非常简单。从数据库中加载所有用户

users::table.load(&mut connection)

执行的 SQL

SELECT * FROM users;

加载某个用户的所有帖子

Post::belonging_to(user).load(&mut connection)

执行的 SQL

SELECT * FROM posts WHERE user_id = 1;

复杂查询

Diesel 强大的查询构建器可以帮助您构建所需的简单或复杂查询,零成本。

let versions = Version::belonging_to(krate)
  .select(id)
  .order(num.desc())
  .limit(5);
let downloads = version_downloads
  .filter(date.gt(now - 90.days()))
  .filter(version_id.eq_any(versions))
  .order(date)
  .load::<Download>(&mut conn)?;

执行的 SQL

SELECT version_downloads.*
  WHERE date > (NOW() - '90 days')
    AND version_id = ANY(
      SELECT id FROM versions
        WHERE crate_id = 1
        ORDER BY num DESC
        LIMIT 5
    )
  ORDER BY date

减少样板代码

Diesel 代码生成为您生成样板代码。它让您专注于业务逻辑,而不是映射 SQL 行。

这意味着您可以写出这个

#[derive(Queryable, Selectable)]
#[diesel(table_name = downloads)]
pub struct Download {
    id: i32,
    version_id: i32,
    downloads: i32,
    counted: i32,
    date: SystemTime,
}

而不是这个(没有 Diesel)

pub struct Download {
    id: i32,
    version_id: i32,
    downloads: i32,
    counted: i32,
    date: SystemTime,
}

impl Download {
    fn from_row(row: &Row) -> Download {
        Download {
            id: row.get("id"),
            version_id: row.get("version_id"),
            downloads: row.get("downloads"),
            counted: row.get("counted"),
            date: row.get("date"),
        }
    }
}

插入数据

不仅仅是读取数据。Diesel 使使用结构体来创建新记录变得容易。

#[derive(Insertable)]
#[diesel(table_name = users)]
struct NewUser<'a> {
    name: &'a str,
    hair_color: Option<&'a str>,
}

let new_users = vec![
    NewUser { name: "Sean", hair_color: Some("Black") },
    NewUser { name: "Gordon", hair_color: None },
];

insert_into(users)
    .values(&new_users)
    .execute(&mut connection);

执行的 SQL

INSERT INTO users (name, hair_color) VALUES
  ('Sean', 'Black'),
  ('Gordon', DEFAULT)

如果您需要从您插入的行中获取数据,只需将 execute 更改为 get_resultget_results。Diesel 将处理其余部分。

let new_users = vec![
    NewUser { name: "Sean", hair_color: Some("Black") },
    NewUser { name: "Gordon", hair_color: None },
];

let inserted_users = insert_into(users)
    .values(&new_users)
    .get_results::<User>(&mut connection);

执行的 SQL

INSERT INTO users (name, hair_color) VALUES
  ('Sean', 'Black'),
  ('Gordon', DEFAULT)
  RETURNING *

更新数据

Diesel 的代码生成器可以生成多种更新行的方式,让您以对您的应用程序有意义的任何方式封装您的逻辑。

修改一个结构体

post.published = true;
post.save_changes(&mut connection);

一次性批量更改

update(users.filter(email.like("%@spammer.com")))
    .set(banned.eq(true))
    .execute(&mut connection)

使用结构体进行封装

update(Settings::belonging_to(current_user))
    .set(&settings_form)
    .execute(&mut connection)

原始 SQL

总会有一些查询更简单以原始 SQL 编写,或者无法用查询构建器表达。即使在这些情况下,Diesel 也提供了一个易于使用的 API 来编写原始 SQL。

#[derive(QueryableByName)]
#[diesel(table_name = users)]
struct User {
    id: i32,
    name: String,
    organization_id: i32,
}

// Using `include_str!` allows us to keep the SQL in a
// separate file, where our editor can give us SQL specific
// syntax highlighting.
sql_query(include_str!("complex_users_by_organization.sql"))
    .bind::<Integer, _>(organization_id)
    .bind::<BigInt, _>(offset)
    .bind::<BigInt, _>(limit)
    .load::<User>(&mut conn)?;

行为准则

任何与 Diesel 互动的人,包括但不限于这个 GitHub 仓库,都必须遵循我们的 行为准则

许可

根据以下任一许可

贡献

在贡献之前,请阅读 贡献指南,其中包含有关在本地设置 Diesel、编码风格和常见缩写的有用信息。

除非您明确表示,否则您提交的任何贡献,按照 Apache-2.0 许可证定义的工作,将按照上述方式双重许可,不添加任何其他条款或条件。

依赖项

~0.5–1.1MB
~26K SLoC