che-orm
Documentation: English | Русский
Экспериментальная типизированная ORM для Rust. Сейчас рабочий runtime-backend —
SQLite через deadpool-sqlite, а строки декодируются обратно в модели,
сгенерированные procedural macro.
Возможности
#[derive(Model)]для генерации метаданных модели и typed fields.- SQL AST и параметризованная генерация
SELECT,INSERT,UPDATE,DELETE. - Генерация
CREATE TABLE, индексов и ограничений. - Async SQLite pool через
deadpool-sqliteи Tokio. - High-level
get,all,create,update,deleteи typedqueryfacade. - Низкоуровневые
insert,fetch_all,fetch_oneи произвольныйQueryAst. - Транзакции с commit/rollback.
- Foreign keys с каскадным удалением и typed
fetch_byдля связанных строк. - Versioned migrations через Atlas и встроенный
manageCLI. - Разделение моделей по application-модулям через
AppConfigиAppRegistry. OffsetDateTimeи managed-поляauto_now_add/auto_now.- Защита от пустых mutation-запросов и случайных массовых update/delete.
Проект находится в разработке. PostgreSQL executor пока не реализован.
Быстрый старт
Добавьте зависимость:
[]
= "0.2"
= { = "1", = ["macros", "rt-multi-thread"] }
= { = "0.3", = ["formatting", "parsing"] }
Опишите модель:
use Model;
use OffsetDateTime;
Используйте модель через async SQLite database:
use Database;
async
Managed timestamp-поля не передаются в INSERT: их значения создаёт SQLite.
updated_at автоматически добавляется ORM в каждый update-запрос.
Enum choices
Для фиксированного набора строк используйте DbEnum. Одно значение variant используется в JSON,
SQLite и schema metadata:
use ;
DbEnum generates Serialize and Deserialize; do not derive the serde traits separately. It
stores values as TEXT and emits a CHECK constraint for the declared choices.
Пул
По умолчанию создаётся пул размером 4:
let database = connect?;
Размер можно задать явно:
let database = connect_with_pool_size?;
Для in-memory SQLite используется пул размера 1:
let database = connect_in_memory?;
Это важно: разные SQLite-соединения с :memory: имеют разные базы данных.
CRUD и транзакции
Основной facade автоматически ограничивает update/delete primary key:
let updated = database
.
.set
.execute
.await?;
let deleted = database..await?;
assert!;
Для сложных условий и массовых операций используйте низкоуровневый AST.
UPDATE и DELETE должны иметь фильтр. Массовую операцию нужно разрешить
явно через .allow_all():
let query = update
.set
.filter
.into_ast?;
database.execute.await?;
Транзакция выполняется в worker-потоке SQLite pool:
database
.transaction
.await?;
Ошибка closure вызывает rollback, успешное выполнение вызывает commit.
Связанные модели
Foreign key задаётся на поле дочерней модели:
Загрузить записи has_many можно через typed helper:
let user = database
.
.set
.set
.execute
.await?;
let user_id = user.id;
let posts = database.fetch_by.await?;
Для нескольких пользователей используйте fetch_by_many, а не вызывайте
fetch_by в цикле: это устраняет N+1 запросов.
let users = database..await?;
let user_ids = users.iter.map;
let posts = database.fetch_by_many.await?;
Дочерние строки затем группируются по post.user_id в памяти. Пустой набор
возвращает пустой список; для очень больших наборов ключей используйте
несколько порций из-за лимита SQLite на bind-параметры.
fetch_by строит обычный параметризованный SELECT. SQLite foreign keys
включаются для каждого соединения пула автоматически. Поэтому
on_delete = "cascade" будет работать и при удалении пользователя.
Post::USER описывает forward relation, а Post::USER.reverse() имеет
reverse name post_set по умолчанию. Связанные модели загружаются через typed
queryset:
let users = database
.
.prefetch_related
.all
.await?;
Результат prefetch_related содержит Loaded<User, (LoadedMany<Post, _>,)> и
можно передать в ModelSerializer; serializer получает только
материализованные данные и не имеет доступа к Database.
Примеры
В workspace есть crate che-orm-examples:
Миграции
CLI миграций находится в che-orm-examples, а не в library crate:
makemigrations собирает schema из Rust-моделей, записывает её во временный
файл, передаёт Atlas через --to file://... и удаляет файл после завершения.
Миграции примера хранятся в che-orm-examples/migrations/ и применяются только отдельной командой
deploy, а не при старте приложения. Подробности: docs/atlas.md.
В некоторых версиях Atlas migrate lint требует atlas login/Pro; это
ограничение Atlas, а не приложения.
Applications
Модели можно группировать по приложениям, как в Django:
;
let registry = new
.
.;
Каждое приложение хранит свои модели и возвращает свой SchemaSet. Общий
registry используется application-owned migration CLI. Регистрируйте
приложения в порядке зависимостей: сначала таблицы-родители, затем модели с
foreign keys.
Backend status
| Backend | SQL compiler | Pool/executor |
|---|---|---|
| SQLite | Да | Да, async deadpool-sqlite |
| PostgreSQL | Да, placeholders и DDL dialect | Нет |
Для проверки PostgreSQL compiler без SQLite runtime:
Features sqlite и postgres взаимоисключающие.
Проверка проекта
Русская документация: docs/models.md,
docs/sqlite.md, docs/atlas.md и
docs/tutorial.md. Английская версия: docs/en/.