Diesel is a Safe, Extensible ORM and Query Builder for Rust

Diesel is the most productive way to interact with databases in Rust because of its safe and composable abstractions over queries.

🚀 Getting Started ⭐ Contribute to Diesel

Why did we make Diesel?

Preventing Runtime Errors

We don't want to waste time tracking down runtime errors. We achieve this by having Diesel eliminate the possibility of incorrect database interactions at compile time.

Built for Performance

Diesel offers a high level query builder and lets you think about your problems in Rust, not SQL. Our focus on zero-cost abstractions allows Diesel to run your query and load your data even faster than C.

Productive and Extensible

Unlike Active Record and other ORMs, Diesel is designed to be abstracted over. Diesel enables you to write reusable code and think in terms of your problem domain and not SQL.

Still not sold? Have a look at an in-depth comparison with other rust database crates.

See some examples

Simple queries are a complete breeze. Loading all users from a database:

users::table.load(&mut connection)

SELECT * FROM users;

Loading all the posts for a user:

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

SELECT * FROM posts WHERE user_id = 1;

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)?;

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 codegen generates boilerplate for you. It lets you focus on your business logic, not mapping to and from SQL rows.

With Diesel:

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

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"),
        }
    }
}

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);

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

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)

Diesel allows to ergonomically abstract over different database backends while keeping all of it’s compile time guarantees.

#[derive(diesel::MultiConnection)]
enum DatabaseConnection {
    Sqlite(diesel::SqliteConnection),
    Postgres(diesel::PgConnection),
}

let mut connection =
    DatabaseConnection::establish("postgres://localhost/diesel")?;

let all_users = users::table.load::<User>(connection)?;

match connection {
    DatabaseConnection::Sqlite(connection) => {
        perform_sqlite_specific_query(connection)?;
    }
    DatabaseConnection::Postgres(connection) => {
        perform_postgres_specific_query(connection)?;
    }
}

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,
}

sql_query(include_str!("complex_users_by_organization.sql"))
    .bind::<Integer, _>(organization_id)
    .bind::<BigInt, _>(offset)
    .bind::<BigInt, _>(limit)
    .load::<User>(&mut conn)?;

Contribute

The Diesel project is always looking for people to help with various parts of the project. If you would like to help here are different ways to contribute to the project:

Contributing Code, Documentation or Guides. Checkout the planning for Diesel 2.4 for open tasks.
Providing knowledge and help to maintain the MySQL/MariaDB backend. This is currently the only in-tree backend that is not used by any maintainers, so having someone around that actually uses this backend would be very helpful for the Diesel project.
Answering questions in our discussion forum.
Reporting bugs in our issue tracker.
Helping triaging issues in our issue tracker.
Sponsoring the maintainers.