Tutorial
8. Projects and apps¶
An app is a package with its own models, migrations and routes, registered in
hinoki.toml. This chapter adds a billing app to the notes project from the
Quick start.
Create the app¶
From the project root:
uv run hinoki app create
| Prompt | Default | Answer |
|---|---|---|
| App name | billing |
|
| URL prefix | /billing |
/billing |
| Depends on | (none) |
The command writes the package and registers it:
notes/apps/billing/
├── api.py endpoints of the app
├── routes.py the list of routes served, mounted at the prefix
├── models.py tables of the app
└── migrations/ migration history
[[apps]]
name = "billing"
models = "notes.apps.billing.models"
migrations = "notes.apps.billing.migrations"
routes = "notes.apps.billing.routes:routes"
prefix = "/billing"
requires = []
Hinoki reads apps only from hinoki.toml; it never scans installed packages.
If billing later references a model of another app, list that app in
requires: migrations then run in dependency order.
Add a model¶
# notes/apps/billing/models.py
from datetime import datetime
from uuid import UUID, uuid4
from hinoki import db
from hinoki.orm import Model, field, pk
from hinoki.utils import utc_now
@db.ordered_by("-created_at")
class Invoice(Model):
id: UUID = pk(default_factory=uuid4)
reference: str = field(max_length=40, unique=True)
paid: bool = False
created_at: datetime = field(default_factory=utc_now, index=True)
The table name is derived: billing_invoices, the app followed by the plural
model name. @db.table("billing_invoices") pins it, so renaming the class
keeps the physical name; the model rules below ask for it.
Plan and apply the migration¶
uv run hinoki migrations plan billing
uv run hinoki migrations apply
database: sqlite:///…/notes/.hinoki/local.sqlite3 (from local SQLite default)
create table billing_invoices
wrote …/notes/apps/billing/migrations/0001-create-table-billing-invoices.sql
database: sqlite:///…/notes/.hinoki/local.sqlite3 (from local SQLite default)
notes: nothing to apply
billing: 0001-create-table-billing-invoices
plan compares the models with the recorded migration state and writes the
next migration; the number and the slug come from the change. Review the
.sql file before you apply it. With more than one app, plan needs the app
name; apply runs every app in dependency order.
Where the data goes
apply uses the application's database setting, so the variable that
configures the server, such as NOTES_DATABASE__URL, also configures the
migrations; plan, status and apply print the database they chose. With no
database configured, apply creates .hinoki/local.sqlite3 beside
hinoki.toml. HINOKI_DATABASE_URL overrides the setting for one run.
If the application cannot be loaded, the commands stop (exit 2) instead of guessing.
Migrations never run when the application starts.
Check the project¶
uv run hinoki check
uv run pytest
8 rule(s): 0 violated, 0 unverifiable, 0 waived
notes/rules.py keeps two model rules commented out:
Models.require_explicit_table and Models.require_foreign_key_index.
hinoki check sees only the models the application imports, and a model rule
that matches no model is unverifiable, which fails the check. Turn them on
(and import Models) once a billing route imports Invoice; then add
@db.table("billing_invoices") above the class, or the check reports:
notes/apps/billing/models.py:10: HNK-DB-001 [violated] Invoice uses the derived table name 'billing_invoices'
fix: name the table with @db.table(...) or table=... on the model
Pinning the derived name changes no table: migrations plan billing then
reports no changes.
Endpoints for billing go in notes/apps/billing/api.py, and routes.py lists
them. The application in notes/main.py includes every app's list with
manifest_routes(), which mounts this one at /billing, so paths inside the
app never repeat the prefix:
# notes/main.py (as hinoki new wrote it)
from hinoki import Hinoki
from hinoki.project import manifest_routes
from notes.rules import project_rules
from notes.settings import ProjectSettings
app = Hinoki(
settings=ProjectSettings, # NOTES_* variables and .env
include=manifest_routes(), # notes/routes.py, then each app's routes at its prefix
title="Notes",
openapi_url="/openapi.json",
docs_url="/docs",
rules=project_rules,
)
The project's rules require every action to name an
Access policy with permissions; build one as in chapter 4.
Recap¶
hinoki app createwrites an app and registers it inhinoki.toml.- Table names, migration numbers and slugs are derived; you review the SQL.
- The manifest sets each app's prefix; code never repeats it.