che-orm 0.4.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
# Models and Schema

## Derive Model

`#[derive(Model)]` generates the `Model` implementation and typed field constants.
Every model must have exactly one `#[orm(primary_key)]` field of type `i64`
or `che_orm::Uuid`:

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

After the derive, `User::ID`, `User::EMAIL`, and `User::NAME` are available for
filters, ordering, and assignments. `User::primary_key()` is also used by the
high-level facade for `get`, `update`, and `delete`.

`Debug` in `#[derive(Debug, Model)]` is unrelated to the ORM. It is the standard
Rust derive for printing a model with `{:?}`.

### UUIDv7

```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>()` and `User::insert()` generate UUIDv7 in Rust when
building an INSERT if the key was not supplied through `.set(User::ID, uuid)`.
`database.insert(&model)` preserves `model.id`. Explicit UUIDs are preserved
regardless of version. SQLite stores a 16-byte `BLOB`, PostgreSQL DDL uses
`UUID`, and JSON serializers expose UUID strings.

The derive sets `Model::PrimaryKey` from the field type. Hand-written `Model`
implementations must specify `type PrimaryKey = i64` or `Uuid`; `primary_key`
and `primary_key_value` use this type. Serializer write modes use the model's
key type, for example `WriteMode<Uuid>`.

## Table Attributes

### `table`

Sets the exact table name. Required unless `app` is specified:

```rust
#[orm(table = "users")]
```

### `app`

Generates `<app>_<snake_case model name>` when `table` is omitted:

```rust
#[derive(Debug, che_orm::Model)]
#[orm(app = "blog")]
pub struct Post {
    #[orm(primary_key)]
    pub id: i64,
}
```

`Post` uses `blog_post`; `PostComment` uses `blog_post_comment`. Names are not
pluralized. An explicit `#[orm(app = "blog", table = "legacy_posts")]` uses
exactly `legacy_posts`. The prefix must be a valid SQL identifier.

`app` also accepts a path to a `const &str`, so all models and `AppConfig::name()`
can share one definition:

```rust
pub const APP_NAME: &str = "blog";

#[derive(Debug, che_orm::Model)]
#[orm(app = APP_NAME)]
pub struct Post {
    #[orm(primary_key)]
    pub id: i64,
}
```

For models in a child module, use `#[orm(app = super::APP_NAME)]` (or import the
constant). `crate::apps::blog::APP_NAME` is supported too. Return this same
constant from the app's `AppConfig::name()`. The table name is assembled and
validated at compile time, without runtime allocation. Expressions and function
calls are not accepted. Explicit `table` overrides the prefix, including a
constant prefix.

`app` controls table naming only; register the model in `AppConfig::schema()` as
usual. The derive cannot infer the registry owner or module path. Changing `app`
changes the inferred physical table name: review the migration diff and use an
explicit `table` to preserve an existing name.

### `index`

Creates an index after the table. Single-column and composite indexes are supported:

```rust
#[orm(table = "users", index("name"), index("tenant_id", "email"))]
```

### `unique`

Creates a table-level unique constraint. For one column, use `#[orm(unique)]` on
the field instead. The table-level form is for composite constraints:

```rust
#[orm(table = "memberships", unique("organization_id", "user_id"))]
```

Do not specify both forms for one field: this creates two uniqueness checks.

## Field Attributes

| Attribute | Purpose |
| --- | --- |
| `primary_key` | Primary key; `i64` receives backend identity/rowid behavior, `Uuid` generates UUIDv7 in Rust when the key is omitted. |
| `db_column = "old_name"` | Physical SQL column when the Rust field has another name. |
| `unique` | Uniqueness of one column. |
| `default = "..."` | SQL expression for `DEFAULT`. The value is not parameterized. |
| `check = "..."` | SQL expression inside `CHECK (...)`. |
| `references = "roles(id)"` | Foreign key target. |
| `on_delete = "cascade"` | `ON DELETE` action for a foreign key. |
| `auto_now_add` | Managed timestamp on insertion. Requires `OffsetDateTime`. |
| `auto_now` | Managed timestamp on update. Requires `OffsetDateTime`. |

