Repository navigation
Conversation
ditadi
force-pushed
the
stack/database-dev-flow/07-apps-init
branch
from
October 20, 2026 09:20
07b1748 to
7db9fa1
Compare
The DatabasePlugin is no longer hidden from `databricks apps init`. The template ships config/database/schema.ts in the app schema, and app.yaml sets APPKIT_DB_MIGRATE_ON_START=true for apps that select the plugin, so the deployed app applies its committed migrations on start. The CLI manifest renders only valueFrom entries, so the literal lives in app.yaml.tmpl. drizzle-kit stays out of the template and its lockfiles: `appkit db init` installs the pinned version when the app lacks it, so apps without the plugin do not get it. `appkit db verify` warns when .env points at a branch `appkit db init` did not set up for you, such as the deploy branch the scaffolded .env names until `db init` runs. The template's server exits 1 when startup fails, so a failed migration stops the app instead of leaving it up without its routes. The owner-mismatch error names the recovery for an app recreated with a new service principal: `databricks postgres delete-role --reassign-owned-to`. The plugin docs and the template README describe the flow end to end: `appkit db init` once after scaffolding, `appkit db migrate` while you develop, migrations on deploy with their per-migration transactions and lock limits, two-step changes for tables in use, rollback, existing apps, `appkit db verify --deployed -t <target>` in CI, and one owner per branch. The Lakebase docs start local development on a dev branch. The template's .gitignore skips config/database/*.bak, the copy of schema.ts that `appkit db introspect` keeps. Signed-off-by: ditadi <victordperd@gmail.com>
ditadi
force-pushed
the
stack/database-dev-flow/07-apps-init
branch
from
October 20, 2026 12:22
7db9fa1 to
81e2e8f
Compare
Contributor
🤖 AppKit PR bot🔬 Run evalsStart an eval for this PR from the evals-monitor app: Go to Evals Monitor → 📦 Try this PR's app templateScaffolds a new app from this PR's SDK build. Run it in any folder (requires the GitHub CLI — gh run download 41109406247 -R databricks/appkit -n appkit-template-0.89.0-pr.7de3087-stack-database-dev-flow-07-apps-init-675 -D appkit-pr-675 \
&& unzip -o "appkit-pr-675/appkit-template-0.89.0-pr.7de3087-stack-database-dev-flow-07-apps-init-675.zip" -d "appkit-pr-675" \
&& databricks apps init --template "appkit-pr-675"The template pins |
This was referenced Oct 20, 2026
Contributor
📦 Bundle size reportCompared against
|
| dist | raw | gzip |
|---|---|---|
| JS (runtime) | 1.4 MB (+21 KB) | 522 KB (+6.6 KB) |
| Type declarations | 482 KB (+4.0 KB) | 176 KB (+1.4 KB) |
| Source maps | 2.9 MB (+42 KB) | 970 KB (+12 KB) |
| Other | 11 KB | 3.7 KB |
| Total | 4.8 MB (+67 KB) | 1.6 MB (+20 KB) |
Per-entry composition (own code — deps external (as shipped))
| Entry | Initial (gz) | Lazy (gz) | Total (gz) | node_modules (min) | Own code (min) |
|---|---|---|---|---|---|
. |
106 KB | 2.5 KB | 108 KB | external | 343 KB |
./beta |
108 KB (+174 B) | 485 B | 108 KB (+174 B) | external | 324 KB (+474 B) |
./beta/database-tooling |
49 KB (+4.0 KB) | 0 B | 49 KB (+4.0 KB) | external | 145 KB (+12 KB) |
./testing |
45 KB | 32 KB | 77 KB | external | 223 KB |
./tsdown |
520 B | 0 B | 520 B | external | 813 B |
./type-generator |
26 KB | 0 B | 26 KB | external | 74 KB |
Chunks:
| Entry | Chunk | Load | Size (gz) |
|---|---|---|---|
. |
index.js |
initial | 101 KB |
. |
utils.js |
initial | 4.6 KB |
. |
remote-tunnel-manager.js |
lazy | 2.5 KB |
./beta |
beta.js |
initial | 88 KB |
./beta |
modular.js |
initial | 6.0 KB |
./beta |
stream-manager.js |
initial | 5.9 KB |
./beta |
service-context.js |
initial | 4.2 KB |
./beta |
databricks.js |
initial | 3.3 KB |
./beta |
client.js |
initial | 647 B |
./beta |
index.js |
initial | 20 B |
./beta |
supervisor-api.js |
lazy | 192 B |
./beta |
databricks.js |
lazy | 178 B |
./beta |
index.js |
lazy | 115 B |
./beta/database-tooling |
index.js |
initial | 49 KB |
./testing |
manifest.js |
initial | 32 KB |
./testing |
index.js |
initial | 10 KB |
./testing |
wide-event-emitter.js |
initial | 2.9 KB |
./testing |
index.js |
lazy | 28 KB |
./testing |
remote-tunnel-manager.js |
lazy | 2.5 KB |
./testing |
utils.js |
lazy | 1.8 KB |
./tsdown |
index.js |
initial | 520 B |
./type-generator |
index.js |
initial | 26 KB |
@databricks/appkit-ui
npm tarball (packed): 397 KB (+4 B) — gzipped download (dist + bin; excludes release-only docs/NOTICE).
| dist | raw | gzip |
|---|---|---|
| JS (runtime) | 429 KB | 147 KB |
| Type declarations | 267 KB | 98 KB (+1 B) |
| Source maps | 853 KB | 286 KB |
| CSS | 16 KB | 3.2 KB |
| Total | 1.5 MB | 534 KB (+1 B) |
Per-entry composition (consumer bundle — deps bundled, peerDeps external)
| Entry | Initial (gz) | Lazy (gz) | Total (gz) | node_modules (min) | Own code (min) |
|---|---|---|---|---|---|
./js |
5.3 KB | 49 KB | 55 KB | 208 KB | 14 KB |
./js/beta |
2.1 KB | 0 B | 2.1 KB | 0 B | 5.0 KB |
./react |
433 KB | 49 KB | 481 KB | 1.3 MB | 177 KB |
./react/beta |
4.9 KB | 0 B | 4.9 KB | 0 B | 12 KB |
Chunks:
| Entry | Chunk | Load | Size (gz) |
|---|---|---|---|
./js |
index.js |
initial | 5.2 KB |
./js |
chunk |
initial | 120 B |
./js |
apache-arrow |
lazy | 49 KB |
./js/beta |
beta.js |
initial | 2.1 KB |
./react |
index.js |
initial | 431 KB |
./react |
tslib |
initial | 2.1 KB |
./react |
apache-arrow |
lazy | 49 KB |
./react/beta |
beta.js |
initial | 4.9 KB |
Conflicts: template/_gitignore keeps both the introspect backup and the history lock entries. database.md keeps PR675's development workflow section and moves the beta note, the deploy-target check and the history lock from the merged side into it. The workflow text now matches the merged code: --schema none hands over no schema and reads no schema.ts, schema public is never handed over, session branches are bound to their user, and verify --deployed compares the deployed journal entries and SQL and fails when it cannot read them. Signed-off-by: ditadi <victordperd@gmail.com>
The GA Lakebase guide told every Lakebase app to run the beta `npx appkit db init --schema none`, without saying it is beta, and said that copied objects keep their owner and that --schema none leaves the schemas as they are. The database development flow is beta and hidden, and it is documented on the Database plugin page, so the Lakebase guide goes back to its main text. Signed-off-by: ditadi <victordperd@gmail.com>
PR675 removed hidden from the database manifest, so the generated beta barrel and the template manifest picked the plugin up, and showed appkit db in appkit --help. The database development flow stays hidden while it is beta: the manifest is hidden again, beta.ts exports database by hand because the generated barrel skips hidden plugins, the template manifest no longer offers the plugin, and appkit db is hidden from --help again. The project field keeps bundleIgnore. Signed-off-by: ditadi <victordperd@gmail.com>
Signed-off-by: ditadi <victordperd@gmail.com>
With a reference databricks.yml leaves unresolved, every branch counts as a deploy target and init refuses too, so the local verify warning sent you to a command that cannot help. The report now says whether the refusal covers every branch, and the warning then says which commands refuse and leaves out init. Signed-off-by: ditadi <victordperd@gmail.com>
…es a migration Signed-off-by: ditadi <victordperd@gmail.com>
Signed-off-by: ditadi <victordperd@gmail.com>
… branch refusesEveryBranch is now the guard's every-branch refusal text, not a flag. The warning prints it after the branch's own reason, so a .env on the default or a protected branch still names the reference and its file, and it lists introspect among the commands that refuse. Signed-off-by: ditadi <victordperd@gmail.com>
…ation checks verify --deployed reads the branch from variable-overrides.json and fails on a deployed migration the checkout does not commit. On a branch that takes no writes, migrate also regenerates shared/appkit-types/database.d.ts. Signed-off-by: ditadi <victordperd@gmail.com>
ditadi
added a commit
that referenced
this pull request
Oct 30, 2026
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>
…schema Redeploying an older commit applies nothing, and the startup check then fails when a table or column that commit declares is gone. A migration that drops or renames one ends rollbacks to the commits that need it, so the docs no longer promise that two-step changes keep every older commit starting. Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
A branch db init creates now starts with the app schema rebuilt from the committed migrations, or from the baseline introspect writes, so it holds no copied rows. --schema migrate keeps them. Existing apps with a schema.ts adopt their tables with init --schema introspect, because a plain init on a new branch drops tables the migrations do not create. Introspect reads the schema that schema.ts declares. Without schema.ts, init and introspect read schema app, so an app on public runs init --schema none and then introspect --schema-name public. Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
…ed migrations Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
…kebase-only recovery The hint for a schema another role owns must say first that two apps on one database each need their own schemaName, then give the delete-role recovery for a recreated app or a re-added resource, with the warning that it moves every object the role owns. It must not suggest ALTER OWNER, which fails with "must be able to SET ROLE" on a Lakebase service principal role. Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
…pps case first Schema "app" owned by another role has two causes, and the hint now orders them. Two apps on one database each need their own schemaName. Otherwise the app was recreated or its resource re-added, and Lakebase handed the objects to another role. No Postgres role can hand them back, because ALTER ... OWNER TO a service principal role fails with "must be able to SET ROLE", so the hint gives only the platform's delete-role --reassign-owned-to command, covers the re-add case where the owner is the remover's role, and warns that it moves every object the role owns and deletes the role. Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
…very for database Two apps on one database with the same schema are unsupported; each needs its own schemaName. A deploy succeeds 2 s after the process starts unless app.yaml declares a health_check, and then /health must answer within 300 s, which AppKit binds only after migrations. Classic compute stops the old process first, no-downtime compute keeps it serving, a crashed process is not restarted, and scale-to-zero apps rerun the start on every cold start. A start migrates only as the app's own service principal, so a local start or run-local never migrates, and a deploy start refuses an edited migration or a diverged history. A failed migration is repaired in the rows, never by editing the migration; a DATABRICKS_SUPERUSER role on the deploy branch reads and writes the service principal's rows, runs a batched backfill between an expand and a contract migration, and can cancel a stuck appkit-migrate session. The owner recovery drops ALTER OWNER, which fails with "must be able to SET ROLE", lists what the role owns first, and gives delete-role --reassign-owned-to. init decides from the branch's schema owner instead of APPKIT_DB_NEW_BRANCH, tags the copied journal until the rebuild finishes, and forks the branch the default databricks.yml target binds. Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
….yaml has health_check The template README no longer says init forks the project's default branch or that any new branch is rebuilt; init forks the branch the app deploys to and rebuilds the app schema when it still belongs to the copied service principal. It says the deployed app migrates only as its own service principal and that the deploy waits up to 300 s for /health. The app.yaml comment records why the health check is there, so nobody removes it and turns a failed migration into a deploy that passed. Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
# Conflicts: # docs/docs/plugins/database.md # packages/appkit/src/database/migrations/ownership.ts # packages/appkit/src/database/migrations/tests/ownership.test.ts
A start migrates only when PGUSER is set and equals DATABRICKS_CLIENT_ID. The database plugin docs and the template README said a local start never migrates because it is not a deployment. Say it as the identity rule instead, and that db init writes the developer's PGUSER, so a local start or run-local connects as them and skips. Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
The one owner per branch runbook listed only pg_class objects before the role delete. Use the inventory db init takes before a hand-off instead: every object the role owns in the current database through pg_shdepend and pg_identify_object, run in each database, plus what it owns or is granted in other databases and shared objects. Say that the delete also drops the role's memberships and grants, and to resolve anything unrelated to the app first. Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
…--schema clean after a keep Add three facts of the fork-copy rule to the database docs and the template README. A branch the same init run created is rebuilt even when its app schema was already yours. migrate, introspect and seed refuse an untouched copy as well as a tagged one. After keeping the copied rows, the schema is yours and appkit db init --schema clean removes them. Fold the two keep-copy paragraphs that the merge of the init layer left side by side into one. Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
# Conflicts: # docs/docs/plugins/database.md
Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
…nit's resolver Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: ditadi <victordperd@gmail.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🥞 Stacked PR (generated by Stack)
Use this link to review incremental changes.
Stacked on #674. The design is #677.
What did you change, and why?
The commands from #654 to #674 need template support and docs before the plugin can be offered in
databricks apps init. This PR adds what the template renders for an app that selects the plugin, and documents the development flow.It does not offer the plugin. The manifest keeps
hidden: true, andbeta.tsstill exportsdatabaseby hand because the generated beta barrel skips hidden plugins.template/appkit.plugins.jsondoes not list the plugin, andappkit dbstays hidden fromappkit --help. The earlier revision of this PR removedhidden: true, and this revision puts it back. Offering the plugin is a later, separate change.For an app that selects the plugin, the template now renders these files:
app.yamlsetsAPPKIT_DB_MIGRATE_ON_START=true, so the deployed app applies the committed migrations on start.config/database/schema.tssays to edit tables there and runnpx appkit db migrate.verify --deployedstep after the production deploy.For every app,
server/server.tsexits 1 whencreateAppfails, so a failed migration stops the app instead of leaving it up without routes._gitignoreskipsconfig/database/*.bak, the previousschema.tsthatintrospectkeeps. drizzle-kit is not a template dependency, becauseappkit db init(#672) installs it.This PR also makes these changes:
projectfield setsbundleIgnore, so the project goes to.envand gets nodatabricks.ymlvariable.databricks postgres delete-role <its role> --reassign-owned-to <new role>, run by someone with CAN MANAGE on the Lakebase project.appkit db verifywarns when.envpoints at a branchappkit db initdid not set up for you. While adatabricks.ymlreference is unresolved, the warning names it and leaves out the init advice.database.mdgets a Development workflow section under a note thatappkit dbis hidden and beta. It covers branch setup, the commands, the deploy guard, the history lock, changing tables in use, migrations on deploy, existing apps, rolling back, schema ownership,verify --deployedand CI. It warns that a new branch copies the default branch's rows, production data included.lakebase.md, to run the betanpx appkit db init --schema none. This revision drops that change, solakebase.mdmatches main.Review round, 2026-11-09:
initdefault, which schema introspect reads, and whatverify --deployedchecks.Fix round for fjakobs's review of #677, 2026-11-15:
delete-role --reassign-owned-towith a check of what the role owns, neverALTER ... OWNER TO(L503, L260).PGUSERidentity rule (L307), and what a deploy waits for per compute type with the 300 s health check (L350).app.yaml.tmplgains a comment on that.pg_cancel_backenditem).delete-role, the fork-copy rule, the fork source and the drizzle-kit install.How do you know it works?
verify.test.tsand the CLI'sverify.test.tscover the warning on the default branch and on a dev branch, each with an unresolved reference.ownership.test.tsasserts thedelete-rolehint.app.yaml.tmplwith Gotext/templatefor a database app and two others, and only the database app got the flag. That block is unchanged since../betanames as main, and./beta/database-toolingis the only new subpath.appkit --helpdoes not listdb.Review round, 2026-11-09: each fix has a failing-then-passing test in its PR, and every layer's appkit and shared tests ran against Postgres 14 after the sync. At the top of the stack,
pnpm build,pnpm test(6502 passed, 1 skipped),pnpm -r typecheck,pnpm check,pnpm knipandpnpm docs:buildpass.Fix round for fjakobs's review, 2026-11-15: each fix has a failing-then-passing test in its PR, and every layer's database, plugin and CLI tests ran against Postgres 17 after the sync. A throwaway Lakebase fork confirmed that the developer role can write the service principal's rows but cannot alter its tables. At the top of the stack,
pnpm test(6602 passed, 1 skipped),pnpm -r typecheck,pnpm buildandpnpm docs:buildpass, and oxlint and oxfmt are clean on every changed file.