che-orm 0.4.0

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

Migrations belong to the application and compile with it. The ORM applies
`MigrationOperation` values and records identities and checksums in database
history. Changing a model alone does not update an existing schema.

## Generate Migrations in Your Application

The easiest starting point is the [application template](template.md). It includes
the `manage` CLI source and an empty registry in `src/migrations/`. Adding the
`che-orm` dependency alone does not add a CLI to an existing project.

Register models in `AppConfig::schema()` and application modules in `AppRegistry`,
in dependency order: parents before models with foreign keys. From the generated
application's directory, create the first migration:

```bash
cargo run --bin manage -- makemigrations --name initial
```

The generator compares registered models with the state replayed from previous
migrations, not with the live database. It writes a numbered Rust module in
`src/migrations/` and updates `src/migrations/mod.rs`.
Generation needs no database connection, but requires `rustfmt`.

Review operations before applying them, especially removals, renames and new
required fields on populated tables. Data backfills and explicit renames may
require manual edits. Commit migration files to Git.

```bash
cargo run --bin manage -- migrate
cargo run --bin manage -- migrate status
```

Create new migrations after subsequent model changes:

```bash
cargo run --bin manage -- makemigrations --name update_models
cargo run --bin manage -- migrate
```

Do not edit applied migrations: preserve their identities, contents and checksums.
Application is a separate deployment step, not part of startup.
Generation is always explicit as well.

## Preview Changes and Check in CI

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

`--dry-run` prints the proposed Rust source without writing files. `--check`
returns a nonzero exit code if models need a new migration.
Neither command needs a database connection. Run through `cargo run` to use
current models and registry: a stale binary refuses generation when migration
sources have changed.

For PostgreSQL, create the database first and set `CHE_ORM_DATABASE_URL`.
The template selects its backend during generation; when switching to PostgreSQL,
use `--no-default-features --features postgres` on every Cargo command.
Structured operations compile for the selected backend, but arbitrary SQL and
data conversions need review for the target database.

## Example Application CLI

Run from the repository root:

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

`schema` prints the registered models' schema. `migrate` applies migrations;
`migrate status` shows which identities have been recorded in database history.

`database_url()` in `che-orm-examples/src/lib.rs` reads `CHE_ORM_DATABASE_URL`.
SQLite defaults to `app.db`; PostgreSQL defaults to `postgresql://localhost/che_orm`.
For PostgreSQL, add `--no-default-features --features postgres` before `--bin`.

The example ships separate frozen SQL baselines for both backends and includes
the selected one with `include_str!` in `src/bin/manage.rs`. Its migration
identity is `examples:0001_initial`. The example does not generate migrations;
`makemigrations` and `migrate lint` are unavailable.

## Custom Registry and API

Keep models, `AppRegistry`, settings, and the migration registry outside the core
crate. Construct migrations with `Migration::new`, specifying stable
`MigrationId` values, dependencies, and ordered `MigrationOperation` values.

```rust
let graph = che_orm::MigrationGraph::new(application_migrations())?;
let applied = database.migrate(graph).await?;
```

`application_migrations()` is your application's function returning
`Vec<Migration>`. Use `ProjectState::diff` and `operations_from_changes` to
calculate changes, and `render_migration_rust` to generate a Rust module. Review
operations and SQL before applying them. `RunSql` must use the selected backend's
SQL and include matching `state_operations` when changing the schema.

Preserve the identities, contents, and checksums of applied migrations. Append
new operations in new migrations and plan data backfills explicitly. For
example, a required `DbEnum` column on a populated table needs a valid value
backfilled while retaining its `CHECK` constraint.

Apply migrations as a separate deployment/CI step. Reserve
`Database::create_table` for tests and local experiments. See the
[backend guide](backends.md#migrations) for locking, transaction, and SQL details.