Привет, Хабр!

Сегодня мы поговорим о Diesel ORM — инструменте, который превращает работу с базами данных в Rust в настоящее удовольствие. Diesel ORM — это расширяемый и безопасный объектно-реляционный маппер и конструктор запросов для Rust. Он имеет высокоуровневый API для взаимодействия с различными СУБД: PostgreSQL, MySQL и SQLite.

Начнем с установки и настройки!

Установка / настройка

Создаем новый проект на Rust:

cargo new my_diesel_project
cd my_diesel_project

Открываем файлик Cargo.toml проекта и добавляем зависимости для Diesel и необходимых библиотек:

[dependencies]
diesel = { version = "2.0.0", features = ["postgres"] }
dotenv = "0.15"

Файл указывает Cargo установить Diesel ORM с поддержкой PostgreSQL (выбрали постгрес для примера), а также библиотеку dotenv. Также допустим то, что Postqre уже установлен.

Для работы с Diesel также нужен Diesel CLI:

sudo apt-get update
sudo apt-get install postgresql postgresql-contrib

Это установит Diesel CLI с поддержкой PostgreSQL. Далее, инициализируем Diesel в проекте:

brew install postgresql
brew services start postgresql

Команда создаст файл diesel.toml и папку migrations в проекте. Теперь создаем файл .env в корне вашего проекта и добавляем в него строку подключения к БД:

sudo -u postgres createuser myuser -s
sudo -u postgres createdb mydatabase

Теперь создаем файлик src/schema.rs для хранения схемы БД:

touch src/schema.rs

В main.rs подключаем библиотеки Diesel и dotenv:

#[macro_use]
extern crate diesel;
extern crate dotenv;

pub mod schema;
pub mod models;

use diesel::prelude::*;
use dotenv::dotenv;
use std::env;

pub fn establish_connection() -> PgConnection {
    dotenv().ok();

    let database_url = env::var("DATABASE_URL")
        .expect("DATABASE_URL must be set");
    PgConnection::establish(&database_url)
        .expect(&format!("Error connecting to {}", database_url))
}

Так мы загрузили переменные окружения из файла .env, устанавили соединение с базой данных и возвращаем его.

CRUD операции

Создание

Создаем файл src/models.rs и определяем структуру модели данных:

#[derive(Queryable)]
pub struct Post {
    pub id: i32,
    pub title: String,
    pub body: String,
    pub published: bool,
}

#[derive(Insertable)]
#[table_name="posts"]
pub struct NewPost<'a> {
    pub title: &'a str,
    pub body: &'a str,
}

В src/schema.rs добавляем схему таблицы:

table! {
    posts (id) {
        id -> Int4,
        title -> Varchar,
        body -> Text,
        published -> Bool,
    }
}

Для вставки новых данных, в src/lib.rs создадим функцию для вставки новых записей:

use diesel::prelude::*;
use diesel::pg::PgConnection;
use crate::schema::posts;
use crate::models::{Post, NewPost};

pub fn create_post<'a>(conn: &PgConnection, title: &'a str, body: &'a str) -> Post {
    let new_post = NewPost {
        title,
        body,
    };

    diesel::insert_into(posts::table)
        .values(&new_post)
        .get_result(conn)
        .expect("Error saving new post")
}

Чтение

Для чтения данных создадим функцию в src/lib.rs:

pub fn get_posts(conn: &PgConnection) -> Vec<Post> {
    use crate::schema::posts::dsl::*;

    posts
        .load::<Post>(conn)
        .expect("Error loading posts")
}

Например, фильтрация опубликованных постов и сортировка по ID выглядит так::

pub fn get_published_posts(conn: &PgConnection) -> Vec<Post> {
    use crate::schema::posts::dsl::*;

    posts
        .filter(published.eq(true))
        .order(id.desc())
        .load::<Post>(conn)
        .expect("Error loading published posts")
}

Обновление и удаление

Для обновления записи создадим функцию:

pub fn update_post_title(conn: &PgConnection, post_id: i32, new_title: &str) -> Post {
    use crate::schema::posts::dsl::{posts, id, title};

    diesel::update(posts.find(post_id))
        .set(title.eq(new_title))
        .get_result::<Post>(conn)
        .expect("Error updating post title")
}

Для удаления записи есть такая функция:

