0173. Database code, starter domains and an admin are each added by choice, and the framework never requires an ORM
- Status: Proposed (the direction is Mik's; the design awaits his approval)
- Date: 2026-11-18
- Decided by: Decision 0171, section 9, named three things Django and Phoenix still do better: tables and queries from the models, a ready sign-in system, and an admin. Mik answered on 18 Nov 2026: "We should think about the three things django and phoenix do better, but I think an ORM for migrations shouldn't be a requirement. It's one of the things I dislike about django, but it should be addable based on the Developer's preference." The design is the integrator's.
- Planning item:
docs/plan/server-roadmap.md, work packages 38 to 40
Context
After decisions 0163 to 0171 a developer writes a domain file and one method per operation. Three kinds of work are still done by hand in every app: the database code behind each method, the accounts domain that every app needs, and a screen for staff to look at and correct data.
Django answers the first with an ORM that owns the models, the queries and the migrations. Mik does not want that to be required. IDX-Studios/work-stable-api already shows the shape he prefers: its table types are generated from annotated YAML, its queries are written by hand in Kysely, and its migrations are written by hand in Knex and held back when they would drop or rename something.
So the rule for this record is: each of the three is something an app adds, each works without the other two, and an app that adds none of them loses nothing it has today.
Decision
1. Database code: nothing by default, and four things an app can add
With nothing added, a model is a shape that is validated on the way in and out. The method talks to the database with whatever the developer likes, and migrations are run with whatever tool they like. This is the plan as it stood, and it stays the default.
A shape with an identity (a model) can then be marked as stored. That is one line in the domain file, and by itself it only records which table and columns the model maps to (derived from its name and fields, and overridable):
shapes:
Post:
identity: id
stored: true # table `posts`, columns in snake_case
id: id
authorId: id
body: text(1..5000)
createdAt: time
queries:
getPost:
input: { id: id }
returns: Post
allow: public
plain: read # optional, and only with a data module: no method to write
What is done with stored: depends on what the app adds. Each row is separate and optional.
| The app adds | What it gets | What it still owns |
|---|---|---|
A data module for the query tool it prefers: data-kysely, data-drizzle, data-sqlx, data-sql (a new module type, decision 0171) | Typed table definitions for that tool, generated from the stored models, and the mapping between a row and a model. A column name in a query is then checked by the compiler | Every query, written by hand in that tool |
| The schema check (part of any data module) | The build compares the stored models with the real schema and stops when they disagree, naming the model, the field and the column. The schema is read from a scratch database the app's own migrations were applied to, or from a schema file its migration tool writes | The migrations, written by hand with any tool |
Proposed migrations: duolith data propose | A plain SQL file with the change between the schema and the models, written into the app's migrations folder for the developer to read, edit and commit. It is never applied by the build, and there is no hidden record of state | Whether to use the proposal at all |
Plain operations: plain: create | read | update | delete | list on an operation of a stored model | That operation needs no method. Its query is generated from the data module's templates into a file the developer can read, and can replace (decision 0165, section 4) | Every operation that has real logic |
None of this is an ORM. There are no model objects with a save, no lazy loading, no query the developer cannot see, and no run-time layer between the method and the database. What is generated is types, and for a plain operation one query in a readable file.
One check applies to any migration, however it was written: it must be safe for the release that is still running. Dropping or renaming a column the running release reads is an error that gives the two-step way to do it. This is the rollout rule of decision 0168, and what work-stable-api does today by holding such a migration until someone allows it by name.
A name still cannot be mistyped (decision 0164, section 1a). Without a data module that guarantee stops at the method. With one, it reaches the column.
2. Starter domains: a working domain copied into the app
duolith add accounts copies a complete domain into the app: its domain file, its methods, its pages and its tests. From then on it is the app's code and can be changed freely. duolith add already copies a kit part in the same way (decision 0146), and this is what phx.gen.auth does in Phoenix.
| Starter | What it holds |
|---|---|
accounts | Sign up, sign in, sessions, sign out everywhere, email verification, password reset, and the rules self and admin. --with <provider> gives the thin version that trusts an identity provider's tokens |
payments | Customers, a subscription with its workflow (charge, retry, refund on failure), the signed webhook, and the fake provider for tests |
notifications | Preferences, email and push sending behind needs:, and the daily digest workflow |
- They are Plaza's. Plaza (decision 0170) is built by running these commands, so each starter is proved by the example and by Plaza's tests.
- Security-sensitive parts wrap audited libraries (decision 0171, section 2). Password hashing is never ours.
- A copy does not go stale silently. The lock file records which version of a starter was copied. When a later version fixes a security problem,
duolith auditfails and shows the change as a diff against the app's copy.duolith starters diff accountsshows any newer version the same way. Applying it is the developer's choice, because the code is theirs. - They do not require a data module. A starter's models are marked
stored:and its database work uses only plain operations. With a data module added, those are generated. Without one,duolith add accountswrites the handful of functions it needs as typed stubs and says so.
3. An admin, generated from the operations an admin is allowed to call
duolith add admin adds a generated set of pages for staff.
- There is nothing new to declare. The admin shows exactly the queries and commands whose
allow:rule admits an admin. A list comes from a query, a detail screen from a read, and a button from a command, with its form built from the command's input. - It is a client of the same API. Every action goes through the whole pipeline of decision 0165: the rule, the limits, validation and the audit trail. The admin can do nothing that a caller with the same role could not do with the typed client, so it adds no way round a rule.
- Who is an admin comes from a list held as a secret, never from a claim in a token or a row the app can write. This is the rule work-stable-api uses.
- It is off the public address where the platform allows, and can be placed on its own server with one line (decision 0169).
- Screens can be taken over one at a time. The pages are ordinary pages made of kit parts.
duolith admin eject <screen>copies one into the app, and the rest stay generated. - It needs no data module, because it calls operations and never the database.
This is deliberately less than Django's admin in one respect: it cannot edit a table that no operation exposes. To let staff correct a record, the app declares the operation (plain: update with allow: admin), which is one entry and leaves an audit record.
4. What a developer sees
| A developer who wants | Runs | Writes |
|---|---|---|
| Full control, as today | Nothing | Queries and migrations, in any tool |
| Typed tables and a check that models and schema agree | duolith add data-kysely | Queries and migrations, in that tool |
| No code for plain create, read, update, list | The same, plus plain: on those operations | Only the operations with logic |
| Accounts, payments or notifications that already work | duolith add accounts | Changes to them, if any |
| A screen for staff | duolith add admin | Nothing, until a screen needs to differ |
Stages
- The data module type,
stored:, typed tables and the schema check, for Postgres with Kysely and with sqlx. - Plain operations, proposed migrations and the migration safety check. Then
data-drizzleanddata-sql. - The
accountsstarter, thenpaymentsandnotifications, each taken from Plaza, withduolith starters diffand the audit check. - The admin: lists, details, commands, the admin list,
eject.
Alternatives considered
| Option | Why not |
|---|---|
| A built-in ORM that owns models, queries and migrations, as Django has | Mik turned it down. It hides the queries, ties every app to one way of working, and makes the framework responsible for a database layer |
| Leave all database code to the developer for good | Every app then rewrites the same create, read and list code, and nothing checks a model against its table. The check and the generated types cost the developer nothing when they are not added |
| Migrations generated and applied by the build | A change to production data that nobody read. A proposal the developer commits keeps a person in the path |
| Accounts as a hosted service or a closed package | An app cannot change what it does not own, and sign-in is where apps differ most. A copy with a tracked version gives ownership and still reports a security fix |
| An admin that edits tables directly | It would bypass every rule, limit and audit record the pipeline exists to apply |
Consequences
- A new module type, data, with its own tests: generated types match the models, the schema check reports each kind of mismatch, and a plain operation's query is parameterised and limited.
- The domain schema gains
stored:on a model andplain:with five values on an operation. Both are optional. (does:is already taken: a workflow step uses it to name an operation, decision 0167.) - New commands:
duolith data propose,duolith starters diff,duolith admin eject, and three new names forduolith add: a data module, a starter andadmin. modules.lock(decision 0171) also records the version of each starter that was copied.- New work packages 38 (data modules), 39 (starter domains) and 40 (the admin) in
docs/plan/server-roadmap.md. Plaza uses all three: it is built from the starters, on a data module, with the admin on. - The comparison in decision 0171, section 9, then has no missing rows. Two differences from Django remain on purpose: no ORM, and no editing of a table without an operation.
- New diagnostics, numbered when the briefs are written.