Skip to content

feat(appkit): default defineSchema tables to the app schema - #655

Draft
ditadi wants to merge 14 commits into
stack/database-dev-flow/01-migrations-on-deployfrom
stack/database-dev-flow/02-default-app-schema
Draft

ditadi wants to merge 14 commits into
stack/database-dev-flow/01-migrations-on-deployfrom
stack/database-dev-flow/02-default-app-schema

Conversation

@ditadi

@ditadi ditadi commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

🥞 Stacked PR (generated by Stack)

Use this link to review incremental changes.


Stacked on #654. The design is #677.

What did you change, and why?

On Lakebase, the deployed app's service principal has no CREATE on public, but it can create and own a schema of its own. #654 applies migrations on start as that service principal, so with public as the default the first deploy would fail until someone ran a grant by hand.

  • defineSchema() without a schemaName puts its tables in the Postgres schema app. The service principal creates app on its first start and owns everything in it, including the migration journal. DEFAULT_SCHEMA_NAME in define-schema.ts is the only place the default is set.
  • An explicit { schemaName: "public" } still produces unqualified SQL (pgTable and pgEnum).
  • Beta apps whose tables are in public now look in app and fail setup. When every missing table exists in public, the error says so and shows { schemaName: "public" }. It leaves out the usual advice to commit migrations, which would create a second, empty copy in app.
  • A 42501 while migrating into public gets its own hint. It says to grant CREATE ON SCHEMA public to the service principal, or to use the default app.
  • The plugin docs explain the default, say each app needs its own schema, and cover upgrading an app with tables in public.
  • The dev-playground passes { schemaName: "public" }, because its tables were created by hand in public.

Apps that name their schema are unchanged, and apps on the old default get an error that says what to change. This revision only merges the corrected #654 and current main. The diff of this PR is unchanged.

Review round, 2026-11-09:

  • With APPKIT_DB_MIGRATE_ON_START=true, startup refuses to apply migrations when defineSchema() was given no schemaName, none of the declared tables exist in app, and some exist in public. Before, the first migration created empty copies in app and the app served them. The lookup lives in database/migrations/tables-left-in-public.ts, shared with the startup check's advice.
  • The 42501 hint for schema public claims missing CREATE only when has_schema_privilege says so; otherwise it names the table ownership problem.

Fix round for fjakobs's review of #677, 2026-11-15:

  • The public ownership hint stops advising ALTER TABLE ... OWNER TO, which no role can do for the app's service principal (L503).

How do you know it works?

  • define-schema.test.ts checks that tables and enums go to app by default and stay unqualified with an explicit public.
  • schema-check.test.ts checks that the error names public when every missing table is there, and keeps the usual advice when only some are there or the declared schema is public.
  • ownership.test.ts checks the public hint. migrate-on-start.test.ts uses the default, so it checks that the journal goes to app.
  • At this PR's head, the history tests passed, and a repeated start against a local PostgreSQL 14 applied nothing the second time. The full vitest suite, a clean build, the docs build and typecheck passed at the top of the stack (feat(appkit): add appkit db check #678), which contains this PR, and its packed tarballs export the same root and ./beta names as main. CI runs the full suite on this PR.
  • This revision was not run against a real Lakebase workspace.

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 knip and pnpm docs:build pass.

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 build and pnpm docs:build pass, and oxlint and oxfmt are clean on every changed file.

@ditadi
ditadi force-pushed the stack/database-dev-flow/02-default-app-schema branch from 59db797 to f8a437d Compare October 12, 2026 21:32
@ditadi
ditadi added this pull request to stack #667 October 13, 2026 13:34
@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

📦 Bundle size report

Compared against bundle-size-baseline.json (main).

@databricks/appkit

