Привет, Хабр!
Сегодня мы поговорим о 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. Подробнее в каталоге.