che-orm 0.4.0

Typed SQLite and PostgreSQL ORM for che-rest applications
Documentation
# SQLite runtime

## Подключение

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

`Database` использует managed pool `deadpool` с адаптером `deadpool-sync` для
`rusqlite`. По умолчанию pool size равен 4. Блокирующие SQLite-вызовы выполняются
вне async-потоков. Bundled SQLite не ниже 3.54.0 (исправлена RUSTSEC-2026-0459).
Для настройки:

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

Для тестов:

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

In-memory database должна использовать pool size 1, иначе каждое соединение
получит отдельную `:memory:` базу.

## Известное ограничение параллельных чтений

Увеличение пула не гарантирует рост производительности SQLite. В локальном
исследовании сортировки 10 000 строк без индекса восемь соединений давали худший
результат, чем четыре. Это воспроизвелось и в чистом `rusqlite`, без HTTP,
декодирования моделей и serializers.

Исследованная bundled-сборка (`libsqlite3-sys` 0.35.0, SQLite 3.50.2) включает
`SQLITE_ENABLE_MEMORY_MANAGEMENT`. Во встроенном page-cache SQLite этот флаг
объединяет управление кешами в общую группу с общим LRU mutex. Это не означает
включение прикладного SQLite shared-cache mode, но может ограничивать параллельные
чтения внутри одного процесса. У статистики аллокаций есть отдельный общий mutex:
в экспериментальной сборке он стал следующим ограничением после устранения
конкуренции общей группы page-cache.

**Настройки сборки, API инициализации и default-пул для устранения этой проблемы
пока не изменены.** Отключение compile-time флага влияет на глобальное освобождение
кеш-памяти; отключение статистики меняет memory accounting и связанные механизмы
контроля и требует настройки до инициализации SQLite. Thread safety в экспериментах
не отключалась. Нельзя скрытно менять глобальную конфигурацию при выдаче соединения
из пула или считать, что Cargo config библиотеки управляет downstream-сборками.

Пока рекомендуется индексировать частые сортировки и диапазонные фильтры,
проверять `EXPLAIN QUERY PLAN` и выбирать размер пула по реальной нагрузке.
Канонический datetime TEXT позволяет использовать обычные индексы, но не устраняет
полные сканирования и внутреннюю конкуренцию SQLite. Одинаковый JSON также не
гарантирует одинаковые SQL-проекции и запросы подсчёта. Условия, A/B-замеры и
исправление первоначальной гипотезы о парсинге дат описаны в
[исследовании бенчмарка соседнего checkout](../../che-rest/benchmarks/cli_fullstack/SQLITE-PERFORMANCE.md).
Эти выводы относятся к SQLite, не PostgreSQL.

## Сравнение дат

`OffsetDateTime` и `Option<OffsetDateTime>` используют канонический UTC `TEXT`:
`2026-01-01T00:00:00.000000000Z`. Дробная часть всегда содержит девять цифр,
UTC-год находится в диапазоне `0000..=9999`. Typed writes сохраняют наносекунды.
SQL defaults используют миллисекундную точность часов SQLite, дополненную нулями
до той же ширины. Для nullable-полей сохраняется SQL NULL.

Фильтры, joins и сортировка используют обычное бинарное сравнение строк, без
custom collation и разбора дат при каждом сравнении. Обычные индексы, например
`#[orm(index("created_at"))]`, подходят для сортировки и диапазонных фильтров.
`ColumnRef::datetime` и `ModelField::datetime` остаются доступны для typed AST.
PostgreSQL продолжает использовать TIMESTAMPTZ; JSON остаётся RFC 3339 и не
обязан содержать девять знаков дробной части.

### Breaking change: миграция существующих SQLite-баз

Нельзя запускать новую версию со смешанными форматами дат. Остановите запись,
сделайте резервную копию и примените явную follow-up compiled migration
**до запуска приложения**. Открытие базы не переписывает данные. Schema diff
не обнаруживает формат сохранённых строк: одного `makemigrations` недостаточно.

```rust
MigrationOperation::NormalizeSqliteDateTimes {
    table: "tasks_task".into(),
    columns: vec!["created_at".into(), "updated_at".into()],
}
```

Зафиксируйте физические имена таблиц и колонок в исходнике миграции; не собирайте
их из актуальных моделей при старте. Включите все datetime-колонки, в том числе
nullable, `db_column`, sync current/shadow и timestamps журналов. JSON, wire
payloads и непрозрачные сохранённые запросы переписывать не нужно.

