che-orm 0.3.0

Typed SQLite and PostgreSQL ORM for che-rest applications
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
# che-orm

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

Экспериментальная типизированная 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

| Backend | SQL compiler | Pool/executor |
| --- | --- | --- |
| 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).