pre-alpha

3.8 · Guides

Relations, many-to-many and loading

Hinoki stores relations as ordinary foreign-key columns and loads related rows only when a query asks for them. Attribute access never performs hidden I/O.

Declare a foreign key

from uuid import UUID, uuid4

from hinoki.orm import Model, OnDelete, field, foreign_key


class Author(Model):
    id: UUID = field(primary_key=True, default_factory=uuid4)
    name: str


class Post(Model):
    id: UUID = field(primary_key=True, default_factory=uuid4)
    author_id: UUID = foreign_key(
        Author,
        on_delete=OnDelete.RESTRICT,
        related_name="posts",
    )
    title: str

The author_id field is stored on posts. The forward relation is post.author; author.posts is the reverse relation. The foreign-key type must match the referenced primary-key type. on_delete is required, so what happens to a row when the row it references is deleted is always a decision. Its value is a member of the OnDelete enum (from hinoki.orm import OnDelete):

on_delete When the referenced row is deleted
OnDelete.RESTRICT The delete is refused while referencing rows exist
OnDelete.CASCADE The referencing rows are deleted too
OnDelete.SET_NULL The column is set to NULL; the field must be annotated | None
OnDelete.NO_ACTION Like RESTRICT, checked by the database at the end of the statement

Only enum members are accepted. Text such as on_delete="cascade", which earlier revisions took, is reported by a type checker and refused with a RegistrationError when the module is imported. OnDelete.SET_NULL on a field without | None is refused the same way, before any migration is planned:

class Note(Model):
    id: UUID = field(primary_key=True, default_factory=uuid4)
    post_id: UUID | None = foreign_key(Post, on_delete=OnDelete.SET_NULL, default=None)

The rule is written into the REFERENCES ... ON DELETE clause of the generated migration and enforced by the database.

Foreign keys in abstract models and mixins

A foreign key declared in an abstract model or a mixin is registered once for each table model that inherits it. The forward relation keeps its name on every model. The reverse name must differ, so write it with the {model} placeholder, which becomes the inheriting class's name in lower case:

class Owned(Model, abstract=True):
    team_id: UUID = foreign_key(
        Team, on_delete=OnDelete.CASCADE, related_name="{model}_set"
    )


class Article(Owned):
    id: UUID = field(primary_key=True, default_factory=uuid4)


class Page(Owned):
    id: UUID = field(primary_key=True, default_factory=uuid4)

Team gets the reverse relations article_set and page_set. With a fixed related_name, the second model that inherits the field is refused with an error naming both models. A table model that subclasses another table model copies the column and the forward relation; it gets a reverse relation of its own only when the name uses the placeholder, because a fixed name already belongs to its parent. A foreign key cannot reference an abstract model, which has no table. {model} is the only placeholder. Without related_name there is no reverse relation and nothing can collide.

Use select_related for a forward foreign key when a query needs one related row (one LEFT JOIN in the same statement; acount() and apaginate() leave that join out of their COUNT, since loading a to-one relation cannot change the row count, but keep a join that a filter such as author__name=... needs). Use prefetch_related for a reverse or collection relation; it issues a separate bounded query and attaches the results.

posts = await Post.all().select_related("author")
for post in posts:
    print(post.author.name)

Accessing an unloaded relation raises a relation-loading error. Load the relation explicitly so the query is visible in the calling code.

One-to-one relations

A one-to-one relation uses the same foreign-key declaration with unique=True; there is no separate field helper. The unique constraint enforces that each target is referenced by at most one row. Keep the reverse relation explicit with related_name:

from __future__ import annotations

from typing import ClassVar
from uuid import UUID, uuid4

from hinoki.orm import Model, OnDelete, field, foreign_key
from hinoki.orm.relations import Related


class User(Model):
    id: UUID = field(primary_key=True, default_factory=uuid4)
    profile: ClassVar[Related[Profile | None]]


class Profile(Model):
    id: UUID = field(primary_key=True, default_factory=uuid4)
    user_id: UUID = foreign_key(
        User,
        on_delete=OnDelete.CASCADE,
        unique=True,
        related_name="profile",
    )
    user: ClassVar[Related[User]]

The forward profile.user relation has one required target. The reverse user.profile relation is Profile | None: a user may not have a profile. Load it explicitly and in a bounded number of queries:

profiles = await Profile.all().select_related("user")
users = await User.all().prefetch_related("profile")

select_related joins the forward target into the profile query; prefetch_related uses one batched query for profiles and returns one profile or None per user. Neither access pattern performs lazy queries. If a database has drifted and contains multiple rows despite the unique declaration, prefetch_related raises MultipleObjectsReturned rather than choosing one. Migrations create the FK and unique constraint together; applying a unique constraint to existing duplicate data fails and requires an explicit data cleanup before retrying. When changing an existing foreign key to unique=True, SQLite rebuilds the table and may reject duplicates; MySQL, MariaDB and PostgreSQL require a hand-written migration for the uniqueness change. Resolve duplicates before applying the constraint.

Many-to-many relationships are represented by an explicit join model with two foreign keys and a composite @unique constraint. There is no implicit many-to-many table or through= shortcut.

Model a many-to-many relationship

Define a model for the association table. Each row links one post to one tag; the composite uniqueness constraint prevents the same pair from being inserted twice.

from typing import ClassVar
from uuid import UUID, uuid4

from hinoki.orm import Model, OnDelete, field, foreign_key, unique
from hinoki.orm.relations import Related


class Post(Model):
    id: UUID = field(primary_key=True, default_factory=uuid4)
    title: str
    tag_links: ClassVar["Related[list[PostTag]]"]


class Tag(Model):
    id: UUID = field(primary_key=True, default_factory=uuid4)
    name: str
    post_links: ClassVar["Related[list[PostTag]]"]


@unique("post_id", "tag_id")
class PostTag(Model):
    id: UUID = field(primary_key=True, default_factory=uuid4)
    post_id: UUID = foreign_key(
        Post, on_delete=OnDelete.CASCADE, related_name="tag_links"
    )
    tag_id: UUID = foreign_key(
        Tag, on_delete=OnDelete.CASCADE, related_name="post_links"
    )

Create a link by inserting a PostTag row. To read a post's tags, query the join model and load its tag foreign key in the same query:

post = await Post.acreate(title="Release notes")
tag = await Tag.acreate(name="docs")
await PostTag.acreate(post_id=post.id, tag_id=tag.id)

links = await PostTag.filter(post_id=post.id).select_related("tag")
tag_names = [link.tag.name for link in links]

The reverse post.tag_links relation contains PostTag rows; load it with prefetch_related("tag_links") before accessing it. It does not return Tag objects or fetch data on attribute access. A join model can also carry its own fields, such as the time a tag was added. Include all three models in the migration plan so the association table and its uniqueness constraint are created together.

This explicit form supports association rows and their foreign-key relations. Hinoki does not currently generate the join model or expose a direct post.tags relation.

See models and queries and migrations for schema changes to foreign keys.