[ditadi]

What changed, and why?

The original design described an earlier proposal that no longer matched the implemented database-operation stack. This updates designs/002_DatabaseRouteOperations.md to the current author experience and makes this existing design PR the first layer, before #687.

• database() discovers conventional routes; routes: false disables HTTP, and an explicit registry supports custom layouts. Standard builds include the compiled registry automatically.
• Operations require stable explicit names. An omitted input schema means no parameters: useDatabaseQuery("alerts.queue"), databaseApi.execute(name), and mutate() work without empty objects. Parameterized operations require their declared Zod input.
• Operations declare no entity, and nothing infers a response from a table. An omitted output schema means no body: undefined answers 204, null on GET, PATCH, or PUT answers 404, and any other value answers 500 without being sent. An operation that answers data declares an output schema, which is also its public projection; .private() does not filter it.
• States that every policy callback, the resource lookup included, receives the verified actor.
• Documents verified actors, required policies, service-principal database access, safe field errors, transactions and concurrency rules, generated contracts, development watching, and source-less production packaging.
• Records dependent queries with skipToken, mutation identity across name/session changes, automatic query refresh, and unknown write outcomes.
• Removes stale approval gates and unsupported reload/CLI promises. Separates repository validation from the live Apps checks still needed before release.

Validation

Reviewed the design against the runtime, metadata validation, identity resolver, generator, registry loader, client, hooks, and current database guide. Markdown fences, source references, and whitespace checks pass.

Review feedback removed entity and the output defaults and documented the actor in policy lookups. #688, #689, #690, and #692 each gained one commit for it, and #687 and #691 were rebased unchanged. At the stack tip, pnpm build, pnpm docs:build, pnpm -r typecheck, pnpm check, knip, 840 database and type-generator tests, the playground smoke test, and the source-less bundle check pass.

Knip on the design layer's unchanged baseline reports the same findings as with the revised document: packages/appkit/bin/appkit.js and five unused development dependencies (esbuild, ora, zod, @types/react-dom, react-dom). The documentation commit bypasses that existing hook failure; no dependency or runtime change is included.

The AML evaluation app remains local and ignored, and is excluded from every PR. Live Apps identity/proxy behavior was not exercised by this documentation update.

Stack

Bottom to top: #683 (design) → #687 → #688 → #689 → #690 → #691 → #692.

Base: main. Next: #687, lifecycle/serializer removal. Design 001 and its migration chain remain separate: #677.

[github-actions]

🤖 AppKit PR bot

🔬 Run evals

Start an eval for this PR from the evals-monitor app: Go to Evals Monitor →

📦 Try this PR's app template

Scaffolds a new app from this PR's SDK build. Run it in any folder (requires the GitHub CLI — gh auth login — and the Databricks CLI):

gh run download 41903371881 -R databricks/appkit -n appkit-template-0.90.0-pr.c0d140f-victor-ditadi-data-stack-database-route-blocks-00-design-683 -D appkit-pr-683 \
  && unzip -o "appkit-pr-683/appkit-template-0.90.0-pr.c0d140f-victor-ditadi-data-stack-database-route-blocks-00-design-683.zip" -d "appkit-pr-683" \
  && databricks apps init --template "appkit-pr-683"

The template pins @databricks/appkit and @databricks/appkit-ui to tarballs built from this branch, so the scaffolded app runs against this PR's code.