[ditadi]

🥞 Stacked PR (generated by Stack)

Use this link to review incremental changes.

• stack/database-dev-flow/00-design [Files changed]
• stack/database-dev-flow/01-migrations-on-deploy [Files changed]
  • stack/database-dev-flow/02-default-app-schema [Files changed]
    • stack/database-dev-flow/03-db-migrate [Files changed]
      • stack/database-dev-flow/04-db-introspect [Files changed]
        • stack/database-dev-flow/05-db-init [Files changed]
          • stack/database-dev-flow/06-db-verify [Files changed]
            • stack/database-dev-flow/07-apps-init [Files changed] ← this PR
              • stack/database-dev-flow/08-db-check [Files changed]

---

Stacked on #674.

Summary

Offers the DatabasePlugin in databricks apps init, and documents the development flow end to end. Past npx appkit db init, a scaffolded app with the plugin needs no manual step to develop and deploy:

• appkit db init points .env at a Lakebase branch of your own and sets up its schema. It asks nothing.
• appkit db migrate writes and applies migrations as you change config/database/schema.ts.
• app.yaml sets APPKIT_DB_MIGRATE_ON_START=true, so the deployed app applies the committed migrations on start.
• appkit db verify checks your branch, and with --deployed -t <target> the deployed app.
• One owner per branch: the app's service principal owns the schema on the deploy branch.

Details

• The plugin manifest is no longer hidden, and neither are the appkit db commands in the CLI. The database export moves from beta.ts to the generated beta exports.
• Template changes:
  • app.yaml.tmpl sets APPKIT_DB_MIGRATE_ON_START=true when the plugin is selected. The CLI manifest renders only valueFrom entries, so the literal lives in the template. The block sits next to the .appEnv block, not inside it, because the template smoke test strips conditionals with regexes that do not nest.
  • server/server.ts exits 1 when startup fails, so a failed migration stops the app instead of leaving it up without routes.
  • config/database/schema.ts uses schema app.
  • appkit.plugins.json gets the database entry, with the postgres binding for branch and database.
  • README.md.tmpl gets a development-workflow section, a verify --deployed step after the production deploy, and config/database/ in the project structure.
  • _gitignore skips config/database/*.bak, the previous schema.ts that introspect keeps.
• drizzle-kit is not a template dependency. appkit db init (feat(appkit): add appkit db init, clean and seed #672) installs the version AppKit pins when the app lacks it. Apps without the plugin don't get it, and the template lockfiles are unchanged.
• appkit db verify warns when .env points at a branch appkit db init did not set up for you. Until databricks apps init runs db init itself, the scaffolded .env names the branch picked in its prompts, usually the deploy branch. This is a warning, not a finding, and the docs say to run npx appkit db init once after scaffolding. So this PR does not wait for that CLI change.
• The owner-mismatch error covers an app recreated with a new service principal. The old one still owns the schema, and someone with CAN MANAGE on the Lakebase project runs databricks postgres delete-role <old role> --reassign-owned-to <new role>.
• Plugin docs (database.md):
  • Set up your branch: no prompts, --dev, --session, --ttl, --schema and --yes, and the drizzle-kit install.
  • A caution: a new branch copies the default branch's rows, production data included. The developer role is a member of DATABRICKS_SUPERUSER, and CAN MANAGE on the project also allows deleting the deploy branch.
  • Migrations on deploy: the flag, one transaction per migration, the 5 s table-lock timeout with 3 tries, the 5 min migration-lock wait, and no migration on start against a developer branch.
  • Changing tables in use (two-step changes), existing apps, rolling back, the recreated-app recovery, verifying the deployed app, and CI.
• Lakebase docs (lakebase.md): local development starts on a dev branch with npx appkit db init --schema none. Developing against the deployed branch is a subsection.

Tests

• The verify tests cover the new warning: on the project's default branch, verify reports why the branch is not yours and still passes, and the CLI prints the warning.
• The ownership test asserts the delete-role --reassign-owned-to hint.
• I rendered app.yaml.tmpl with Go text/template for a database app, an analytics-only app and an app with no resources. Each output parses as YAML, and only the database app gets the flag. I rendered README.md.tmpl with and without the plugin.
• I checked the doc claims against the code of feat(appkit): apply committed database migrations on deploy start #654–feat(appkit): add appkit db verify #674: the init flags and branch choice, the migrate, clean, seed and introspect refusals, the lock limits, the warning on start for migrations the code does not commit, and verify --deployed.
• tools/check-template-deps.ts passes.
• Build, typecheck, lint and format, knip, generate:types and sync:template (no diff), and the docs build pass. The docs build's one broken-anchor warning is in custom-plugins, which this PR does not touch.
• The database tests pass against a local Postgres 14: 869 in appkit and 630 in the shared CLI.

[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 39422038318 -R databricks/appkit -n appkit-template-0.89.0-pr.cd46b9a-stack-database-dev-flow-07-apps-init-675 -D appkit-pr-675 \
  && unzip -o "appkit-pr-675/appkit-template-0.89.0-pr.cd46b9a-stack-database-dev-flow-07-apps-init-675.zip" -d "appkit-pr-675" \
  && databricks apps init --template "appkit-pr-675"

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.