# Repository

> Async CRUD operations for a model type via the Repository trait and ModelRepository.

Source: https://rws8.tech/docs/database/repository/ · Last updated 2026-11-04

`ModelRepository` implements the `Repository<T, ID>` trait and provides the standard set of async create, read, update, and delete operations for a model type. Obtain one from any `#[derive(Model)]` struct using `User::repository(&pool)`.

## Obtaining a repository

```rust
use rust_web_server::model::DbPool;

let pool = DbPool::from_env().await?;

// User::repository is generated by #[derive(Model)]
let repo = User::repository(&pool);
```

The repository borrows the pool by reference for its lifetime — the pool itself is shared and async-safe.

## `Repository<T, ID>` trait

```rust
pub trait Repository<T: Model, ID> {
    async fn find_by_id(&self, id: ID) -> Result<Option<T>, DbError>;
    async fn find_all(&self) -> Result<Vec<T>, DbError>;
    async fn save(&self, entity: &T) -> Result<T, DbError>;
    async fn save_all(&self, entities: &[T]) -> Result<Vec<T>, DbError>;
    async fn delete_by_id(&self, id: ID) -> Result<(), DbError>;
    async fn delete_all_by_id(&self, ids: &[ID]) -> Result<(), DbError>;
    async fn count(&self) -> Result<i64, DbError>;
    async fn exists_by_id(&self, id: ID) -> Result<bool, DbError>;
}
```

`ModelRepository` implements it for `ID` = `i64`, `i32`, `String` and `Uuid` (the `PrimaryKey` types). `T::repository(&pool)` picks `i64` for an integer key and the key's own type otherwise — see [Keys, timestamps, soft delete and locking](/database/conventions/#primary-keys).

Besides the trait, `ModelRepository` has `insert(&entity)` (always an `INSERT`), `query()` (a `QueryBuilder` on the same pool), and for soft-delete models `restore(id)`, `force_delete_by_id(id)` and `find_by_id_with_deleted(id)` ([soft delete](/database/conventions/#soft-delete)).

## Method reference

### `find_by_id`

Executes `SELECT * FROM users WHERE id = ?` and returns the first matching row, or `None` if no row exists.

```rust
match repo.find_by_id(42).await? {
    Some(user) => println!("found: {}", user.email),
    None       => println!("not found"),
}
```

### `find_all`

Executes `SELECT * FROM users` and returns every row in the table.

```rust
let all_users: Vec<User> = repo.find_all().await?;
```

Use the [Query Builder](/database/query-builder/) when you need filtering, ordering, or pagination.

### `save`

Inserts or updates a single entity. With an `auto_increment` key:

- **INSERT** — when the primary key field is `0` (or `Value::Null`).
- **UPDATE** — when the primary key is non-zero; a row that isn't there is a `DbErrorKind::NotFound` error.

With any other key, `save` updates the row when the key is in the table and inserts it otherwise ([primary keys](/database/conventions/#primary-keys)). Models with `#[timestamps]`, `#[soft_delete]` or `#[version]` get those columns written by `save` and `delete_by_id` ([conventions](/database/conventions/)).

`save` returns the persisted entity with the primary key filled in (important for auto-increment inserts).

```rust
let saved = repo.save(&User {
    id:    0,   // 0 triggers INSERT with auto_increment
    name:  "Alice".into(),
    email: "alice@example.com".into(),
    role:  "user".into(),
    active: true,
}).await?;
println!("new id: {}", saved.id);   // id assigned by the database
```

To update, set a non-zero primary key:

```rust
let updated = repo.save(&User { id: saved.id, role: "admin".into(), ..saved }).await?;
```

### `save_all`

Calls `save` for each entity in the slice, returning a `Vec<T>` of the persisted entities.

```rust
let users = vec![
    User { id: 0, name: "Bob".into(),   email: "bob@example.com".into(),   .. },
    User { id: 0, name: "Carol".into(), email: "carol@example.com".into(), .. },
];
let saved = repo.save_all(&users).await?;
```

### `delete_by_id`

Executes `DELETE FROM users WHERE id = ?`.

```rust
repo.delete_by_id(42).await?;
```

### `delete_all_by_id`

Calls `delete_by_id` for each id in the slice (one DELETE per id).

```rust
repo.delete_all_by_id(&[1, 2, 3]).await?;
```

### `count`

Executes `SELECT COUNT(*) FROM users` and returns the result as `i64`.

```rust
let total: i64 = repo.count().await?;
println!("{total} users in database");
```

### `exists_by_id`

Returns `true` if a row with the given id exists.

```rust
if repo.exists_by_id(99).await? {
    println!("user 99 exists");
}
```

Internally calls `find_by_id` and checks for `Some`.

## Auto-increment PK retrieval

After an INSERT, the newly assigned primary key is retrieved differently per backend:

| Backend | Mechanism |
|---|---|
| SQLite | `last_insert_rowid()` |
| PostgreSQL | `INSERT … RETURNING id` |
| MySQL | `last_insert_id()` |

In all cases, `save` re-fetches the inserted row via `SELECT * FROM … WHERE id = ?` and returns the complete, database-consistent entity.

## Full CRUD example

```rust
use rust_web_server::model::{DbPool, Repository};
use rust_web_server::Model;

#[derive(Model, Debug, Clone)]
#[table(name = "users")]
pub struct User {
    #[primary_key(auto_increment)]
    pub id: i64,
    #[column(name = "first_name")]
    pub name: String,
    #[column(unique)]
    pub email: String,
    pub role: String,
    pub active: bool,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let pool = DbPool::from_env().await?;
    let repo = User::repository(&pool);

    // CREATE
    let alice = repo.save(&User {
        id: 0,
        name: "Alice".into(),
        email: "alice@example.com".into(),
        role: "user".into(),
        active: true,
    }).await?;
    println!("created user #{}", alice.id);

    // READ
    let found = repo.find_by_id(alice.id).await?.expect("user exists");
    println!("fetched: {} ({})", found.name, found.email);

    // UPDATE
    let promoted = repo.save(&User { role: "admin".into(), ..found }).await?;
    println!("role is now: {}", promoted.role);

    // EXISTS / COUNT
    println!("exists: {}", repo.exists_by_id(alice.id).await?);
    println!("total:  {}", repo.count().await?);

    // DELETE
    repo.delete_by_id(alice.id).await?;
    println!("deleted");

    Ok(())
}
```