Example:

```rust
#[derive(Model)]
#[orm(table = "users")]
struct User {
    #[orm(primary_key)]
    id: i64,
    #[orm(unique)]
    email: String,
    #[orm(check = "length(name) > 0")]
    name: String,
    #[orm(default = "true")]
    is_active: bool,
    #[orm(auto_now_add)]
    created_at: time::OffsetDateTime,
    #[orm(auto_now)]
    updated_at: time::OffsetDateTime,
}
```

## Supported Types

| Rust | SQLite SQL | Nullable |
| --- | --- | --- |
| `i64` | `INTEGER` | No |
| `f64` | `REAL` | No |
| `Uuid` | `BLOB` (16 bytes) | No |
| `String` | `TEXT` | No |
| `ImageField` | `TEXT` (relative storage key) | No |
| `JsonField` | `TEXT` (JSON) | No |
| enum deriving `DbEnum` | `TEXT` with a choices `CHECK` | No |
| `Vec<u8>` | `BLOB` | No |
| `bool` | `INTEGER` (`0`/`1`) | No |
| `time::OffsetDateTime` | UTC `TEXT` | No |
| `Option<T>` | `T` type | Yes |

`Option<T>` is automatically considered nullable. The ORM decodes fields through
the common `Row` and `FromDatabaseValue`. SQLite stores `OffsetDateTime` as RFC3339
`TEXT` and decodes it into UTC; see [SQLite runtime](sqlite.md) for date comparisons.
See the [backend guide](backends.md) for PostgreSQL types.

### Rust Names and SQL Columns

An existing SQL column named `caption` can have a Rust field named `title`:

```rust
#[derive(Debug, che_orm::Model)]
#[orm(table = "articles")]
struct Article {
    #[orm(primary_key)]
    id: i64,
    #[orm(db_column = "caption")]
    title: String,
}
```

Queries use `Article::TITLE`, while SQL addresses `caption`. Renaming only the
Rust field while preserving `db_column` creates no schema operation and does not
rewrite data. New columns with matching Rust and SQL names do not need this
attribute. Sync models declare stable wire names separately with
`#[orm(sync_name = "...")]`.

`Option<ImageField>` holds a relative file key or `NULL`, not image bytes or an
HTTP URL. The field is automatically read-only in JSON model writes; uploading
and validating the file belongs to `che-rest::media`. Start with the
[step-by-step ImageField guide](image-field.md) for model and ViewSet examples,
storage layout, URLs, and migrations. Use `#[orm(db_column = "old_name")]` only
when the existing SQL column has a different name; new models normally do not
need it.

## Timestamp Fields

`auto_now_add` and `auto_now` are intended for fields analogous to Django's
`auto_now_add` and `auto_now`.

- Both fields receive a SQLite `DEFAULT` based on `strftime(..., 'now')`.
- Managed fields are omitted from regular ORM `INSERT` statements.
- For `auto_now`, the ORM adds an assignment to every update query.
- Raw SQL through `execute_sql` does not update timestamps automatically.
- On reads, the value is decoded into `OffsetDateTime`.

PostgreSQL uses `TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP` and native timestamp
decoding. `CURRENT_TIMESTAMP` is fixed at the transaction's start; ORM UPDATE
assignments for `auto_now` use the Rust process clock.

## Relations

Models can be organized into application modules. An application implements
`AppConfig` and returns its own `SchemaSet`:

```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>()
    }
}
```

Applications are then combined through `AppRegistry`:

```rust
let registry = che_orm::AppRegistry::new()
    .register::<AccountsApp>()
    .register::<ContentApp>();
```

This separates model ownership while retaining a single schema state for the
application's compiled migrations.

A foreign key between ORM models is declared through `foreign_key`.
Its key type must match the target model's primary key: `i64` / `Uuid` or the
nullable variants `Option<i64>` / `Option<Uuid>`.
Use `on_delete = "set null"` only with nullable keys:

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

