che-orm 0.2.1

Typed SQLite ORM primitives for che-rest applications
Documentation
# che-orm

Documentation: [English]README.en.md | **Русский**

Экспериментальная типизированная 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` и typed `query` facade.
- Низкоуровневые `insert`, `fetch_all`, `fetch_one` и произвольный `QueryAst`.
- Транзакции с commit/rollback.
- Foreign keys с каскадным удалением и typed `fetch_by` для связанных строк.
- Versioned migrations через Atlas и встроенный `manage` CLI.
- Разделение моделей по application-модулям через `AppConfig` и `AppRegistry`.
- `OffsetDateTime` и managed-поля `auto_now_add` / `auto_now`.
- Защита от пустых mutation-запросов и случайных массовых update/delete.

Проект находится в разработке. PostgreSQL executor пока не реализован.

## Быстрый старт

Добавьте зависимость:

```toml
[dependencies]
che-orm = "0.2"
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")?;
    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-запрос.

## 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.

## Пул

По умолчанию создаётся пул размером 4:

```rust
let database = Database::connect("app.db")?;
```

Размер можно задать явно:

```rust
let database = Database::connect_with_pool_size("app.db", 8)?;
```

Для in-memory SQLite используется пул размера 1:

```rust
let database = Database::connect_in_memory()?;
```

Это важно: разные 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?;
```

Транзакция выполняется в worker-потоке SQLite pool:

```rust
database
    .transaction(|connection| {
        connection.execute("DELETE FROM users WHERE id = ?1", [1])?;
        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 -- makemigrations
cargo run -p che-orm-examples --bin manage -- migrate
cargo run -p che-orm-examples --bin manage -- migrate status
cargo run -p che-orm-examples --bin manage -- migrate lint
```

`makemigrations` собирает schema из Rust-моделей, записывает её во временный
файл, передаёт Atlas через `--to file://...` и удаляет файл после завершения.
Миграции примера хранятся в `che-orm-examples/migrations/` и применяются только отдельной командой
deploy, а не при старте приложения. Подробности: [`docs/atlas.md`](docs/atlas.md).
В некоторых версиях Atlas `migrate lint` требует `atlas login`/Pro; это
ограничение Atlas, а не приложения.

## 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

| Backend | SQL compiler | Pool/executor |
| --- | --- | --- |
| SQLite | Да | Да, async `deadpool-sqlite` |
| PostgreSQL | Да, placeholders и DDL dialect | Нет |

Для проверки PostgreSQL compiler без SQLite runtime:

```bash
cargo test -p che-orm --no-default-features --features postgres
```

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).