[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]
              • stack/database-dev-flow/08-db-check [Files changed] ← this PR

---

Stacked on #675.

Summary

Adds appkit db check, an offline check of the committed migrations for CI. It reads only the checkout, so a pull request can run it without Databricks or Lakebase credentials. It fails when:

• config/database/schema.ts changed and no committed migration has the change;
• the journal lists a migration generated before the one ahead of it, which a branch that ran the newer one never runs;
• a snapshot does not follow the one before it, which happens when two migrations were generated from one snapshot on parallel git branches;
• a migration's .sql or snapshot is not committed, or a .sql is not in the journal.

Each finding names its fix, and the command exits 1 on any of them.

Details

• The schema comparison reuses the diff appkit db migrate runs against the latest snapshot, now diffSchema in migrations.ts. So check fails exactly when migrate would write a migration. An ambiguous rename counts as a change, and nothing prompts.
• The journal check also fails an entry whose idx is not its position, since drizzle-kit names snapshots by idx.
• The schema is compared only when the latest snapshot is committed. Without it, the missing snapshot is the finding.
• Two pull requests that both add 0001_migration conflict in git first. The check catches a resolution that keeps both. The fix it names takes the base branch's migrations, then runs appkit db clean and appkit db migrate. The clean is there because the developer's branch already ran the old migration.
• Docs: db check joins the commands table. The CI section runs it on every pull request and explains the conflict. The template README names it.

Tests

• The runCheck tests generate real migration history with drizzle-kit and a real schema.ts, with every Databricks and Lakebase call throwing. They cover:
  • a sound history, and no migrations with no tables;
  • a schema.ts change without its migration, with and without committed migrations, and an ambiguous column rename;
  • a merge that keeps two migrations generated from one snapshot;
  • a when out of order, and an idx that is not its position;
  • an uncommitted .sql and snapshot, and an unlisted .sql.
• The CLI tests cover the pass and fail output, the exit code, and errors.
• Against the dev-playground, which declares tables and commits no migration, check fails with the schema finding.
• Build, typecheck, lint and format, and knip pass. The database tests pass against a local Postgres 14: 879 in appkit and 635 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 39421984615 -R databricks/appkit -n appkit-template-0.89.0-pr.fc69bde-stack-database-dev-flow-08-db-check-678 -D appkit-pr-678 \
  && unzip -o "appkit-pr-678/appkit-template-0.89.0-pr.fc69bde-stack-database-dev-flow-08-db-check-678.zip" -d "appkit-pr-678" \
  && databricks apps init --template "appkit-pr-678"

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.