Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Relations guide

ruprizzle generates one relation loader per relation. The loader is a value-level description of how to fetch the other side, and the actual loading is batched so the query count is bounded by the number of levels, not the number of parent rows.

All snippets below assume a generated db module. They are wrapped in rust,ignore because they depend on generated code.

One-to-many and many-to-one

Given the blog schema, User has many Posts and each Post has one author:

let users = db.user()
    .find_many()
    .include(user::posts().take(5))
    .exec()
    .await?;

for user in &users {
    for post in user.posts.get() {
        println!("{}: {}", user.name, post.title);
    }
}

let posts = db.post()
    .find_many()
    .include(post::author())
    .exec()
    .await?;

for post in &posts {
    if let Some(author) = post.author.get() {
        println!("{} by {}", post.title, author.name);
    }
}

include() changes the execution method. Use exec(), exec_one(), or exec_optional() instead of fetch_all()/fetch_one()/fetch_optional() so the relation is loaded.

Accessing loaded relations

Relation fields are Related<T>. Access the loaded value with .get():

  • Related<Vec<Post>> decodes to &Vec<Post>.
  • Related<Option<User>> decodes to &Option<User>.
let user = db.user()
    .find_many()
    .filter(user::ID.eq(alice_id))
    .include(user::posts())
    .exec_one()
    .await?;

for post in user.posts.get() {
    println!("{}", post.title);
}

try_get() returns Option<&T> and is useful when you are not sure whether a relation was included. is_absent() and is_loaded() let you check the state without panicking.

Filtering included children

Add filters, ordering, and a per-parent limit to the include:

let users = db.user()
    .find_many()
    .include(
        user::posts()
            .filter(post::PUBLISHED.eq(true))
            .order_by(post::CREATED_AT.desc())
            .take(10),
    )
    .exec()
    .await?;

take(n) is a per-parent limit, not a global limit. It is compiled to a ROW_NUMBER() OVER (PARTITION BY ...) window on dialects that support it.

Single-row includes

fetch_one() and fetch_optional() are unavailable once include() is present. Use the include-aware equivalents:

let user = db.user()
    .find_many()
    .filter(user::ID.eq(alice_id))
    .include(user::posts().take(5))
    .exec_one()
    .await?;

let maybe = db.user()
    .find_many()
    .filter(user::EMAIL.eq("nobody@example.com"))
    .include(user::posts())
    .exec_optional()
    .await?;

Many-to-many without a join model

When two models declare list fields pointing at each other and neither names a through model, the join table is inferred rather than declared:

model Post {
  id   Int    @id
  tags Tag[]
}

model Tag {
  id    Int    @id
  posts Post[]
}

The parser synthesises a join model named _<A>To<B> — the two model names sorted alphabetically, so _PostToTag — with columns A and B holding the two primary keys. A @relation(name: "...") on the pair produces _<A>To<B>_<name> instead, which is how two independent many-to-many links between the same pair stay apart.

The generated *_attach, *_set and *_detach helpers work the same way as for an explicit join model; the difference is only in what you write in the schema. Declare the join model explicitly (below) when it needs columns of its own — an ordering index, a timestamp, a role.

Many-to-many with an explicit join model

ruprizzle does not hide join tables. A Post with many Tags through an explicit PostTag model looks like this:

model Post {
  id   Int   @id
  tags Tag[] @relation(through: PostTag)
}

model Tag {
  id    Int     @id
  posts Post[]  @relation(through: PostTag)
}

model PostTag {
  post_id Int
  tag_id  Int
  post    Post @relation(fields: [post_id], references: [id])
  tag     Tag  @relation(fields: [tag_id], references: [id])

  @@id([post_id, tag_id])
  @@map("post_tags")
}

The generated code provides an IncludeMany loader and a query helper:

let posts = db.post()
    .find_many()
    .include(post::tags())
    .exec()
    .await?;

for post in &posts {
    for tag in post.tags.get() {
        println!("{} has tag {}", post.id, tag.id);
    }
}

// Or load tags for a single post directly
let tags = post::tags_query(db.raw_pool(), post_id).fetch_all().await?;

Nested writes on insert

Create a parent and its children in one call. The children must be supplied as an InsertManyQuery, and a NestedSetter attaches the loaded child rows to the parent.

use ruprizzle::{Encodable, InsertManyQuery, NestedSetter, Value};

struct SetPosts;
impl NestedSetter<User> for SetPosts {
    fn set(&self, parent: &mut User, batch: ruprizzle::executor::RowBatch) {
        parent.posts = ruprizzle::Related::Loaded(
            ruprizzle::executor::decode_rows::<Post>(batch).unwrap(),
        );
    }
}

let children = InsertManyQuery::<Post>::new(db.raw_pool())
    .row([("title", Value::Str("Hello".into()))])
    .row([("title", Value::Str("World".into()))]);

let user = db.user()
    .create(UserInsert {
        id: None,
        email: "alice@example.com".into(),
        name: Some("Alice".to_string()),
        role: None,
        created_at: None,
        updated_at: None,
    })
    .with_related(|u| u.id.to_value(), "author_id", children, SetPosts)
    .exec()
    .await?;

// Many-to-many on insert uses the generated *_set helper
let post = db.post()
    .create(PostInsert {
        id: None,
        title: "A post".into(),
        body: None,
        published: Some(true),
        author_id: user_id,
        created_at: None,
    })
    .with_m2m(post::tags_set(vec![rust_tag_id, orm_tag_id]))
    .exec()
    .await?;

Nested writes on update

For one-to-many relations, use connect, disconnect, and set_related. The update must match exactly one parent row.

use ruprizzle::Encodable;

