Skip to content

docs: design 001, database development flow - #677

Open
ditadi wants to merge 8 commits into
mainfrom
stack/database-dev-flow/00-design
Open

ditadi wants to merge 8 commits into
mainfrom
stack/database-dev-flow/00-design

Conversation

@ditadi

@ditadi ditadi commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

🥞 Stacked PR (generated by Stack)

Use this link to review incremental changes.


What did you change, and why?

The DatabasePlugin reads tables but never creates them. Getting from databricks apps init to a deployed table today takes hand-run SQL, grants and console steps on the branch the app deploys to.

This PR adds design 001, Database development flow, as designs/001_DatabaseDevelopmentFlow.md. Comments and edits happen in the Google Doc, and changes there are synced to this file. The rest of this stack implements the design: #654, #655, #666, #670, #672, #674, #675 and #678.

This revision matches the doc to the corrected stack. The doc now says that:

  • the tooling ships as @databricks/appkit/beta/database-tooling, which is beta and internal to the AppKit CLI
  • migrate, introspect, clean and init hold config/database/.appkit-db.lock, and seed, verify, check, clean --delete-branch and init --schema none take no lock
  • init --schema none hands off nothing, and schema public is never handed off
  • the deploy guard reads each target with and without variable-overrides.json, and an unresolved branch or database reference refuses every write
  • introspect keeps .private() on declared columns, writes new columns private, and refuses a schema.ts that does not load or a foreign key it does not declare
  • verify --deployed compares the committed migrations with the source snapshot of the active deployment, and fails when it cannot read that snapshot
  • appkit db check fails on a snapshot file that is not a drizzle-kit snapshot
  • migrations log one line per run, with no span and no metric
  • feat(appkit): add template and docs for the database development flow #675 keeps the plugin hidden: true and appkit db hidden from appkit --help, and offering the plugin in apps init is a later, separate change

How do you know it works?

Docs only. A review checked each changed statement against the code of #654 to #678.

Signed-off-by: ditadi <victordperd@gmail.com>
… 001

Signed-off-by: ditadi <victordperd@gmail.com>
@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

🤖 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 41109402593 -R databricks/appkit -n appkit-template-0.89.0-pr.635ba31-stack-database-dev-flow-00-design-677 -D appkit-pr-677 \
  && unzip -o "appkit-pr-677/appkit-template-0.89.0-pr.635ba31-stack-database-dev-flow-00-design-677.zip" -d "appkit-pr-677" \
  && databricks apps init --template "appkit-pr-677"

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.

Signed-off-by: ditadi <victordperd@gmail.com>
@ditadi
ditadi requested a review from a team as a code owner October 26, 2026 02:04
@ditadi
ditadi requested a review from MarioCadenas October 26, 2026 02:04
ditadi and others added 4 commits October 30, 2026 10:44
The design doc promised behavior the corrected stack does not ship. It
now describes what the code does:

- The tooling export is @databricks/appkit/beta/database-tooling, beta
  and internal to the AppKit CLI.
- migrate, introspect, clean and init hold config/database/.appkit-db.lock.
  init holds one lock for its whole run, and init --schema none, seed,
  verify and clean --delete-branch take none. The doc says how to
  recover a stale lock file.
- init --schema none hands off nothing, and schema public is never
  handed off.
- Values in variable-overrides.json count for the deploy boundary, and
  an unresolved branch or database reference refuses every write.
- Introspect keeps .private() on declared columns, writes new columns
  private, and refuses a schema.ts that does not load or a foreign key
  it does not declare.
- verify --deployed compares the committed migrations with the source
  snapshot of the active deployment, and fails when it cannot read it.
- Migrations log one line per run. There is no span and no metric.
- #675 keeps the plugin and appkit db hidden. A reveal is a later,
  separate change.

The appkit db check section stays as it is until #678 settles.

Signed-off-by: ditadi <victordperd@gmail.com>
…he stack code

Signed-off-by: ditadi <victordperd@gmail.com>
… and prompts

Apply the review of the design doc. The pooler refusal belongs to migrate on start, the migrator reconciles without the lock before it takes it, the deploy guard reads each target with and without variable-overrides.json, and init asks only for --schema clean and an ambiguous rename. The reveal also moves the database export into the generated barrel, check refuses a file that is not a drizzle-kit snapshot, and the project is not a databricks.yml variable.

Signed-off-by: ditadi <victordperd@gmail.com>
@ditadi
ditadi requested a review from fjakobs November 1, 2026 23:27

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant