che-orm
Русский | English
Экспериментальная типизированная ORM для Rust с единым async API для SQLite и PostgreSQL. Backend выбирается при компиляции. Требуется Rust 1.89+.
Текущая опубликованная версия che-orm — 0.3.3. Проект находится
в разработке; перед обновлением см. CHANGELOG.
Этот checkout готовит 0.4.0 (ещё не опубликована): bound-query API и формат SQLite datetime изменились несовместимо. До публикации новых ORM/Sync/REST используйте согласованные локальные зависимости. См. план выпуска.
Возможности
- Типизированные модели и запросы.
#[derive(Model)]создаёт метаданные и поля для фильтрации и записи. CRUD строится из Rust-выражений; значения передаются в SQL как параметры. - Один async API для SQLite и PostgreSQL. Модели, CRUD и транзакции используют общий интерфейс; backend выбирается feature-флагом при сборке.
- Миграции как часть приложения. Изменения схемы хранятся в компилируемых
миграциях. Шаблон включает CLI для их генерации и применения, а модели
группируются в модули приложения через
AppConfig/AppRegistry. - Явная загрузка связей и сериализация.
select_relatedиprefetch_relatedзагружают связанные данные до сериализации.ModelSerializerработает с готовыми данными и не обращается к базе. - Типы для прикладных данных. Целочисленные и UUIDv7-ключи, необязательные поля,
перечисления с
CHECK, JSON, временные метки и ключи изображенийImageField.
Офлайн-синхронизация — отдельное расширение. che-sync добавляет
синхронизацию UUID-моделей между клиентом и сервером, не привязывая ORM
к HTTP или Tauri. Подробнее — ниже.
Модель и использование в приложении
Добавьте зависимости в Cargo.toml. SQLite включён по умолчанию:
[]
= "0.4.0"
= { = "1", = ["macros", "rt-multi-thread"] }
Опишите модель
В src/main.rs объявите обычную Rust-структуру. Model создаст метаданные
таблицы и типизированные поля User::EMAIL, User::NAME и User::ID:
use Model;
Используйте модель
В том же файле добавьте подключение и операции с данными. Этот пример
запускается на временной SQLite-базе без дополнительной настройки.
create_table здесь нужен только для демонстрации; для постоянной схемы
приложения используйте миграции.
use Database;
async
database.save(&user) сохраняет все обычные поля объекта по первичному ключу,
а не только изменённые. Метод возвращает Option<User>: обновлённую запись
или None, если строка уже удалена. Исходный объект не изменяется;
для создания новой записи используйте create.
Вместо изменения объекта и save можно обновить только выбранные поля:
let updated = database
.
.set
.execute
.await?;
Транзакции
Операции внутри callback выполняются через tx, на одном соединении.
Успешный результат фиксирует изменения; ошибка откатывает транзакцию.
Например, обновление существующего пользователя:
database
.transaction
.await?;
PostgreSQL
Модели и CRUD-код остаются прежними. Замените зависимость в Cargo.toml:
= { = "0.4.0", = false, = ["postgres"] }
Создайте базу PostgreSQL и задайте URL со своими реквизитами:
В main замените connect_in_memory подключением по URL:
let url = var
.expect;
let database = connect.await?;
При сборке должен быть включён ровно один флаг: sqlite или postgres.
default-features = false отключает SQLite по умолчанию. Приложение само
читает URL; connect открывает пул, но не создаёт базу.
Подробнее о TLS и особенностях backend — в руководстве.
Готовое приложение из шаблона
Вместо ручного подключения можно сгенерировать проект. Шаблон предлагает
SQLite или PostgreSQL, структуру single или modular, стартовую модель
и CLI миграций:
Для PostgreSQL перед миграцией создайте базу и задайте CHE_ORM_DATABASE_URL.
Новый модуль приложения: cargo run --bin manage -- createapp blog.
Подробнее — руководство по шаблону.
Миграции
Изменение Rust-модели само по себе не меняет существующую базу. Схема развивается через компилируемые миграции — Rust-модули с операциями, которые хранятся в проекте и компилируются вместе с приложением.
В шаблоне уже есть CLI manage. Он сравнивает зарегистрированные модели
с состоянием предыдущих миграций, а не с живой базой. После создания
начальной миграции каждый следующий цикл выглядит так:
# Проверьте сгенерированные операции перед применением.
Добавляйте файлы из src/migrations/ в Git. Переименования и заполнение
существующих данных могут требовать ручной правки операций. Применённые
миграции не редактируйте: БД хранит их идентификаторы и контрольные суммы.
На деплое migrate запускается отдельным шагом, до старта приложения.
Для просмотра изменений без записи файлов и проверки в CI:
Генерация не требует подключения к БД; --check завершается с ошибкой,
если модели требуют новой миграции. manage — часть приложения из шаблона,
а не CLI, устанавливаемый зависимостью che-orm.
Свой реестр, API применения и особенности backend описаны
в руководстве по миграциям.
Синхронизация и интеграции
che-sync позволяет работать с UUID-моделями локально без сети, а затем
синхронизировать изменения с сервером. Поддерживает повторную отправку
ожидающих запросов и слияние полей. Работает с SQLite и PostgreSQL.
- Синхронизация моделей — доступ ко всей модели (протокол 2).
- Общие объекты — права на отдельные объекты (протокол 3).
- API совместимости — прежний scoped-протокол со снимками данных.
che-orm отвечает за данные и транзакции, che-sync — за синхронизацию.
HTTP и REST-маппинг принадлежат che-rest, Tauri-команды — che-tauri.
См. Todo-сервер и desktop-клиент
для примера работы двух устройств.
Документация
Примеры и проверка
Из корня репозитория:
Приложение-пример содержит замороженные миграции и не поддерживает
makemigrations. Для своего приложения используйте шаблон выше.
Runtime-тестам PostgreSQL нужен работающий сервер и TEST_POSTGRES_URL;
они запускаются отдельно с --test runtime -- --ignored.
Полные проверки публикации описаны в подготовке релиза.