pre-alpha

GuidesData

Relations

implemented Updated November 20, 2026 5 min read

A relation is an ordinary foreign-key column. Related rows load only when a query asks for them: attribute access never performs I/O.

Declare a foreign key

# notes/apps/billing/models.py
from typing import ClassVar
from uuid import UUID, uuid4

from hinoki import db
from hinoki.orm import Model, OnDelete, Related, field, foreign_key, pk


class Customer(Model):
    id: UUID = pk(default_factory=uuid4)
    name: str = field(max_length=120)
    invoices: ClassVar["Related[list[Invoice]]"]


@db.indexed("customer_id")
class Invoice(Model):
    id: UUID = pk(default_factory=uuid4)
    customer_id: UUID = foreign_key(
        Customer, on_delete=OnDelete.RESTRICT, related_name="invoices"
    )
    reference: str = field(max_length=40, unique=True)
    customer: ClassVar[Related[Customer]]

customer_id is stored on billing_invoices. invoice.customer is the forward relation (named after the column without _id); customer.invoices is the reverse relation, created only when related_name is set. The ClassVar[Related[...]] lines are for type checkers. The column type must match the referenced primary key.

on_delete is required and takes an OnDelete member:

on_delete When the referenced row is deleted
OnDelete.RESTRICT the delete is refused while references exist
OnDelete.CASCADE referencing rows are deleted too
OnDelete.SET_NULL the column becomes NULL; the field must be \| None
OnDelete.NO_ACTION like RESTRICT, checked at the end of the statement

A refused delete raises hinoki.db.DatabaseError (database request failed), not UniqueViolation, so it is not translated to 409: check for references first, or register an error handler for it.

Text such as on_delete="cascade", and SET_NULL on a non-nullable field, are refused with RegistrationError at import:

# notes/apps/billing/models.py (continued)
@db.indexed("invoice_id")
class Payment(Model):
    id: UUID = pk(default_factory=uuid4)
    invoice_id: UUID | None = foreign_key(
        Invoice, on_delete=OnDelete.SET_NULL, default=None
    )

The rule becomes the migration's REFERENCES … ON DELETE clause and the database enforces it.

# inside an async operation
invoices = await Invoice.all().select_related("customer")
names = [invoice.customer.name for invoice in invoices]

customers = await Customer.all().prefetch_related("invoices")
counts = {c.id: len(c.invoices) for c in customers}
Method Use for SQL
select_related("customer") a forward foreign key (one row) one LEFT JOIN in the same statement
prefetch_related("invoices") a reverse or collection relation one separate, bounded query

Reading a relation that was not loaded raises RelationNotLoaded. acount() and apaginate() drop a select_related join from their COUNT (a to-one join cannot change the count) but keep a join a filter needs, such as customer__name=....

One-to-one

A one-to-one relation is a foreign key with unique=True:

# notes/apps/billing/models.py (continued)
class BillingProfile(Model):
    id: UUID = pk(default_factory=uuid4)
    customer_id: UUID = foreign_key(
        Customer, on_delete=OnDelete.CASCADE, unique=True, related_name="profile"
    )
    vat_number: str = field(max_length=20)
    customer: ClassVar[Related[Customer]]

Add profile: ClassVar["Related[BillingProfile | None]"] to Customer for type checkers. profile.customer has one required target; customer.profile is BillingProfile | None. Load them with select_related("customer") and prefetch_related("profile"). If the database has drifted and holds several rows for one customer, prefetch_related raises MultipleObjectsReturned.

The migration creates the foreign key and the unique constraint together. It fails on existing duplicates; clean them up first. Turning an existing foreign key into unique=True rebuilds the table on SQLite and needs a hand-written migration on PostgreSQL, MySQL and MariaDB.

Many-to-many

There is no implicit join table or through=: declare the association model.

# notes/apps/billing/models.py (continued)
class Tag(Model):
    id: UUID = pk(default_factory=uuid4)
    name: str = field(max_length=40, unique=True)
    invoice_links: ClassVar["Related[list[InvoiceTag]]"]


@db.unique("invoice_id", "tag_id")
@db.indexed("tag_id")
class InvoiceTag(Model):
    id: UUID = pk(default_factory=uuid4)
    invoice_id: UUID = foreign_key(
        Invoice, on_delete=OnDelete.CASCADE, related_name="tag_links"
    )
    tag_id: UUID = foreign_key(
        Tag, on_delete=OnDelete.CASCADE, related_name="invoice_links"
    )

The composite unique constraint stops duplicate pairs and indexes invoice_id; @db.indexed("tag_id") indexes the other side. Link and read:

# inside an async operation
tag = await Tag.acreate(name="priority")
await InvoiceTag.acreate(invoice_id=invoice.id, tag_id=tag.id)

links = await InvoiceTag.filter(invoice_id=invoice.id).select_related("tag")
tag_names = [link.tag.name for link in links]

invoice.tag_links holds InvoiceTag rows (load it with prefetch_related("tag_links")), not Tag objects. The association model can carry its own columns, such as when the tag was added.

Foreign keys in abstract models and mixins

A foreign key in an abstract model or mixin is registered once per table model that inherits it. Give the reverse relation a per-model name with the {model} placeholder (the class name in lower case):

# notes/apps/billing/models.py (continued)
class CustomerOwned(Model, abstract=True):
    customer_id: UUID = foreign_key(
        Customer, on_delete=OnDelete.CASCADE, related_name="{model}_set"
    )


class CreditNote(CustomerOwned):
    id: UUID = pk(default_factory=uuid4)


class Estimate(CustomerOwned):
    id: UUID = pk(default_factory=uuid4)

Customer gets creditnote_set and estimate_set. A fixed related_name makes the second inheriting model fail with an error naming both. Without related_name there is no reverse relation. A foreign key cannot reference an abstract model. {model} is the only placeholder.

See also