A safe, extensible ORM and Query Builder for Rust
API Documentation: latest release – main branch
Homepage
Diesel gets rid of the boilerplate for database interaction and eliminates
runtime errors without sacrificing performance. It takes full advantage of
Rust's type system to create a low overhead query builder that "feels like
Rust."
Supported databases:
- PostgreSQL
- MySQL
- SQLite
- MariaDB
You can configure the database backend in Cargo.toml:
[dependencies]
diesel = { version = "<version>", features = ["<postgres|mysql|sqlite>"] }
Getting Started
Find our extensive Getting Started tutorial at
https://diesel.rs/guides/getting-started.
Guides on more specific features are coming soon.
Getting help
If you run into problems, you can come ask for help at in our GitHub Discussions forum.
This is also the right place to propose new features or show your applications.
Usage
Simple queries
Simple queries are a complete breeze. Loading all users from a database:
users::table.load(&mut connection)
Executed SQL:
SELECT * FROM users;
Loading all the posts for a user:
Post::belonging_to(user).load(&mut connection)
Executed SQL:
SELECT * FROM posts WHERE user_id = 1;
Complex queries
Diesel's powerful query builder helps you construct queries as simple or complex as
you need, at zero cost.
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)?;
Executed SQL:
SELECT version_downloads.* FROM 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
Less boilerplate
Diesel codegen generates boilerplate for you. It lets you focus on your business logic, not mapping to and from SQL rows.
That means you can write this:
#[derive(Queryable, Selectable)]
#[diesel(table_name = downloads)]
pub struct Download {
id: i32,
version_id: i32,
downloads: i32,
counted: i32,
date: SystemTime,
}
Instead of this without 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"),
}
}
}
Inserting data
It's not just about reading data. Diesel makes it easy to use structs for new records.
#[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);
Executed SQL:
INSERT INTO users (name, hair_color) VALUES
('Sean', 'Black'),
('Gordon', DEFAULT)
If you need data from the rows you inserted, just change execute to get_result or get_results. Diesel will take care of the rest.
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);
Executed SQL:
INSERT INTO users (name, hair_color) VALUES
('Sean', 'Black'),
('Gordon', DEFAULT)
RETURNING *
Updating data
Diesel's codegen can generate several ways to update a row, letting you encapsulate your logic in the way that makes sense for your app.
Modifying a struct:
post.published = true;
post.save_changes(&mut connection);
One-off batch changes:
update(users.filter(email.like("%@spammer.com")))
.set(banned.eq(true))
.execute(&mut connection)
Using a struct for encapsulation:
update(Settings::belonging_to(current_user))
.set(&settings_form)
.execute(&mut connection)
Raw SQL
There will always be certain queries that are just easier to write as raw SQL, or can't be expressed with the query builder. Even in these cases, Diesel provides an easy to use API for writing raw 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)?;
Code of conduct
Anyone who interacts with Diesel in any space, including but not limited to
this GitHub repository, must follow our code of conduct.
License
Licensed under either of these:
Contributing
Before contributing, please read the contributors guide
for useful information about setting up Diesel locally, coding style and common abbreviations.
Unless you explicitly state otherwise, any contribution you intentionally submit
for inclusion in the work, as defined in the Apache-2.0 license, shall be
dual-licensed as above, without any additional terms or conditions.
We would like to thank all of the sponsors supporting the work on Diesel. Notable large sponsors are:
Additionally we would like to thank all persons sponsoring the project on GitHub. Without them developing Diesel wouldn't be possible.
Diesel 是一个安全、可扩展的 Rust ORM 和查询构建器。它消除了数据库相关的样板代码和运行时错误，又不牺牲性能，借助 Rust 的类型系统，让查询“用起来就像 Rust 本身一样”。