Операция разбирает RFC 3339 в Rust без потери наносекунд, нормализует offsets,
сохраняет NULL и перестраивает таблицу по её исторической схеме. Managed defaults
обновляются, известные индексы и foreign keys сохраняются. Невалидные даты,
UTC-год вне диапазона и коллизии unique-ключей атомарно отменяют миграцию;
история не продвигается. Leap seconds и дробная часть длиннее девяти цифр
отклоняются вместо неявного округления; такие значения нужно явно исправить.
Явные SQL defaults сначала нужно проверить и временно
убрать через `AlterColumn`; после нормализации восстановить только канонические
defaults отдельным `AlterColumn`. Для triggers/views действуют
обычные правила rebuild: явно удалить и восстановить, не обходя проверки.
На PostgreSQL операция не изменяет данные или схему.

Raw SQL, импорт и внешние писатели обязаны соблюдать тот же 30-символьный UTC
формат либо передавать `DatabaseValue::DateTime`. Старые строки декодируются,
но сравнивать смешанные форматы в SQL небезопасно. Custom индексы и SQL с
`COLLATE che_datetime` замените обычными: runtime больше не регистрирует эту
collation. SQL миграции с функцией `che_datetime_utc` выполняется только через
migration executor, который регистрирует её на время операции.

Изолированный замер производительности:

```bash
cargo test --release -p che-orm --test datetime_benchmark -- --ignored --nocapture
```

Смещение без лимита компилируется в `LIMIT -1 OFFSET ...` для SQLite.

## Создание схемы

```rust
database.create_table::<User>().await?;
```

Операция выполняет:

1. `CREATE TABLE`;
2. все `CREATE INDEX`, описанные в metadata модели.

Для просмотра SQL без подключения:

```rust
let compiled = che_orm::SqlCompiler::<che_orm::SqliteDialect>
    ::compile(&User::create_table().into_ast());
println!("{}", compiled.sql);
```

## High-level CRUD

Facade API возвращает модели, включая generated primary key и значения managed
timestamp-полей:

```rust
let user = database
    .create::<User>()
    .set(User::EMAIL, "alice@example.test")
    .set(User::NAME, "Alice")
    .set(User::IS_ACTIVE, true)
    .execute()
    .await?;

let loaded = database.get::<User>(user.id).await?;
let users = database
    .query::<User>()
    .filter(User::IS_ACTIVE.eq(true))
    .order_by(User::NAME.asc())
    .limit(20)
    .all()
    .await?;

let updated = database
    .update::<User>(user.id)
    .set(User::NAME, "Alice Cooper")
    .execute()
    .await?;

let deleted = database.delete::<User>(user.id).await?;
```

`get` и `first` возвращают `Option`, если строка отсутствует. `update` также
возвращает `Option`; `delete` возвращает `bool`.

## Сохранение объекта модели

`save` обновляет все обычные поля существующей записи по её primary key:

```rust
let mut user = database.get::<User>(user_id).await?.unwrap();
user.name = "Alice Cooper".into();
let saved = database.save(&user).await?; // Option<User>
```

Метод не вставляет новую строку: при отсутствии записи возвращается `None`.
Primary key и сохранённые `auto_now_add` не перезаписываются, `auto_now`
обновляется ORM. Обычные поля, включая nullable, JSON и доверенные ключи
`ImageField`, берутся из объекта; `db_column` учитывается автоматически.
Результат содержит модель из `RETURNING`, исходный объект не изменяется.
Если обычных полей и managed-обновлений нет, возвращается `EmptyUpdate`.
Для точечного изменения используйте `update().set(...)`: `save` записывает все
обычные поля и может перезаписать изменения, сделанные после загрузки объекта.

В транзакции используйте `tx.save(&user).await?`. Для синхронизируемых моделей
вызывайте метод через настроенный `client.database()` / `server.database()`:
запись и sync-метаданные фиксируются вместе.

`create`, `update` и `save` используют SQLite `RETURNING` и возвращают значения,
полученные непосредственно из ORM-операции. ORM не создаёт `AFTER INSERT` или
`AFTER UPDATE` triggers, поэтому при работе с базой только через ORM
возвращаемая модель соответствует записанным значениям. Если такие triggers
добавлены вручную, через raw SQL или миграцию, они могут изменить строку после
того, как SQLite сформировал результат `RETURNING`; это значение не отражает
последующие trigger-изменения.

## Низкоуровневый insert

```rust
let user = User {
    id: 0,
    email: "alice@example.test".into(),
    name: "Alice".into(),
    is_active: true,
    created_at: time::OffsetDateTime::now_utc(),
    updated_at: time::OffsetDateTime::now_utc(),
};

let result = database.insert(&user).await?;
println!("{}", result.rows_affected);
println!("{:?}", result.last_insert_rowid);
```

