che-orm 0.4.0

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

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

An experimental typed ORM for Rust with a shared async API for SQLite and
PostgreSQL. The backend is selected at compile time. Requires **Rust 1.89+**.

The current published `che-orm` version is **0.3.3**. The project is under
development; check the [changelog](CHANGELOG.md) before upgrading.

This checkout prepares **0.4.0** (not yet published), with breaking bound-query
and SQLite datetime-storage changes. Use matching local dependencies until the
new core/sync/REST versions are published; see [release preparation](docs/releasing.md).

## Features

- **Typed models and queries.** `#[derive(Model)]` generates metadata and
  fields for filtering and writes. Build CRUD queries with Rust expressions;
  values are passed to SQL as parameters.
- **One async API for SQLite and PostgreSQL.** Models, CRUD and transactions
  share an interface; select the backend with a feature flag at build time.
- **Application-owned migrations.** Schema changes live in compiled migrations.
  The template includes a CLI to generate and apply them; organize models
  into application modules with `AppConfig` / `AppRegistry`.
- **Explicit relation loading and serialization.** `select_related` and
  `prefetch_related` load related data before serialization.
  `ModelSerializer` works with materialized data and never queries the database.
- **Types for application data.** Integer and UUIDv7 keys, nullable fields,
  enum choices with `CHECK` constraints, JSON, timestamps and `ImageField` keys.

