# che-orm
Экспериментальная типизированная ORM для Rust. SQLite или PostgreSQL выбирается
при компиляции; обе БД используют одинаковые модели и высокоуровневый async API.
Требуется Rust 1.88 или новее.
## Возможности
- `#[derive(Model)]` для генерации метаданных модели и typed fields.
- SQL AST и параметризованная генерация `SELECT`, `INSERT`, `UPDATE`, `DELETE`.
- Генерация `CREATE TABLE`, индексов и ограничений.
- Async-пулы SQLite и PostgreSQL, PostgreSQL TLS и типизированные ошибки.
- High-level `get`, `all`, `create`, `update`, `delete` и typed `query` facade.
- Низкоуровневые `insert`, `fetch_all`, `fetch_one` и произвольный `QueryAst`.
- Транзакции с commit/rollback.
- Foreign keys с каскадным удалением и typed `fetch_by` для связанных строк.
- Версионированные compiled migrations и `manage` CLI приложения-примера.
- Разделение моделей по application-модулям через `AppConfig` и `AppRegistry`.
- `OffsetDateTime` и managed-поля `auto_now_add` / `auto_now`.
- `f64` и `Option<f64>`: SQLite `REAL`, PostgreSQL `DOUBLE PRECISION`, числовые фильтры и параметризованная запись.
- Защита от пустых mutation-запросов и случайных массовых update/delete.
Проект находится в разработке. Для обеих БД реализованы CRUD, транзакции,
загрузка связей и выполнение compiled migrations.
## Быстрый старт
Добавьте зависимость:
```toml
[dependencies]
che-orm = "0.3"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
time = { version = "0.3", features = ["formatting", "parsing"] }
```
Опишите модель:
```rust
use che_orm::Model;
use time::OffsetDateTime;
#[derive(Debug, Model)]
#[orm(table = "users", index("name"))]
struct User {
#[orm(primary_key)]
id: i64,
#[orm(unique)]
email: String,
name: String,
is_active: bool,
#[orm(auto_now_add)]
created_at: OffsetDateTime,
#[orm(auto_now)]
updated_at: OffsetDateTime,
}
```
Используйте модель через async SQLite database:
```rust
use che_orm::Database;
#[tokio::main]
async fn main() -> Result<(), che_orm::OrmError> {
let database = Database::connect("app.db").await?;
database.create_table::<User>().await?;
let user = database
.create::<User>()
.set(User::EMAIL, "alice@example.test")
.set(User::NAME, "Alice")
.set(User::IS_ACTIVE, true)
.execute()
.await?;
let users = database
.query::<User>()
.filter(User::NAME.eq("Alice"))
.all(&database)
.await?;
let loaded = database.get::<User>(user.id).await?;
println!("{users:?}");
println!("{loaded:?}");
Ok(())
}
```
Managed timestamp-поля не передаются в `INSERT`: их значения создаёт SQLite.
`updated_at` автоматически добавляется ORM в каждый update-запрос.
## Выбор backend
Включается ровно один feature. SQLite выбран по умолчанию. Для PostgreSQL:
```toml
che-orm = { version = "0.3", default-features = false, features = ["postgres"] }
```
В обоих случаях приложение вызывает
`Database::connect(settings.database_url()).await?`. Настройка содержит SQLite
путь или PostgreSQL URL. Модели, CRUD, связи, сериализаторы и async-транзакции
используют общий API. Выбора типа БД во время выполнения нет.
Подробнее: [backend и PostgreSQL](docs/backends.md).
## Первичные ключи UUIDv7
Для UUID-ключа используйте `Uuid` вместо `i64`:
```rust
use che_orm::{Model, Uuid};
#[derive(Debug, Model)]
#[orm(table = "uuid_users")]
struct User {
#[orm(primary_key)]
id: Uuid,
name: String,
}
```
`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:
```rust
use che_orm::{DbEnum, Model};
#[derive(Debug, Clone, Copy, DbEnum)]
enum TaskStatus {
Draft,
#[db_enum(rename = "in_progress")]
InProgress,
Done,
}
#[derive(Debug, Model)]
#[orm(table = "tasks")]
struct Task {
#[orm(primary_key)]
id: i64,
status: TaskStatus,
}
```
`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>`:
```rust
use che_orm::{ImageField, Model};
#[derive(Debug, Model)]
#[orm(table = "boards")]
struct Board {
#[orm(primary_key)]
id: i64,
preview: Option<ImageField>,
}
```
В SQLite поле `preview` — nullable `TEXT`: там хранится, например,
`board-previews/a1b2.png`. Это **относительный путь внутри хранилища**, а не
PNG и не адрес в браузере. Папку с файлами и HTTP-маршруты настраивает
`che-rest::media`; сам `che-orm` только сохраняет и читает ключ.
Поле доступно на чтение в JSON, но не принимается в JSON-запросах к модели.
Загружать файл нужно через объявленное в ViewSet image-действие, а не через
`ImageField::new(...)`: этот конструктор **не создаёт и не проверяет файл**.
Полный пример модели, загрузки, URL, удаления и миграции существующих данных:
**[пошаговое руководство по ImageField](docs/image-field.md)**.
## Пул
По умолчанию создаётся пул размером 4:
```rust
let database = Database::connect("app.db").await?;
```
Размер можно задать явно:
```rust
let database = Database::connect_with_pool_size("app.db", 8).await?;
```
Для in-memory SQLite используется пул размера 1:
```rust
let database = Database::connect_in_memory().await?;
```
Это важно: разные SQLite-соединения с `:memory:` имеют разные базы данных.
## CRUD и транзакции
Основной facade автоматически ограничивает update/delete primary key:
```rust
let updated = database
.update::<User>(user.id)
.set(User::NAME, "Alice Cooper")
.execute()
.await?;
let deleted = database.delete::<User>(user.id).await?;
assert!(deleted);
```
Для сложных условий и массовых операций используйте низкоуровневый AST.
`UPDATE` и `DELETE` должны иметь фильтр. Массовую операцию нужно разрешить
явно через `.allow_all()`:
```rust
let query = User::update()
.set(User::NAME, "New name")
.filter(User::ID.eq(1))
.into_ast()?;
database.execute(query).await?;
```
Транзакции используют общий async API для обеих БД:
```rust
database
.transaction(|tx| Box::pin(async move {
tx.delete::<User>(user.id).await?;
Ok(())
}))
.await?;
```
Ошибка closure вызывает rollback, успешное выполнение вызывает commit.
## Связанные модели
Foreign key задаётся на поле дочерней модели:
```rust
#[derive(Debug, Model)]
#[orm(table = "posts")]
struct Post {
#[orm(primary_key)]
id: i64,
#[orm(foreign_key = User, on_delete = "cascade")]
user_id: i64,
title: String,
}
```
Загрузить записи `has_many` можно через typed helper:
```rust
let user = database
.create::<User>()
.set(User::EMAIL, "alice@example.test")
.set(User::NAME, "Alice")
.execute()
.await?;
let user_id = user.id;
let posts = database.fetch_by(Post::USER_ID, user_id).await?;
```
Для нескольких пользователей используйте `fetch_by_many`, а не вызывайте
`fetch_by` в цикле: это устраняет N+1 запросов.
```rust
let users = database.all::<User>().await?;
let user_ids = users.iter().map(|user| user.id);
let posts = database.fetch_by_many(Post::USER_ID, user_ids).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:
```rust
let users = database
.query::<User>()
.prefetch_related(Post::USER.reverse())
.all(&database)
.await?;
```
Результат `prefetch_related` содержит `Loaded<User, (LoadedMany<Post, _>,)>` и
можно передать в `ModelSerializer`; serializer получает только
материализованные данные и не имеет доступа к `Database`.
## Примеры
В workspace есть crate `che-orm-examples`:
```bash
cargo run -p che-orm-examples --bin schema
cargo run -p che-orm-examples --bin manage -- migrate
cargo run -p che-orm-examples --bin sqlite_crud
cargo run -p che-orm-examples --bin transactions
cargo run -p che-orm-examples --bin serializers
```
## Миграции
CLI миграций находится в `che-orm-examples`, а не в library crate:
```bash
cargo run -p che-orm-examples --bin manage -- schema
cargo run -p che-orm-examples --bin manage -- migrate
cargo run -p che-orm-examples --bin manage -- migrate status
```
Пример содержит frozen compiled baseline в `che-orm-examples/migrations/`.
Его `manage` не генерирует новые миграции: после изменения моделей обновите
реестр миграций приложения. `migrate` применяет compiled операции отдельно от
запуска сервера; `Database::create_table()` используйте только для тестов и
локальных экспериментов. Приложения на `che-rest` могут генерировать compiled
операции собственным `manage makemigrations`.
## Applications
Модели можно группировать по приложениям, как в Django:
```rust
pub struct AccountsApp;
impl che_orm::AppConfig for AccountsApp {
fn name() -> &'static str { "accounts" }
fn schema() -> che_orm::SchemaSet {
che_orm::SchemaSet::new().model::<User>()
}
}
let registry = che_orm::AppRegistry::new()
.register::<AccountsApp>()
.register::<ContentApp>();
```
Каждое приложение хранит свои модели и возвращает свой `SchemaSet`. Общий
registry используется application-owned migration CLI. Регистрируйте
приложения в порядке зависимостей: сначала таблицы-родители, затем модели с
foreign keys.
## Backend status
| SQLite | Да | Да, async `deadpool-sqlite` |
| PostgreSQL | Да | Да, async `deadpool-postgres`, TLS |
Для проверки PostgreSQL-сборки без SQLite:
```bash
cargo test -p che-orm --no-default-features --features postgres
```
Runtime-тесты с настоящим сервером запускаются отдельно с `TEST_POSTGRES_URL`:
```bash
cargo test -p che-orm --no-default-features --features postgres --test runtime -- --ignored
```
Features `sqlite` и `postgres` взаимоисключающие.
## Проверка проекта
```bash
cargo fmt --check
cargo test --workspace
cargo doc --workspace --no-deps
```
Русская документация: [`docs/models.md`](docs/models.md),
[`docs/sqlite.md`](docs/sqlite.md), [`docs/atlas.md`](docs/atlas.md) и
[`docs/tutorial.md`](docs/tutorial.md). Английская версия: [`docs/en/`](docs/en/README.md).