feat(appkit): add the service-principal typed DatabasePlugin API

[ditadi]

Stack

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

Each PR targets the one above it, so the diff shown here is only the delta on top of #525. Review in order.

What

Turns the runtime from #525 into a plugin you can actually use. database({ schema }) publishes one typed client per table, plus transactions and parameterized SQL, and the existing typegen flow learns to derive the declarations that make all of it typed from the schema file alone.

This is the first PR in the series with an exported surface. The plugin runs as the app's service principal and registers no HTTP routes — generated CRUD arrives in the next PR, so everything here is reachable only from server code you write.

import { database, defineSchema, id, text, timestamp } from "@databricks/appkit/beta";

const schema = defineSchema((t) => {
  const notes = t.table("notes", {
    id: id(),
    body: text().notNull(),
    createdAt: timestamp().defaultNow(),
  });
  return { notes };
});

const appkit = await createApp({ plugins: [database({ schema })] });

const recent = await appkit.database.notes.order({ createdAt: "desc" }).limit(10).toArray();

await appkit.database.transaction(async (tx) => {
  const note = await tx.notes.create({ body: "hello" });
  await tx.sql`insert into audit (note_id) values (${note.id})`;
});

Changes

The plugin (plugins/database/)

• database({ schema }) binds one plugin instance to one finalized schema. lifecycle.ts owns setup: it validates the schema, builds the Lakebase pool, and publishes the export surface only once it is ready. Setup is single-flight, and a failure ends the pool rather than leaving a half-open plugin.
• Each table gets an EntityClient with a chainable read side — where, order, select, include, limit, offset, terminated by toArray, first, find, or count — and the keyed writes create, update, upsert, and delete. Every call goes through the DataPath from feat(appkit): add the database runtime and harden its schema builder #525, so the bounds, the parameterization, and the private-column projection hold here by construction.
• transaction(cb) hands the callback a client bound to that transaction; the tagged sql template is available both at the top level and inside a transaction, and interpolates values only.
• Reads and writes carry different interceptor policies (defaults.ts): neither retries, and mutations are never cached.

Errors (database/errors.ts)

DatabasePluginError maps a small closed set of categories onto stable status codes and client messages. A driver error never reaches the caller: it is classified, and the original is logged with its SQLSTATE before the safe error replaces it. The same is true for schema-validation and setup failures, so an operator can diagnose what the client is deliberately not shown.

Schema-derived types (type-generator/database/)

walk-schema.ts walks a finalized schema and generate.ts renders it into appkit-types/database.d.ts, which augments the DatabaseRegistry interface. That is what makes appkit.database.notes know its own columns, filters, and relations. The generator loads the schema file through jiti (pinned at 2.6.1), so a TypeScript schema needs no build step first.

It is wired into both existing entry points — the Vite plugin regenerates on change during development, and appkit generate-types emits it in CI — following the same shape the analytics and serving generators already use.

Exports

defineSchema, the column builders, and database are exported from @databricks/appkit/beta; DatabaseRegistry is exported from the root so the generated declaration file can augment it.

Verification

• pnpm vitest run — 4057 passing, 1 skipped; the new suites cover the plugin lifecycle, the entity client, the generated types, and the schema walker
• pnpm -r typecheck — clean across all packages
• pnpm run generate:types, pnpm run sync:template, and pnpm run docs:build produce no drift
• pnpm install --frozen-lockfile — jiti adds 3 lines to the lockfile and nothing else