Целочисленный `primary_key`, `auto_now_add` и `auto_now` не включаются в
`database.insert(&model)`. UUID-ключ передаётся из модели как 16-байтовый BLOB.
Для UUID-моделей `database.create::<User>()` генерирует UUIDv7, если ключ не
задан через `.set(User::ID, uuid)`.
Поле `auto_now` автоматически добавляется в ORM-generated update.
Остальные поля передаются как SQL parameters.

Для обычного создания используйте `database.create::<User>()`. Низкоуровневый
`insert` сохраняет `ExecuteResult` и нужен для случаев, когда не требуется
перечитывать созданную модель.

## Typed select facade

```rust
use che_orm::Model;

let users = database
    .query::<User>()
    .filter(User::IS_ACTIVE.eq(true))
    .order_by(User::NAME.asc())
    .limit(20)
    .all()
    .await?;

let first = database
    .query::<User>()
    .filter(User::EMAIL.eq("alice@example.test"))
    .first()
    .await?;
```

Значения фильтра параметризуются. Имена таблиц и колонок берутся из derive
metadata и не должны приходить от пользователя.

## Низкоуровневые update и delete

```rust
let update = User::update()
    .set(User::NAME, "Alice Cooper")
    .filter(User::ID.eq(1))
    .into_ast()?;
database.execute(update).await?;

let delete = User::delete()
    .filter(User::ID.eq(1))
    .into_ast()?;
database.execute(delete).await?;
```

Facade `update::<User>(id)` и `delete::<User>(id)` добавляют filter по primary
key автоматически. При прямой работе с AST без `filter` update/delete
возвращают `QueryBuildError::MissingFilter`.
Если массовая операция действительно нужна:

```rust
let query = User::update()
    .set(User::IS_ACTIVE, false)
    .allow_all()
    .into_ast()?;
```

## Связанные строки

Опишите дочернюю модель с foreign key:

```rust
#[derive(Debug, che_orm::Model)]
#[orm(table = "posts")]
struct Post {
    #[orm(primary_key)]
    id: i64,
    #[orm(foreign_key = User, on_delete = "cascade")]
    user_id: i64,
    title: String,
}
```

Создайте таблицы в порядке зависимости и загрузите дочерние строки:

```rust
database.create_table::<User>().await?;
database.create_table::<Post>().await?;

let posts = database.fetch_by(Post::USER_ID, user_id).await?;
```

Для нескольких пользователей используйте batch-загрузку, чтобы не получить
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?;
```

`fetch_by_many` строит параметризованный `IN`-запрос. Пустой набор возвращает
пустой список без обращения к базе. Результаты следует сгруппировать по
`post.user_id` в памяти. ORM автоматически разбивает ключи на порции с учётом
лимита bind-параметров SQLite и объединяет результаты без повторов по primary key.

`Database` включает `PRAGMA foreign_keys = ON` при каждом получении
соединения, поэтому несуществующий `user_id` завершится ошибкой SQLite, а
удаление пользователя каскадно удалит его posts.

`foreign_key = User` также генерирует typed relation `Post::USER`. Для
`belongs_to` используйте `select_related(Post::USER)`, а для `has_many`:

```rust
let users = database
    .query::<User>()
    .prefetch_related(Post::USER.reverse())
    .all()
    .await?;
```

`select_related` возвращает `WithOne<Post, User>`, а `prefetch_related` -
`Loaded<User, (LoadedMany<Post, _>,)>`. Оба результата можно передать в
подходящий serializer. Serializer не получает `Database` и не выполняет
дополнительные запросы.

Nullable foreign key поддерживает `LEFT JOIN`:

```rust
#[orm(foreign_key = User, on_delete = "set null")]
user_id: Option<i64>,
```

Такой `select_related` возвращает `WithOptionalOne<Post, User>`, где `related`
может быть `None`.

## Транзакции

```rust
database
    .transaction(|tx| Box::pin(async move {
        tx.update::<User>(1).set(User::IS_ACTIVE, false).execute().await?;
        Ok(())
    }))
    .await?;
```

Closure получает общий `Transaction`. Каждая ORM-операция асинхронная; SQLite
выполняет её в worker-потоке пула. Ошибка вызывает rollback, успех — commit.
Для прямого `rusqlite::Connection` есть SQLite-only `raw_transaction`.

## Ошибки и ограничения

`OrmError` объединяет ошибки подключения, пула, драйвера, декодирования,
построения запросов и миграций. `constraint_kind()` возвращает общий тип
нарушенного ограничения. Compiled migrations применяются через
`Database::migrate`; выбор PostgreSQL описан в [backend guide](backends.md).