**Offline synchronization is a separate extension.** `che-sync` synchronizes
UUID models between client and server without coupling the ORM to HTTP or
Tauri. See [synchronization and integrations](#synchronization-and-integrations).

## A model and its use in an application

Add the dependencies to `Cargo.toml`. SQLite is enabled by default:

```toml
[dependencies]
che-orm = "0.4.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

### Define a model

Declare an ordinary Rust struct in `src/main.rs`. `Model` generates table
metadata and typed fields: `User::EMAIL`, `User::NAME` and `User::ID`.

```rust
use che_orm::Model;

#[derive(Debug, Model)]
#[orm(table = "users")]
struct User {
    #[orm(primary_key)]
    id: i64,
    #[orm(unique)]
    email: String,
    name: String,
}
```

### Use the model

In the same file, add the connection and data operations. This example runs
against a temporary SQLite database without additional setup.
`create_table` is only for the demonstration here; use
[compiled migrations](docs/en/migrations.md) for persistent application schemas.

```rust
use che_orm::Database;

#[tokio::main]
async fn main() -> Result<(), che_orm::OrmError> {
    let database = Database::connect_in_memory().await?;
    database.create_table::<User>().await?;

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

    let users = database
        .query::<User>()
        .filter(User::NAME.eq("Alice"))
        .all()
        .await?;
    println!("{users:?}");

    user.name = "Alice Smith".into();
    database.save(&user).await?;

    database.delete::<User>(user.id).await?;
    Ok(())
}
```

`database.save(&user)` saves all ordinary fields by primary key, not just
changed fields. It returns `Option<User>`: the updated record, or `None` if
the row has been deleted. The supplied object is not modified;
use `create` to insert a new record.

Instead of changing the object and calling `save`, update only selected fields:

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

### Transactions

Operations inside the callback use `tx` and share one connection.
Success commits the changes; an error rolls back the transaction.
For example, to update an existing user:

```rust
database
    .transaction(|tx| Box::pin(async move {
        tx.update::<User>(user.id)
            .set(User::NAME, "Alice Cooper")
            .execute()
            .await?;
        Ok(())
    }))
    .await?;
```

### PostgreSQL

Models and CRUD code stay the same. Replace the dependency in `Cargo.toml`:

```toml
che-orm = { version = "0.4.0", default-features = false, features = ["postgres"] }
```

Create a PostgreSQL database and set the URL with your credentials:

```bash
export CHE_ORM_DATABASE_URL='postgresql://user:password@localhost:5432/my_app'
```

In `main`, replace `connect_in_memory` with a connection by URL:

```rust
let url = std::env::var("CHE_ORM_DATABASE_URL")
    .expect("CHE_ORM_DATABASE_URL must be set");
let database = Database::connect(&url).await?;
```

Enable exactly one feature at build time: `sqlite` or `postgres`.
`default-features = false` disables the default SQLite backend. The application
reads the URL; `connect` opens a pool but does not create the database.
See the [backend guide](docs/en/backends.md) for TLS and backend-specific details.

## Generate an application from a template

Instead of adding the dependency manually, generate a project. The template
offers SQLite or PostgreSQL, a `single` or `modular` layout, a starter model
and a migration CLI:

```bash
cargo install cargo-generate --locked
cargo generate --git https://github.com/che4web/che-orm templates/che-orm --name my-app
cd my-app
cargo run --bin manage -- makemigrations --name initial
cargo run --bin manage -- migrate
cargo run
```

For PostgreSQL, create the database and set `CHE_ORM_DATABASE_URL` before migrating.
Create an application module with `cargo run --bin manage -- createapp blog`.
See the [template guide](docs/en/template.md).

## Migrations

Changing a Rust model does not change an existing database.
Schemas evolve through **compiled migrations**: Rust modules containing
operations, stored in your project and compiled with the application.

The template includes a `manage` CLI. It compares registered models with the
state of previous migrations, **not with the live database**. After creating
the initial migration, each subsequent cycle looks like this:

```bash
cargo run --bin manage -- makemigrations --name update_models
# Review the generated operations before applying them.
cargo run --bin manage -- migrate
cargo run --bin manage -- migrate status
```

Commit the files in `src/migrations/` to Git. Renames and backfilling existing
data may require manual edits to the operations. Do not edit applied migrations:
the database stores their identities and checksums. On deployment, run `migrate`
as a separate step before application startup.

To preview changes without writing files and to check them in CI:

```bash
cargo run --bin manage -- makemigrations --dry-run
cargo run --bin manage -- makemigrations --check
```

Generation needs no database connection; `--check` fails if models need a new
migration. `manage` is part of the template-generated application, not a CLI
installed by the `che-orm` dependency.
See the [migration guide](docs/en/migrations.md) for custom registries,
the migration API and backend-specific details.

## Synchronization and integrations

`che-sync` lets applications work with UUID models locally while offline,
then synchronize changes with the server. It supports retrying pending requests
and field-level merging. Both SQLite and PostgreSQL are supported.

- [Model synchronization]docs/model-sync.md: whole-model authorization
  (protocol 2).
- [Shared objects]https://github.com/che4web/che-rest/blob/main/docs/object-sync.md:
  per-object permissions (protocol 3).
- [Compatibility API]docs/sync.md: the legacy scoped protocol with snapshots.

`che-orm` owns data and transactions; `che-sync` owns synchronization.
HTTP and REST mapping belong to `che-rest`; Tauri commands belong to `che-tauri`.
See the [Todo server and desktop client](https://github.com/che4web/che-tauri/tree/main/examples/todo-sync)
for a two-device example.

## Documentation

- [Benchmark results and methodology]benchmarks/README.md

- [Step-by-step tutorial]docs/en/tutorial.md
- [Models, fields, relations and serializers]docs/en/models.md
- [Connections, CRUD and transactions]docs/en/sqlite.md
- [Application migrations]docs/en/migrations.md
- [ImageField: models, uploads and file storage]docs/en/image-field.md
- [Compile-tested API examples]docs/en/api-examples.md
- [English guide index]docs/en/README.md
- [Changelog]CHANGELOG.md, [contributing]CONTRIBUTING.md,
  [security policy]SECURITY.md

## Examples and verification

From the repository root:

```bash
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
```

The example application has frozen migrations and does not support
`makemigrations`. Use the template above for your own application.

```bash
cargo fmt --check
cargo test --workspace
cargo test -p che-orm --no-default-features --features postgres
cargo doc --workspace --no-deps
```

PostgreSQL runtime tests require a running server and `TEST_POSTGRES_URL`;
run them separately with `--test runtime -- --ignored`.
See [releasing](docs/releasing.md) for the full publication checks.