diesel README

The project's README from github.com/diesel-rs/diesel. As one markdown file: README.md.

diesel logo

A safe, extensible ORM and Query Builder for Rust

Build Status Crates.io

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:

  1. PostgreSQL
  2. MySQL
  3. SQLite
  4. 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.

Notable Sponsors and Supporters

We would like to thank all of the sponsors supporting the work on Diesel. Notable large sponsors are:


NLNet Foundation
Prototype Fund
GitHub Secure Open Source Fund

NGI Zero Core
Federal Ministry of Research, Technology and Space (Germany)
GiGa Infosystems GmbH

Bytebase - Open-source Database DevSecOps

Additionally we would like to thank all persons sponsoring the project on GitHub. Without them developing Diesel wouldn't be possible.

diesel (diesel-rs/diesel)

Searching Database…

14.2K ·GitHub
Diesel
Что это такое?Diesel — это безопасный и расширяемый ORM и конструктор запросов для Rust. Он избавляет от шаблонного кода для работы с базой данных и ошибок времени выполнения без потери производительности: за счёт системы типов Rust запросы 'чувствуются как Rust'.
То есть это библиотека, которую я встраиваю в своё приложение на Rust, а не отдельный инструмент?Верно — это крейт Rust, который вы добавляете как зависимость. В Cargo.toml вы выбираете, какой бэкенд базы данных он будет использовать, а дальше ваш код собирает и выполняет запросы через API Diesel.
Насколько сложно добавить его в существующий проект?Добавьте Diesel как зависимость в Cargo.toml и настройте там бэкенд, затем пройдите подробное руководство по началу работы (Getting Started). Гайды по более конкретным возможностям появятся позже.
Какие базы данных я могу подключить?Четыре: PostgreSQL, MySQL, SQLite и MariaDB — каждая поддерживается как выбираемый бэкенд.
Вся эта проверка на уровне системы типов не замедляет запросы во время выполнения?В README утверждают, что компромисса нет: Diesel — это конструктор запросов с минимальными накладными расходами, а сложные запросы обходятся 'с нулевой стоимостью', так что безопасность на этапе компиляции не стоит производительности.
Можно ли пользоваться бесплатно, в том числе в коммерческих проектах?Да. Diesel распространяется по двойной лицензии Apache 2.0 и MIT, так что вы выбираете ту, которая подходит вашему проекту; обе разрешают коммерческое использование.
А если мне нужен запрос, который конструктор не умеет выразить?Как раз для таких случаев Diesel предлагает удобный API для сырого SQL — там, где рукописный SQL проще или конструктор не может выразить запрос.
Сколько кода придётся писать для сопоставления строк таблицы со структурами?Почти никакого. Кодогенерация Diesel сама создаёт шаблонный код, так что вы занимаетесь бизнес-логикой, а не перекладыванием строк SQL в структуры и обратно вручную.
После вставки как прочитать сгенерированные значения, например идентификаторы?Вызывайте get_result или get_results вместо execute, и Diesel вернёт данные из вставленных вами строк.
Какими способами можно обновить строку?Кодогенерация умеет создавать несколько стилей: изменение структуры, разовое пакетное изменение или выделение изменения в отдельную структуру — что лучше подходит для конкретной части вашего приложения.
What are similar projects?orm, ent, kysely, mybatis-plus, sequelize, efcore, sqlc, sqlalchemy
Which topics is it in?query-builder, orm, code-generation, mysql, sql, sqlite, postgresql, backend, database, performance, rust, apache-2.0
Creator
diesel-rs
Size
167.1 MB
Stars
14.2K
Updated
CommitOct 17Releasev2.3.14Oct 07
Age
11y
Commits · 90 Days