pub fn delete_post(conn: &PgConnection, post_id: i32) -> usize {
    use crate::schema::posts::dsl::posts;

    diesel::delete(posts.find(post_id))
        .execute(conn)
        .expect("Error deleting post")
}

Миграции

Миграции в Diesel очень удобны и легки в использовании.

Чтобы создать новую миграцию есть команда migration:

diesel migration generate create_posts

Команда создаст новую миграцию с именем create_posts и создаст две SQL файла: up.sql и down.sql в папке migrations.

В файле up.sql определим SQL команды для создания таблицы. Например, для создания таблицы posts:

CREATE TABLE posts (
    id SERIAL PRIMARY KEY,
    title VARCHAR NOT NULL,
    body TEXT NOT NULL,
    published BOOLEAN NOT NULL DEFAULT 'f'
);

В файле down.sql определим SQL команды для отката изменений, например, удаления таблицы posts:

DROP TABLE posts;

Для применения миграций используем команду:

diesel migration run

Команда выполнит все миграции, которые еще не были применены, и обновит структуру базы данных.

Если хочется откатить последнюю миграцию есть такая команда:

diesel migration revert

Эта команда выполнит команды из файла down.sql последней миграции и вернет базу данных в предыдущее состояние.

Когда миграции применены, Diesel автоматом обновляет файл src/schema.rs, который содержит описание схемы базы данных в виде Rust кода. Этот файл генерируется Diesel CLI и не должен изменяться вручную.

Обработка ошибок

В Rust тип Result используется для обработки операций, которые могут завершиться ошибкой. Этот тип либо содержит значение успешной операции Ok, либо описание ошибки Err). В Diesel ORM этот механизм используется довольно часто.

Рассмотрим функцию, которая извлекает пост из базы данных по его ID:

use diesel::prelude::*;
use crate::models::Post;
use crate::schema::posts::dsl::*;

pub fn find_post_by_id(conn: &PgConnection, post_id: i32) -> Result<Post, diesel::result::Error> {
    posts.find(post_id).first(conn)
}

Функция возвращает Result<Post, diesel::result::Error>, т.е она либо успешно возвращает объект Post, либо ошибку типа diesel::result::Error.

При вызове этой функции, можно использовать выражение match для обработки возможных ошибок:

fn main() {
    let connection = establish_connection();

    match find_post_by_id(&connection, 1) {
        Ok(post) => println!("Found post: {}", post.title),
        Err(err) => println!("Error finding post: {:?}", err),
    }
}

Так можно обрабатывать ошибки на месте вызова функции.

Тип Option в Rust используется для обработки случаев, когда значение может быть отсутствующим. В контексте БД, это, например, может быть полезно для операций, которые могут не вернуть ни одной строки:

pub fn find_post_by_title(conn: &PgConnection, post_title: &str) -> Option<Post> {
    posts.filter(title.eq(post_title)).first(conn).ok()
}

Функция возвращает Option<Post>, что означает, что она либо возвращает объект Post, либо None, если пост с указанным заголовком не найден.

Diesel ORM помимо вышеописанных функций автоматом использует параметризованные запросы. Например, напишем функцию, которая выполняет параметризованный запрос для поиска постов по заголовку:

pub fn search_posts_by_title(conn: &PgConnection, search: &str) -> Vec<Post> {
    posts.filter(title.like(format!("%{}%", search)))
        .load::<Post>(conn)
        .expect("Error loading posts")
}

Метод filter автоматически использует параметры вместо прямой вставки значений в SQL-запрос, что предотвращает возможность SQL-инъекций.

Когда работаешь с пользовательским вводом, всегда важно проверять и очищать данные. Например:

pub fn create_post(conn: &PgConnection, new_title: &str, new_body: &str) -> Post {
    let new_post = NewPost {
        title: new_title.trim(),
        body: new_body.trim(),
    };

    diesel::insert_into(posts::table)
        .values(&new_post)
        .get_result(conn)
        .expect("Error saving new post")
}

С методом trim() можно удалять лишние пробелы из пользовательского ввода.

Подробнее с Diesel можно ознакомиться здесь.

А с другими языками программирования инструментами можно ознакомиться в рамках практических онлайн-курсов от моих друзей из OTUS. Подробнее в каталоге.