che-orm
Этот checkout готовит 0.3.2, которая ещё не опубликована. Обновлённый шаблон требует эту версию; локальные проверки подменяют зависимости этим checkout. См. подготовку релиза.
Documentation: English | Русский
Экспериментальная типизированная ORM для Rust. SQLite или PostgreSQL выбирается при компиляции; обе БД используют одинаковые модели и высокоуровневый async API. Требуется Rust 1.88 или новее.
Синхронизация и приложения
che-sync добавляет офлайн-изменения, current/shadow-таблицы, неизменяемые
ожидающие запросы и слияние полей для UUID-моделей. Для новых клиентов используйте
модельные журналы протокола 2: ModelLogClient,
SchemaSet::client_model / server_model, независимые курсоры и доступ ко всей
модели. Scoped-протокол со snapshot/full_load остаётся
отдельным путём совместимости.
che-orm отвечает за данные и транзакции, che-sync — за синхронизацию.
HTTP и REST-маппинг принадлежат che-rest; Tauri-команды — che-tauri.
Готовый Todo-сервер и desktop-клиент
показывает офлайн-работу двух устройств, конфликты и явные compiled migrations.
Возможности
#[derive(Model)]для генерации метаданных модели и typed fields.- SQL AST и параметризованная генерация
SELECT,INSERT,UPDATE,DELETE. - Генерация
CREATE TABLE, индексов и ограничений. - Async-пулы SQLite и PostgreSQL, PostgreSQL TLS и типизированные ошибки.
- High-level
get,all,create,update,deleteи typedqueryfacade. - Низкоуровневые
insert,fetch_all,fetch_oneи произвольныйQueryAst. - Транзакции с commit/rollback.
- Foreign keys с каскадным удалением и typed
fetch_byдля связанных строк. - Версионированные compiled migrations и
manageCLI приложения-примера. - Разделение моделей по application-модулям через
AppConfigиAppRegistry. OffsetDateTimeи managed-поляauto_now_add/auto_now.f64иOption<f64>: SQLiteREAL, PostgreSQLDOUBLE PRECISION, числовые фильтры и параметризованная запись.- Защита от пустых mutation-запросов и случайных массовых update/delete.
Проект находится в разработке. Для обеих БД реализованы CRUD, транзакции, загрузка связей и выполнение compiled migrations.
Быстрый старт
Готовое приложение с выбором SQLite/PostgreSQL, структуры single/modular,
моделью и compiled migrations
можно создать через cargo-generate:
Для PostgreSQL перед миграцией создайте БД и задайте CHE_ORM_DATABASE_URL.
Новые модули создаются командой cargo run --bin manage -- createapp blog.
Локальная генерация и устройство проекта описаны в
руководстве по шаблону.
Добавьте зависимость:
[]
= "0.3.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-запрос.
Выбор backend
Включается ровно один feature. SQLite выбран по умолчанию. Для PostgreSQL:
= { = "0.3.2", = false, = ["postgres"] }
В обоих случаях приложение вызывает
Database::connect(settings.database_url()).await?. Настройка содержит SQLite
путь или PostgreSQL URL. Модели, CRUD, связи, сериализаторы и async-транзакции
используют общий API. Выбора типа БД во время выполнения нет.
Подробнее: backend и PostgreSQL.
Синхронизация также поддерживает оба backend: общие UUID-модели регистрируются
как client_model / server_model, а настроенные database handles фиксируют
обычные ORM-записи. См. протокол 2 для модельных журналов
и scoped API для сохранённого snapshot/full_load-пути.
Первичные ключи UUIDv7
Для UUID-ключа используйте Uuid вместо i64:
use ;
database.create::<User>().set(User::NAME, "Alice").execute().await?
генерирует UUIDv7 в Rust, если ключ не передан. То же делает User::insert()
при преобразовании в AST. Явный ключ задаётся через .set(User::ID, uuid);
database.insert(&model) сохраняет model.id. Явно переданный UUID
сохраняется независимо от его версии.
SQLite хранит UUID как BLOB из 16 байт, PostgreSQL DDL использует UUID,
а JSON-сериализаторы возвращают UUID-строки. get, update, delete,
типизированные транзакции, фильтры и загрузка связей работают с типом ключа
модели. Внешние ключи к UUID-моделям имеют тип Uuid или Option<Uuid>;
on_delete = "set null" используется только с optional-ключами.
#[derive(Model)] задаёт ассоциированный тип Model::PrimaryKey автоматически.
В ручных реализациях нужен type PrimaryKey = i64 или Uuid.
WriteMode по умолчанию использует целочисленный ключ; для явно типизированного
UUID-режима записи используется WriteMode<Uuid>. В вызовах сериализатора
WriteMode::Patch { id: user.id } тип выводится автоматически.
Новые UUID-модели добавляются через миграции приложения. Замена существующего целочисленного ключа на UUID требует явного преобразования данных и внешних ключей: смена Rust-типа сама по себе не преобразует сохранённые значения.
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.
ImageField
Если у записи есть картинка, объявите поле как Option<ImageField>:
use ;
В SQLite поле preview — nullable TEXT: там хранится, например,
board-previews/a1b2.png. Это относительный путь внутри хранилища, а не
PNG и не адрес в браузере. Папку с файлами и HTTP-маршруты настраивает
che-rest::media; сам che-orm только сохраняет и читает ключ.
Поле доступно на чтение в JSON, но не принимается в JSON-запросах к модели.
Загружать файл нужно через объявленное в ViewSet image-действие, а не через
ImageField::new(...): этот конструктор не создаёт и не проверяет файл.
Полный пример модели, загрузки, URL, удаления и миграции существующих данных: пошаговое руководство по ImageField.
Пул
По умолчанию создаётся пул размером 4:
let database = connect.await?;
Размер можно задать явно:
let database = connect_with_pool_size.await?;
Для in-memory SQLite используется пул размера 1:
let database = connect_in_memory.await?;
Это важно: разные SQLite-соединения с :memory: имеют разные базы данных.
CRUD и транзакции
Основной facade автоматически ограничивает update/delete primary key:
let updated = database
.
.set
.execute
.await?;
let deleted = database..await?;
assert!;
Чтобы сохранить все обычные поля уже загруженного объекта:
let mut user = database..await?.unwrap;
user.name = "Alice Cooper".into;
let saved = database.save.await?; // Option<User>
save обновляет существующую строку по primary key и возвращает None, если
строки нет. Метод сохраняет auto_now_add, обновляет auto_now и возвращает
модель из RETURNING; исходный объект не изменяется. Для новой строки используйте
create или insert. В транзакции доступен tx.save(&user).await?.
Для сложных условий и массовых операций используйте низкоуровневый AST.
UPDATE и DELETE должны иметь фильтр. Массовую операцию нужно разрешить
явно через .allow_all():
let query = update
.set
.filter
.into_ast?;
database.execute.await?;
Транзакции используют общий async API для обеих БД:
database
.transaction
.await?;
Ошибка closure вызывает rollback, успешное выполнение вызывает commit.
Связанные модели
Foreign key задаётся на поле дочерней модели:
Загрузить записи has_many можно через typed helper:
let user = database
.
.set
.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 в памяти. Пустой набор
возвращает пустой список без запроса. ORM автоматически разбивает ключи на
порции с учётом лимита bind-параметров выбранного backend.
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:
Пример содержит frozen compiled baseline в che-orm-examples/migrations/.
Его manage не генерирует новые миграции: после изменения моделей обновите
реестр миграций приложения. migrate применяет compiled операции отдельно от
запуска сервера; Database::create_table() используйте только для тестов и
локальных экспериментов. Приложения на che-rest могут генерировать compiled
операции собственным manage makemigrations.
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 | Да | Да, async deadpool-postgres, TLS |
Для проверки PostgreSQL-сборки без SQLite:
Runtime-тесты с настоящим сервером запускаются отдельно с TEST_POSTGRES_URL:
Features sqlite и postgres взаимоисключающие.
Проверка проекта
Русская документация: docs/models.md,
docs/sqlite.md, docs/atlas.md и
docs/tutorial.md. Английская версия: docs/en/.