2.2 · Tutorial
1. Models¶
A model is a table. Hinoki's models are active records over a Rust query compiler: no lazy loading, no surprises.
from datetime import datetime
from uuid import UUID, uuid4
from hinoki.orm import Model, OnDelete, field, foreign_key, indexed, ordered_by
from hinoki.utils import utc_now
class Member(Model, table="tracker_members"):
id: UUID = field(primary_key=True, default_factory=uuid4)
name: str = field(max_length=80)
token: str = field(unique=True)
@indexed("owner_id", "created_at")
@ordered_by("-created_at", "-id")
class Task(Model, table="tracker_tasks", label="Task", plural="Tasks"):
id: UUID = field(primary_key=True, default_factory=uuid4)
owner_id: UUID = foreign_key(
Member, on_delete=OnDelete.RESTRICT, related_name="tasks"
)
title: str = field(max_length=120)
done: bool = False
created_at: datetime = field(default_factory=utc_now)
completed_at: datetime | None = None
The explicit tracker_members and tracker_tasks names above are pinned to
the example's checked-in migration history. New models can omit table=:
from uuid import UUID, uuid4
from hinoki.orm import Model, field
class Invoice(Model):
id: UUID = field(primary_key=True, default_factory=uuid4)
reference: str
Placed in a billing package's models module, that declaration derives the table
billing_invoices (<app>_<models>), the singular display name
Invoice and the plural Invoices. label= and plural= override the
display names; set table= explicitly for irregular/localized names and to
keep a physical table stable when a Python class is renamed. The fallback
pluralizer is deterministic and English-oriented, so use explicit names for
irregular nouns.
@indexedand@ordered_byare decorators that state facts about the model below them (model options). The default order applies to every query that does not callorder_by.foreign_key(Member, ...)is a column holding the owner's id; the relation (task.owner) is never fetched by accident.
The migration¶
The Tracker example already includes the migrations for this model and its index. Inspect the checked-in SQL and apply it to a disposable database:
cd examples
uv run --project .. hinoki migrations status
uv run --project .. hinoki migrations sql --app tracker 0001-initial
uv run --project .. hinoki migrations sql --app tracker 0002-indexes
uv run --project .. hinoki migrations apply --app tracker
CREATE TABLE "tracker_tasks" ( ... );
CREATE INDEX "ix_tracker_tasks_owner_id_created_at" ON "tracker_tasks" ("owner_id", "created_at");
The repository's examples/hinoki.toml registers Tracker alongside Notes and Blog, each with a separate model module and migration package. When you change a model, hinoki migrations plan --app tracker compares declarations with the recorded state and writes the next migration; the number and slug are derived automatically, and --name can override the slug. Review the SQL before applying it; migrations never run at app startup. Destructive changes are flagged and need --allow-destructive. Chapter 8 creates a new manifest-based project with hinoki new and adds apps with hinoki app create.
Next: 2. Schemas.