npm tarball (packed): 1.3 MB (+26 KB) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist raw gzip
JS (runtime) 1.3 MB (+30 KB) 469 KB (+11 KB)
Type declarations 464 KB (+59 B) 168 KB (+28 B)
Source maps 2.6 MB (+54 KB) 874 KB (+18 KB)
Other 11 KB 3.7 KB
Total 4.3 MB (+84 KB) 1.5 MB (+29 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 (-1 B) 2.5 KB (+1 B) 108 KB external 343 KB
./beta 108 KB (+5.1 KB) 485 B 108 KB (+5.1 KB) external 323 KB (+14 KB)
./testing 45 KB (+1 B) 32 KB (-3 B) 77 KB (-2 B) 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
./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

@github-actions

github-actions Bot commented Oct 13, 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 41109404652 -R databricks/appkit -n appkit-template-0.89.0-pr.6cf499b-stack-database-dev-flow-02-default-app-schema-655 -D appkit-pr-655 \
  && unzip -o "appkit-pr-655/appkit-template-0.89.0-pr.6cf499b-stack-database-dev-flow-02-default-app-schema-655.zip" -d "appkit-pr-655" \
  && databricks apps init --template "appkit-pr-655"

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.

@ditadi
ditadi force-pushed the stack/database-dev-flow/02-default-app-schema branch from f8a437d to ec8da9c Compare October 19, 2026 12:25
defineSchema() without a schemaName now places its tables in the Postgres
schema "app" instead of "public". The deployed app's service principal can
create and own a schema of its own, but has no CREATE on public, so tables
in public could not be migrated on deploy without a manual grant.

Signed-off-by: ditadi <victordperd@gmail.com>
An app whose tables predate the app default fails setup with advice to
commit migrations, which would create an empty copy in app. Name the
public tables instead, give public its own ownership hint, document one
schema per app, and pin the dev-playground to public.

Signed-off-by: ditadi <victordperd@gmail.com>
ditadi and others added 12 commits October 30, 2026 15:10
Signed-off-by: ditadi <victordperd@gmail.com>
…re still in public

An app upgraded from a release that put tables in public, still on the default
schema app, has public.notes with its rows and no app.notes. migrateOnStart
applies the committed migrations before assertSchemaMatchesDatabase runs, so the
first migration creates an empty app.notes, the check then passes, and the app
serves the empty table. The advice about tables in public never shows.

Pin the refusal: with the default schema, none of the declared tables in app and
some in public, startup fails before anything is applied. An explicit
schemaName "app", or a declared table already in app, still migrates.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
…adow tables in public

An app upgraded from a release that put tables in public, left on the default
schema app, has public.notes with its rows and no app.notes. migrateOnStart ran
before assertSchemaMatchesDatabase, so the first committed migration created an
empty app.notes, the check passed, and the app served the empty table. The
"tables are in public" advice only showed when the check failed.

Before applying anything, migrateOnStart now asks the catalog where the declared
tables are. When defineSchema() was not told a schemaName, none of the tables
exist in app and some exist in public, startup fails with the advice: keep them
in public with { schemaName: "public" }, move them (ALTER TABLE ... SET SCHEMA),
or name schemaName "app" explicitly when the tables in public are another app's.
defineSchema() records whether schemaName was explicit as a symbol-keyed
property; the public API is unchanged.

The lookup and the advice live in database/migrations/tables-left-in-public.ts,
exported as locateTables, detectTablesLeftInPublic, keepInPublicAdvice and the pg
adapter catalogSqlOf, so the startup check and the CLI can share one query.
assertSchemaMatchesDatabase's inPublicInstead now uses the same lookup.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
…nly when it is missing

On SQLSTATE 42501 for schema public, ownershipHint said the app's role has no
CREATE on public whenever another role owns public, which is always. An app that
already holds CREATE and fails on a table another role owns got told to grant a
privilege it has. Pin that with CREATE granted the hint names the object's owner
as the fault and how to transfer it, and that without CREATE the grant advice stays.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
…privilege

On SQLSTATE 42501 for schema public, ownershipHint claimed the app's role has no
CREATE on public whenever another role owns public, which is always the case. An
app that already holds CREATE and failed on a table another role owns was told to
grant a privilege it has.

schemaOwnership now also reads has_schema_privilege(current_user, schema, 'CREATE')
from pg_catalog, null when the schema does not exist. The hint claims missing
CREATE only when it is missing; with CREATE granted it names an object another
role owns as the fault and how to transfer it (ALTER TABLE ... OWNER TO).

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
… public

The "Apps with tables in public" section described the failing check but not the
migrate-on-start refusal added for the implicit default schema. Describe when
startup refuses, why, and the three ways out: schemaName "public", moving the
tables with ALTER TABLE ... SET SCHEMA, or an explicit schemaName "app".

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
The test proved the allowed case by creating schema app on the scratch database
and left it there. The first pg test already finds a table in a real target
schema, and the unit test covers a table already in app, so the pg test keeps
only the refusal against a real catalog.

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>
On Lakebase no Postgres role can hand an object to the app's service
principal, so the hint for a migration that trips on another role's
object in public must say so and point at the default schema.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
Measured on Lakebase: ALTER ... OWNER TO <sp> fails with "must be able
to SET ROLE", so no Postgres role can transfer an object to the app's
service principal. The hint for a migration that trips on another
role's object in public now says so and points at the default schema
app, which the app creates and owns.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
# Conflicts:
#	packages/appkit/src/database/migrations/ownership.ts
#	packages/appkit/src/database/migrations/tests/ownership.test.ts
#	packages/appkit/src/plugins/database/schema-check.ts
#	packages/appkit/src/plugins/database/tests/schema-check.test.ts
# Conflicts:
#	packages/appkit/src/database/migrations/ownership.ts

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