`foreign_key = User` generates `Post::USER`, a DDL foreign key to `users(id)`,
and `Post::USER.reverse()` for the reverse relation. The default reverse
relation name is `post_set`. `on_delete = "cascade"` adds cascade deletion. For
relation is generated for that field. When using `Database`, SQLite
`PRAGMA foreign_keys = ON` is enabled on every pool connection.

Load the relation through the typed field of the child model:

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

This is equivalent to the filter `Post::query().filter(Post::USER_ID.eq(user_id))`.
For a collection of owners, do not call `fetch_by` in a loop: that creates N+1
queries. Use a batch query:

```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` performs parameterized `IN` queries, automatically chunking keys
to respect the backend limit and deduplicating results by primary key. An empty
set returns an empty list without a query. The child rows must then be grouped
by `post.user_id` in memory.

Typed eager-loading wrappers are available on querysets:

`database.query::<M>()` returns a `BoundQuery` that borrows that database.
Its terminal methods use the same database, including after relation loading:
replace `.all(&database)`, `.first(&database)` and `.count(&database)` with
`.all()`, `.first()` and `.count()` respectively.

Standalone `DatabaseQuery::new(M::query())` values remain database-independent
and still accept an explicit database when executed. Use these for REST ViewSet
queryset declarations; `database.fetch_all(M::query())` is also unchanged.

```rust
let posts = database
    .query::<Post>()
    .select_related(Post::USER)
    .all()
    .await?;

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

`select_related` returns `WithOne`, while `prefetch_related` returns `Loaded`
with `LoadedMany`. A serializer receives these materialized values and has no
database access.

Multiple `belongs_to` relations can be loaded with a chainable API in one SQL
query. Each relation receives an alias from its FK name (`author_id` -> `author`):

```rust
let posts = database
    .query::<Post>()
    .select_related(Post::AUTHOR)
    .select_related(Post::EDITOR)
    .all()
    .await?;
```

For two FKs to one table, the generated relation markers differ, so `author` and
`editor` cannot be confused at compile time.

After `select_related`, joined model fields are available through the relation

```rust
let posts = database
    .query::<Post>()
    .select_related(Post::USER)
    .filter(Post::USER.related_field(User::NAME).eq("Alice"))
    .order_by(Post::USER.related_field(User::NAME).asc())
    .all()
    .await?;
```

Do not use such a call before `select_related`: the joined table alias exists
only in a materializing query.

A serializer declares JSON fields separately from the ORM model:

```rust
#[derive(che_orm::ModelSerializer)]
#[serializer(model = User)]
struct UserSerializer {
    #[serializer(read_only)]
    id: i64,
    email: String,
    name: String,
    #[serializer(many = Post, relation = PostUserRelation)]
    posts: Vec<PostSerializer>,
}
```

`PostUserRelation` is generated alongside the `Post` model; import it from the
model module. This intentionally binds the serializer at compile time to a
specific foreign key relation.

`UserSerializer` with a nested `many` field accepts the result of
`prefetch_related`: `Loaded<User, (LoadedMany<Post, PostUserRelation>,)>`.
The queryset must call `prefetch_related` first. The serializer does not accept
a `Database`, perform queries, or create N+1 queries.

Multiple reverse relations are loaded in a chain and serialized as a typed tuple:

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

let response = UserWithPostsAndAuditsSerializer::many(users);
```

For multiple nested fields, use `LoadedMany` and relation markers; the order of
`prefetch_related` must match the materialized graph. Use
`UserSerializer::many(...)` for multiple materialized objects:

```rust
let response = UserSerializer::many(users);
```

For a nested serializer, `many` accepts `Loaded` with the matching `LoadedMany`,
so an unloaded relation cannot accidentally be passed to the call. A complete
runnable example is in `che-orm-examples`:

```bash
cargo run -p che-orm-examples --bin serializers
```