pre-alpha

Guides

Guides

implemented Updated November 20, 2026 4 min read

One page per task. Start with data and endpoints, then add access, rules and runtime concerns as you need them. New to Hinoki? Take the tutorial or the quick start first.

Data

  • Configure a databasechoose the backend, set the URL or connection fields, keep credentials secret.
  • Define modelscolumns, primary keys, column types, table names and write-time validators.
  • Model optionsindexes, composite uniqueness, default order, update timestamps and names, as decorators.
  • Relationsforeign keys, one-to-one, many-to-many association models and explicit loading.
  • Query and write rowsfilters, pagination, reusable queries, creates, updates and bulk writes.
  • Lifecycle hooksreact to a model's own writes and inspect its changed columns.
  • Migrationsplan, review, apply and check migrations for every app.
  • Schemasdeclare the data that crosses the API boundary and convert it to and from rows.
  • Scalar field typesenums, literals, dates, decimals, bytes, addresses, secrets and paths.
  • Collections and unionssets, tuples, dictionaries, unions, discriminated unions, TypedDicts and dataclasses.
  • Validate inputconstraints, normalization, field and object checks, and input reshaping.
  • Schemas from modelsderive a Schema from a Model and convert rows with from_model.
  • Time and utilitiesUTC time, the application timezone, test clocks and update timestamps.

Endpoints

  • Function-based APIsthe default pattern: plain functions grouped by a RouteGroup that states access, transactions and errors once.
  • Class-based APIsAPI classes for @crud resources with hooks, inheritance and resources you ship to others.
  • Register routeshow routes.py and hinoki.toml build the route map, with Mount, include= in tests and hinoki routes.
  • Requests and responseswhat an action receives (path, query, body, forms, XML, files) and how its result is checked.
  • Generate CRUD routeslist, retrieve and write actions from a model, with access and ownership rules.
  • Errorsmalformed requests, authentication failures and declared application errors.
  • Middlewaretyped Middleware around an action or the whole app, identical on Kiso and Granian.
  • Paginationpage-number pagination with PageNumberPagination.
  • Parsers and renderersother body formats in and out.
  • OpenAPI documentthe OpenAPI 3.1 document generated from routes, signatures and Schema declarations.

Security and checks

  • Authentication and accessproviders resolve a Caller; Access policies check permissions.
  • Hosts, CORS and HTTPSrestrict the host names an app answers to, which browser origins may read it, browser security headers, HTTPS redirects and trusted proxies.
  • Rulestyped promises about your application, checked with a stable ID, a location and an explanation.

Runtime

  • Application modulesresources that live as long as a worker, such as a database pool.
  • Transactionsatomic=True on actions, db.atomic in application code.
  • Settingstyped, immutable settings from the environment, dotenv and TOML, with redacted secrets.
  • Serve an applicationhinoki dev while you work, hinoki serve in production, on Kiso (the default) or Granian.
  • Kiso serverwhat Hinoki's Rust server runs natively, its limits, workers and signals, reload and reverse-proxy behaviour.
  • Test an applicationtest through the whole stack with ASGIClient, against a disposable database, from the test hinoki new generates.
  • Command lineevery hinoki command, the short forms inside a project and the explicit forms outside one.
  • Create a projectthe interactive hinoki new flow, its options and what the generated project contains.
  • Inspect an applicationcheck rules, list routes, export the OpenAPI document, show settings and diagnose the environment.
  • Interactive shellan async-capable prompt with the app's settings and models.
  • Typingwhat a type checker catches in handlers, decorators and Schema construction.

Integrations

  • Add an adminstaff pages for your models, with a sign-in page, users and per-model permissions.
  • Customize the admincolumns, hooks, bulk actions, templates and themes.
  • Expose actions over MCPselected actions as tools for a remote MCP client.
  • Development MCPa server that describes your app to a coding agent; it can run requests against the app only when you enable --scenarios.
  • Build with a coding agenta project, rules and tools ready for an agent, and where its authority ends.

Operating

Concepts and project