1.2 · Get started
Quick start¶
This walkthrough uses the default local SQLite database, so no database server or URL setup is needed. It creates the table with an explicit migration; Hinoki does not create or migrate tables when the app starts. To use PostgreSQL, MySQL or MariaDB instead, see Configure a database.
Plan and apply the migration¶
examples/hinoki.toml registers Notes, Tracker and Blog as independent apps.
From the repository root, enter examples/ and use the locked environment in
the parent directory. On a fresh checkout, the checked-in Notes migration is
already up to date, so planning reports no changes. Inspect the registered
apps and migration SQL:
cd examples
uv run --project .. hinoki app list
uv run --project .. hinoki migrations plan --app notes
uv run --project .. hinoki migrations sql --app notes 0001-create-table-notes
Review the SQL, then apply it explicitly. With no URL set, the migration
command and the Notes app both use sqlite://./.hinoki/local.sqlite3:
uv run --project .. hinoki migrations apply --app notes
The local database file and migration ledger are created when apply runs.
Use a disposable database while evaluating the example.
Start the app and send a request¶
uv run --project .. hinoki dev notes.main:app
The database field of the Notes settings opens a pool for the worker and closes it at shutdown. It does not create tables. In another terminal, create a note and list the collection:
curl -i -X POST http://127.0.0.1:8000/notes \
-H 'content-type: application/json' \
-d '{"title":"First note","body":"Hello"}'
curl http://127.0.0.1:8000/notes
The POST returns 201 Created and a JSON object with the generated id, title and body. The GET returns a JSON array. Invalid input is rejected before the handler runs; see error handling for the response format.
Where to go next¶
- Tutorial: build the Tracker example in seven steps, then learn the project and app workflow.
- Models and queries: fields, querysets and relation loading.
- Migrations: migration files, destructive changes and deployment workflow.
- Configure a database: choose another backend, set its URL and understand backend-specific behavior.
- API reference: public symbols and signatures.