// Attach existing posts to a user
db.user()
    .update()
    .filter(user::ID.eq(user_id))
    .connect::<Post, _, _>(|u| u.id.to_value(), "author_id", "id", vec![post_id_1, post_id_2])
    .exec()
    .await?;

// Detach specific posts
db.user()
    .update()
    .filter(user::ID.eq(user_id))
    .disconnect::<Post, _, _>(|u| u.id.to_value(), "author_id", "id", vec![post_id_1])
    .exec()
    .await?;

// Replace the user's posts with a new set
db.user()
    .update()
    .filter(user::ID.eq(user_id))
    .set_related::<Post, _, _>(|u| u.id.to_value(), "author_id", "id", vec![post_id_3])
    .exec()
    .await?;

For many-to-many relations, the generated *_attach, *_set, and *_detach helpers return an M2mWrite:

db.post()
    .update()
    .set(post::TITLE, "Updated title")
    .filter(post::ID.eq(post_id))
    .with_m2m(post::tags_attach(vec![tag_id_1, tag_id_2]))
    .exec()
    .await?;

// Replace all tags for a post
db.post()
    .update()
    .filter(post::ID.eq(post_id))
    .with_m2m(post::tags_set(vec![tag_id_1]))
    .exec()
    .await?;

// Detach a tag
db.post()
    .update()
    .filter(post::ID.eq(post_id))
    .with_m2m(post::tags_detach(vec![tag_id_1]))
    .exec()
    .await?;

Cascading deletes

DeleteQuery::cascade runs the referential action in a transaction before deleting the parent rows. The action must match the onDelete declared on the relation.

use ruprizzle::DeleteAction;

let deleted = db.user()
    .delete()
    .filter(user::ID.eq(user_id))
    .cascade::<Post>("author_id", DeleteAction::Cascade)
    .exec()
    .await?;

DeleteAction has the variants Cascade, Restrict, SetNull, SetDefault, and NoAction. SetDefault is accepted by the schema parser, but DeleteQuery::cascade will return an error at runtime if you use it; default-value handling is not yet wired to the cascade runner.

Self-referential relations

A model that references itself, such as an Employee with a manager_id, can be loaded with aliased includes:

// Each employee has one manager
let employees = db.select::<Employee>()
    .include(employee::manager())
    .exec()
    .await?;

// Each manager has many reports
let managers = db.select::<Employee>()
    .include(employee::reports().take(10))
    .exec()
    .await?;

The generated module provides manager() and reports() relation loaders for self-referential schemas. Include depth is limited by the schema's max_include_depth generator setting.

Tree hierarchies

A self-referential model — one whose parent foreign key points at its own primary key — also gets recursive-CTE traversal helpers, so an arbitrarily deep tree is one query rather than one query per level.

// Every ancestor of a node, walking up to the root.
let chain = db.category().ancestors(node_id).all().await?;

// The whole subtree below a node, bounded to three levels.
let subtree = db.category()
    .descendants(node_id)
    .max_depth(3)
    .all()
    .await?;

// The subtree reassembled in memory as a `HierarchyNode<Category>`.
let tree = db.category().tree_from_root(root_id).await?;

ancestors and descendants return a HierarchyQuery, which has max_depth, order_by_depth_asc / order_by_depth_desc, cycle_protection, with_deleted (since 1.6; includes soft-deleted nodes and the subtrees below them), and — like every other builder — to_sql(), so the generated WITH RECURSIVE statement is inspectable. Cycle protection is on by default: each path carries the keys it has visited and never steps onto one again, so a corrupted parent chain returns each node once instead of spinning. It also caps the walk at 100 levels unless max_depth is set. The visited keys are kept as a comma-separated string, so a text key that contains a comma can be mistaken for a visited node. Pass cycle_protection(false) only when the data is known to be acyclic: with it off and no max_depth, a cycle recurses until Postgres or SQLite cancel the statement, or MySQL hits cte_max_recursion_depth. (Before 1.5.2, protection was only the depth cap, and a cycle came back as dozens of duplicate rows.)

some, every, and none relation filters

For each relation, the generator emits *_some, *_every, and *_none functions that return a Filter on the parent model.

// Users with at least one published post
let authors = db.user()
    .find_many()
    .filter(user::posts_some(post::PUBLISHED.eq(true)))
    .fetch_all()
    .await?;

// Users whose every post is published
let all_published = db.user()
    .find_many()
    .filter(user::posts_every(post::PUBLISHED.eq(true)))
    .fetch_all()
    .await?;

// Users with no published posts
let no_posts = db.user()
    .find_many()
    .filter(user::posts_none(post::PUBLISHED.eq(true)))
    .fetch_all()
    .await?;

For a many-to-one relation, the generated helpers are named from the child side:

let posts = db.post()
    .find_many()
    .filter(post::author_some(user::NAME.eq("Alice")))
    .fetch_all()
    .await?;

Why this avoids N+1

A naive loop would issue one query per parent to fetch children. include works in two batched stages:

  1. Run the parent query.
  2. Collect the parent keys, run one IN (...) or full-table query per child level, and distribute the child rows back into the parent structs in Rust.

The per-parent limit in take(n) is implemented with a ROW_NUMBER() OVER (PARTITION BY ...) window on dialects that support it. If the dialect does not support window functions, it falls back to one query per parent, which is the only case where the query count is linear in the parent count.

Full-table fast path and its bound

When the parent query is an unfiltered full-table fetch and the include has no extra filter, order, or per-parent limit, ruprizzle can load the whole child table in one query instead of building a large IN (...) list. Before taking that path, it COUNT(*)s the child table and only uses the full-table load when the count is below PoolConfig::full_table_include_limit (default 100_000). If the child table is larger, the loader falls back to a chunked IN (...) list, which preserves the bounded-query guarantee without materialising millions of rows. Set the field to None to disable the fast path entirely.