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): 827 KB (-7 B) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist	raw	gzip
JS (runtime)	855 KB	298 KB
Type declarations	314 KB	108 KB (-9 B)
Source maps	1.7 MB	557 KB
Other	11 KB	3.7 KB
Total	2.8 MB	967 KB (-9 B)

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

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
.	87 KB	2.5 KB	90 KB	external	285 KB
./beta	48 KB	459 B	48 KB	external	140 KB
./type-generator	20 KB	0 B	20 KB	external	57 KB

Chunks:

Entry	Chunk	Load	Size (gz)
.	index.js	initial	83 KB
.	utils.js	initial	4.0 KB
.	remote-tunnel-manager.js	lazy	2.5 KB
./beta	beta.js	initial	32 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	431 B
./beta	client-options.js	initial	220 B
./beta	supervisor-api.js	lazy	194 B
./beta	databricks.js	lazy	142 B
./beta	index.js	lazy	123 B
./type-generator	index.js	initial	20 KB

@databricks/appkit-ui

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

dist	raw	gzip
JS (runtime)	362 KB	121 KB
Type declarations	209 KB	76 KB
Source maps	693 KB	227 KB
CSS	16 KB	3.3 KB
Total	1.3 MB	427 KB

Per-entry composition (consumer bundle — deps bundled, peerDeps external)

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
./js	4.3 KB	49 KB	54 KB	208 KB	12 KB
./js/beta	20 B	0 B	20 B	0 B	0 B
./react	429 KB	49 KB	478 KB	1.3 MB	168 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	4.2 KB
./js	chunk	initial	120 B
./js	apache-arrow	lazy	49 KB
./js/beta	beta.js	initial	20 B
./react	index.js	initial	427 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 31437286576 -R databricks/appkit -n appkit-template-0.57.0-pr.447eea0-stack-database-mvp-01-runtime-525 -D appkit-pr-525 \
  && unzip -o "appkit-pr-525/appkit-template-0.57.0-pr.447eea0-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 :)

[atilafassina]

I think here (and in other operations) we're using .returning() but it doesn't take into account if a column is private(), I think we'll need to abstract this away and avoid passing all columns to expect* methods. Wdyt?

[atilafassina]

thoughts about setting an offset max boundary as well here?
Maybe this is worth it as belt-and-suspenders protection?