GuidesData
Define models¶
A Model maps a Python class to one table. Annotated fields are the columns;
indexes, ordering and other options are decorators. A model
never opens a connection on import and never loads a relation implicitly.
# notes/apps/billing/models.py
from datetime import datetime
from uuid import UUID, uuid4
from hinoki import db
from hinoki.orm import Model, OnDelete, field, foreign_key, pk
from hinoki.utils import utc_now
class Customer(Model):
id: UUID = pk(default_factory=uuid4)
name: str = field(max_length=120)
email: str = field(max_length=254, unique=True)
@db.indexed("customer_id", "created_at")
@db.ordered_by("-created_at", "-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)
paid: bool = False
created_at: datetime = field(default_factory=utc_now)
The tables are billing_customers and billing_invoices. Changing a model
never changes the database: create the tables with
hinoki migrations plan billing and hinoki migrations apply
(migrations).
Declare columns¶
| Declaration | Column |
|---|---|
name: str |
required, not null |
note: str \| None = None |
nullable, optional in the constructor |
paid: bool = False |
default value |
id: UUID = pk(default_factory=uuid4) |
the primary key |
email: str = field(max_length=254, unique=True) |
bounded text, unique |
created_at: datetime = field(default_factory=utc_now, index=True) |
factory default, single-column index |
customer_id: UUID = foreign_key(Customer, on_delete=...) |
a reference (relations) |
field() takes unique, index, max_length, default, default_factory,
constraints and validators. The annotation gives the type and nullability.
- One primary key.
pk()declares it; passdefaultordefault_factorywhen the constructor may omit it. A nullable key (int | None) raisesRegistrationErrorwhen the class is defined. - Keyword-only constructor.
Invoice(reference="INV-1", customer_id=c.id). - Indexes.
field(index=True)indexes one column; it cannot be combined withunique=Trueorpk(), which are already indexed. Aforeign_keyhas noindex=option: index it with@db.indexed(...), or a composite index that starts with it, asInvoicedoes (model options). - Composite uniqueness is
@db.unique("a", "b"); there is no nestedclass Meta.
Column types¶
| Python type | Stored as | Read back as |
|---|---|---|
str, int, float, bool |
the backend's text, integer, float and boolean types | the same type |
UUID, datetime |
native on PostgreSQL; text on SQLite | UUID, datetime |
dict[...], list[...] |
JSON (JSON text on SQLite, text alias on MariaDB) | decoded by the annotation |
bytes |
BYTEA on PostgreSQL, blob on SQLite |
bytes |
date, time |
ISO text (time with microseconds, no timezone) |
date, time |
timedelta |
whole microseconds, bigint |
timedelta |
Enum subclass |
its value: bigint when every value is an integer, else text |
the member |
IPv4Address, IPv6Address, IPv4Network, IPv6Network |
text | the ipaddress object; writes accept only that class |
Decimal |
exact, per backend (below) | Decimal |
A stored value that does not read back as its annotation raises FieldError.
date and timedelta compare and order by value. A set, tuple, Literal,
plain union or Any column has no SQL type: the migration planner reports
no SQL type. SQLite's contains folds ASCII case only.
Decimal columns¶
| Backend | Column | Filters and ordering |
|---|---|---|
| PostgreSQL | numeric |
=, ne, in, isnull, gt, gte, lt, lte, order_by |
| MySQL, MariaDB | decimal(65,30) |
the same; read back with scale 30 (Decimal("1.5") returns as Decimal("1.500…0"), equal in value) |
| SQLite | text (its exact spelling) |
=, ne, in, isnull only; 12.3 and 12.30 differ; range filters and order_by raise FieldError |
# notes/apps/billing/models.py (continued)
from decimal import Decimal
class Price(Model):
id: UUID = pk(default_factory=uuid4)
amount: Decimal
# inside an async operation
# every backend
cheap = await Price.filter(amount=Decimal("9.99"))
# not SQLite
ordered = await Price.filter(amount__gte=Decimal("5")).order_by("amount")
- A filter value is a
Decimal, anintor a numeric string; afloat, abool,NaN, an infinity orcontainsraisesFieldError. decimal(65,30)bounds MySQL and MariaDB to 35 digits before the point; PostgreSQLnumericis unbounded.- A table that already stores a
Decimalas text on PostgreSQL or MySQL needs a reviewed migration that changes the column type. - A generated CRUD list whose
@db.ordered_bynames aDecimalcolumn takes the Python path on SQLite, where that ordering is refused.
Table and display names¶
Hinoki derives the table name <app>_<models> and display names from the class.
| Model | Module | Table | Labels |
|---|---|---|---|
Invoice |
notes.apps.billing.models |
billing_invoices |
Invoice / Invoices |
LineItem |
notes.apps.billing.models |
billing_line_items |
Line item / Line items |
Note |
notes.models or notes.models.note |
notes_notes |
Note / Notes |
APIKey |
notes.models |
notes_api_keys |
API key / API keys |
The app is the package that holds the models module; a module without a
models segment uses its own last name. The plural is a small English rule:
consonant + y → ies; s, x, z, ch, sh → es; otherwise s. It
does not know irregular nouns (Person → persons).
| Override | Form |
|---|---|
| app part of the name | class Invoice(Model, app="accounts") |
| whole table name (never prefixed) | @db.table("invoices") |
| display names | class Person(Model, label="Person", plural="People") |
Pin the table name with @db.table(...) when a model already has migration
history and you rename the class or move its module: a changed derived name is
planned as a drop and a create, which the destructive-migration guard stops; it
is never a rename. The optional HNK-DB-001 rule
(Models.require_explicit_table) requires every matching model to pin it.
Names must be portable ASCII of at most 63 characters. A derived name that is
rejected (sqlite_…, hinoki_migrations, non-ASCII such as class Café) does
not stop the class from being defined: @db.table("cafes") can still name it.
Without one, the error is raised when the model is first used (query, write,
migration plan, project or admin registration, or a foreign key to it).
Model field constraints and validators¶
field() can also check values before every ORM write. Use
constraints=Field(...) for built-in checks and validators=(...) for
synchronous application rules:
# notes/apps/billing/models.py (continued)
from hinoki import Field
def no_padding(value: str) -> None:
if value != value.strip():
raise ValueError("surrounding whitespace is not allowed")
class Product(Model):
id: UUID = pk(default_factory=uuid4)
sku: str = field(
max_length=32, constraints=Field(min_length=3, pattern=r"[A-Z0-9-]+")
)
price: float = field(constraints=Field(gt=0))
name: str = field(max_length=120, validators=(no_padding,))
- When. Immediately before inserts and ORM updates, filtered bulk updates included; never on construction, assignment or reads. Invalid declarations fail when the class is created.
- Checks. String and list lengths, patterns, membership and numeric bounds.
A JSON column (
dict[...],list[dict[...]]) takes no built-in checks; validators still run on it. - Failure.
ModelValidationError, before any SQL, withdetailsholding each field'spath,codeandmessage. In a request it becomes the standard 422 response; the admin shows the messages. - Validators are synchronous, raise
ValueErrorto refuse, perform no I/O and do not change the value. Rules about other rows, permissions or current state belong in an operation.
These checks protect CLI, admin and direct ORM writes; a Schema still
validates HTTP input first (validate input). Database
constraints remain authoritative.
Share fields: abstract models and mixins¶
An abstract model has no table: it is not migrated, cannot be queried and only exists to be subclassed.
# notes/apps/billing/models.py (continued)
class Keyed(Model, abstract=True):
id: UUID = pk(default_factory=uuid4)
@db.timestamps()
@db.ordered_by("-updated_at")
class Tracked(Model, abstract=True):
created_at: datetime = field(default_factory=utc_now)
updated_at: datetime = field(default_factory=utc_now, index=True)
class Article(Keyed, Tracked):
title: str = field(max_length=120)
Article has created_at, updated_at, id and title, is ordered by
-updated_at, indexes updated_at and refreshes it on every update.
Tracked.all() raises ModelError.
abstract=Trueis not inherited; an abstract model needs no primary key, a table model needs exactly one, its own or inherited.- Options from abstract bases are inherited: all
@db.uniqueand@db.indexed, and the order and timestamp column of the first base that sets one. A decorator on the subclass replaces that kind of option. Afield(index=True)index belongs to its column and is dropped when a subclass redeclares the column without it. Constraint names are not inherited: an abstract model cannot use@db.unique(..., name=...). - Plain mixins (non-model classes) contribute annotated fields and methods;
ClassVarannotations are not fields. Type checkers do not see mixin fields as constructor arguments: prefer an abstract model. - Conflicting types. Two bases giving one field different types are refused unless the class redeclares the field.
- Subclassing a table model copies its columns into a separate, unrelated table; no join, no shared rows, no inherited options.
- Column order follows dataclass rules: model bases (last listed first), then mixins, then the class's own fields.
A foreign key in an abstract model needs a per-subclass reverse name; see relations.