feat(appkit): add the database runtime and harden its schema builder

[ditadi]

Stack

• #525 — the database runtime ← you are here
  • #526 — the typed plugin API
    • #527 — generated reads
      • #528 — mutations and hooks
        • #529 — playground example

Each PR targets the one above it. This one is the base of the stack, so its diff is against main.

What

Rebuilds packages/appkit/src/database/ into a foundation the upcoming DatabasePlugin can be built on: the schema builder now rejects the declarations it used to accept silently, and a new runtime layer gives every future database API a single, bounded path to PostgreSQL.

Nothing here is exported. Neither index.ts nor beta.ts reaches into database/ today, so this PR changes no public API and no generated types or docs — it is groundwork, reviewable on its own, and the plugin that consumes it lands in the following PRs.

Changes

A backend-neutral execution boundary (database/runtime/)

DataPath is the only interface the layers above will talk to — select, findOne, count, insert, update, upsert, delete, raw, and transaction. Its field names are schema keys that an adapter resolves through column metadata, never caller-supplied SQL identifiers. The Drizzle adapter and the translate module behind it hold the guarantees:

• Identifiers come from metadata and every operand is parameterized. Tagged raw SQL interpolates values only; a structural interpolation is rejected.
• Reads are bounded by default. A collection read without an explicit limit takes DEFAULT_LIMIT, explicit bounds are validated against MAX_LIMIT, and to-many includes are bounded the same way.
• The default projection is private-safe, so a column marked .private() never leaves the database unless it is asked for by name.
• Filters go through one operator matrix keyed by column value kind. in lists are bounded, an empty in has deterministic semantics rather than matching everything, null matching is only ever is: null, and an empty and/or group is rejected instead of silently widening the query.
• Row counts are invariants, not hopes: insert and upsert must produce exactly one row, update and delete accept zero or one and reject many.
• A table handle from a different schema is rejected, and driver errors are raised without retaining their details.

Schema-builder invariants

The builder previously accepted declarations that could not hold at runtime. It now refuses them at declaration time:

• Foreign keys inherit the target's full storage contract, resolve through chains independently of declaration order, and reject cycles that never reach a concrete type. A target must be a primary key or unique; unknown, cross-schema, and omitted targets are refused. SET NULL requires a nullable column and SET DEFAULT a compatible local default. A generated identity mirrors to non-generated integer storage on the referencing side.
• Relations reject forward and reverse collisions with column names, reject a second foreign key from one table to the same target, keep reverse relations to-many even when the foreign key is unique, and expose only the forward edge of a self-reference. The resulting objects are frozen.
• Columns allow one explicit default mode, accept referential actions only where a foreign key exists, validate varchar lengths and enum declarations, record literal defaults rather than synthesizing them, and restrict the defaultNow/defaultRandom helpers to the timestamp and UUID kinds.
• defineSchema requires each declared table exactly once, rejects aliases and duplicate handles, validates literal defaults against both storage and enum values, refuses a table that would overwrite Drizzle relation metadata, and no longer leaves handles half-finalized when validation fails partway through.

Removals

• .owner() and the isOwner metadata it set are gone. They described row ownership for an RLS story this runtime does not implement, and nothing in the repository called them.
• contract/column-info.ts, contract/relation.ts, and schema-builder/private.ts were folded into the modules that own their data, which narrows the internal barrel accordingly.

Verification

• pnpm vitest run — 3966 passing, 1 skipped
• pnpm -r typecheck — clean across all packages
• pnpm run generate:types, pnpm run sync:template, and pnpm run docs:build produce no drift, as expected for a change with no exported surface
• Rebased onto main at v0.57.0

[github-actions]

📦 Bundle size report

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

@databricks/appkit

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

dist	raw	gzip
JS (runtime)	936 KB (+30 KB)	325 KB (+8.5 KB)
Type declarations	345 KB (+1.2 KB)	120 KB (+499 B)
Source maps	1.8 MB (+58 KB)	610 KB (+14 KB)
Other	11 KB	3.7 KB
Total	3.1 MB (+89 KB)	1.0 MB (+23 KB)

Per-entry composition (own code — deps external (as shipped))

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
.	93 KB (+4.9 KB)	2.5 KB	96 KB (+4.9 KB)	external	306 KB (+17 KB)
./beta	55 KB (+5.0 KB)	457 B	56 KB (+5.0 KB)	external	166 KB (+18 KB)
./testing	17 KB	0 B	17 KB	external	50 KB
./tsdown	520 B	0 B	520 B	external	813 B
./type-generator	21 KB	0 B	21 KB	external	61 KB

Chunks:

Entry	Chunk	Load	Size (gz)
.	index.js	initial	89 KB
.	utils.js	initial	4.0 KB
.	remote-tunnel-manager.js	lazy	2.5 KB
./beta	beta.js	initial	39 KB
./beta	stream-manager.js	initial	5.8 KB
./beta	wide-event-emitter.js	initial	3.2 KB
./beta	databricks.js	initial	3.0 KB
./beta	configuration.js	initial	2.1 KB
./beta	service-context.js	initial	1.3 KB
./beta	client.js	initial	434 B
./beta	client-options.js	initial	220 B
./beta	supervisor-api.js	lazy	192 B
./beta	databricks.js	lazy	142 B
./beta	index.js	lazy	123 B
./testing	index.js	initial	17 KB
./tsdown	index.js	initial	520 B
./type-generator	index.js	initial	21 KB

@databricks/appkit-ui

npm tarball (packed): 348 KB (+5 B) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist	raw	gzip
JS (runtime)	394 KB	132 KB
Type declarations	228 KB (+32 B)	83 KB (+8 B)
Source maps	764 KB	252 KB
CSS	16 KB	3.2 KB
Total	1.4 MB (+32 B)	471 KB (+8 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	20 B	0 B	20 B	0 B	0 B
./react	432 KB	49 KB	481 KB	1.3 MB	177 KB
./react/beta	1.0 KB	0 B	1.0 KB	0 B	1.9 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	20 B
./react	index.js	initial	430 KB
./react	tslib	initial	2.1 KB
./react	apache-arrow	lazy	49 KB
./react/beta	beta.js	initial	1.0 KB

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[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 32745542461 -R databricks/appkit -n appkit-template-0.64.0-pr.8fee458-stack-database-mvp-01-runtime-525 -D appkit-pr-525 \
  && unzip -o "appkit-pr-525/appkit-template-0.64.0-pr.8fee458-stack-database-mvp-01-runtime-525.zip" -d "appkit-pr-525" \
  && databricks apps init --template "appkit-pr-525"

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.

[atilafassina]

Awesome work. just 2 question/suggestions before approving :)