docs(database): tighten plugin guide and CLAUDE.md; small public-API polish

Author: ditadi

CLAUDE.md

@@ -267,6 +267,20 @@ const result = await pool.query('SELECT * FROM users');
 **ORM Integration:**
 Works with Drizzle, Sequelize, TypeORM - see the `@databricks/lakebase` README and `apps/dev-playground/server/lakebase-examples/` for examples.
 
+### Database Plugin
+
+Application-level layer over Lakebase (beta). Owns schema declaration, type generation, drift detection, auto-mounted CRUD routes, and a typed `db` browser client — all driven by `config/database/schema.ts`. See [`docs/docs/plugins/database.md`](./docs/docs/plugins/database.md) for the full guide.
+
+```typescript
+import { createApp, server } from '@databricks/appkit';
+import { database } from '@databricks/appkit/beta';
+
+const app = await createApp({ plugins: [server(), database()] });
+const cases = await app.database.cases.where({ status: 'New' }).limit(50).toArray();
+```
+
+CLI: `npx appkit db init | introspect | migration generate <name> | migrate up | rls <entity> <spec> | seed | setup:dev | types generate | verify`.
+
 ### Frontend-Backend Interaction
 
 ```

docs/docs/api/appkit/Interface.DataPath.md

@@ -120,8 +120,8 @@ raw<T>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
 ```
 
 Tagged-template SQL escape hatch. Values are bound as parameters; column
-and identifier interpolation is intentionally not supported here — use
-`getDrizzle()` from the plugin's exports for that case.
+and identifier interpolation is intentionally not supported here — drop
+to `appkit.database.getPool().query(...)` if you need that.
 
 #### Type Parameters
 

docs/docs/plugins/database.md

@@ -4,13 +4,20 @@ sidebar_position: 4
 
 # Database plugin (beta)
 
+<!-- AUTO-GENERATED: stability-banner-start -->
+:::warning Beta plugin
+This plugin is currently **beta**. APIs may change between minor releases. Import from `@databricks/appkit/beta`. See [Plugin Stability Tiers](./stability.md).
+:::
+<!-- AUTO-GENERATED: stability-banner-end -->
+
 The **database plugin** is the application-level layer over Lakebase. It owns
 schema declaration, type generation, drift detection, auto-mounted CRUD
 routes, and a typed `db` browser client — all driven by a single
 `config/database/schema.ts`.
 
 > **Beta:** the manifest declares `stability: "beta"`. The CLI and runtime
 > APIs are stable enough for non-critical workloads but may change before GA.
+> See [Known limitations](#known-limitations-beta) for what is not yet covered.
 
 **Key features:**
 
@@ -59,7 +66,7 @@ export default defineSchema(({ table }) => ({
 
 ## Auto-mounted routes
 
-Each table gets six conventional routes plus a metadata pair:
+Each table gets six conventional routes plus discovery and health metadata:
 
 | Method | Path                            | Purpose                            |
 |--------|----------------------------------|------------------------------------|
@@ -69,7 +76,6 @@ Each table gets six conventional routes plus a metadata pair:
 | POST   | `/api/database/<e>`              | Create a row (upsert via `Prefer`) |
 | PATCH  | `/api/database/<e>/:id`          | Update by primary key              |
 | DELETE | `/api/database/<e>/:id`          | Delete by primary key              |
-| GET    | `/api/database/<e>/_columns`     | Public column metadata for forms   |
 | GET    | `/api/database/_entities`        | Discovery — list of entities       |
 | GET    | `/api/database/_healthz`         | Readiness probe (`SELECT 1`)       |
 
@@ -82,7 +88,6 @@ database({
     user: {
       list: "service",   // service-principal
       delete: false,     // disable the DELETE route entirely
-      columns: "service" // override the metadata gate
     },
   },
 });
@@ -91,13 +96,16 @@ database({
 ## CLI lifecycle
 
 ```bash
-npx appkit db init                 # one-command Lakebase onboarding
-npx appkit db generate <name>      # scaffold a table (greenfield)
-npx appkit db introspect           # pull existing schema (brownfield)
-npx appkit db migration generate   # author a new SQL migration
-npx appkit db migrate up           # apply migrations (advisory-locked)
-npx appkit db verify               # detect drift between schema.ts and DB
-npx appkit db rls <table> <args>   # scaffold a Row-Level Security policy
+npx appkit db init                      # one-command Lakebase onboarding
+npx appkit db introspect                # pull existing schema (brownfield)
+npx appkit db migration generate <name> # author a new SQL migration
+npx appkit db migrate up                # apply migrations (advisory-locked)
+npx appkit db migrate status            # list applied vs pending migrations
+npx appkit db verify                    # detect drift between schema.ts and DB
+npx appkit db rls <entity> <spec>       # scaffold a Row-Level Security policy
+npx appkit db seed                      # apply config/database/seed.sql
+npx appkit db setup:dev                 # provision a per-user dev branch
+npx appkit db types generate            # regenerate typed client artifacts
 ```
 
 `db migrate up` takes a Postgres advisory lock so two concurrent deploys
@@ -110,44 +118,99 @@ without an interactive confirmation.
 
 ## Hooks
 
-Add per-entity lifecycle hooks via `database({ hooks: { ... } })`:
+`ctx.userId` is the forwarded email — a label, not authz; `undefined` under
+SP. Guard before writing it as audit metadata:
 
 ```ts
 database({
   hooks: {
     user: {
-      beforeCreate: async (data, ctx) => ({ ...data, createdBy: ctx.userId }),
+      beforeCreate: async (data, ctx) => ({
+        ...data,
+        ...(ctx.userId ? { createdBy: ctx.userId } : {}),
+      }),
       afterCreate: async (row) => audit(row.id, "created"),
     },
   },
 });
 ```
 
-`upsert` is a separate channel from `create` and `update` — `beforeUpsert`
-does **not** fan out into `beforeCreate` / `beforeUpdate`. Use a shared
-helper if you need the same logic in both branches.
+`upsert` is its own channel — `beforeUpsert` / `afterUpsert` fire on
+`create({ upsert: true })`; `beforeCreate` / `beforeUpdate` do **not**.
+
+## Row-Level Security
+
+`appkit db rls <entity> <spec>` writes a numbered migration, registers it
+in `meta/_journal.json`, and emits `ENABLE` + `FORCE ROW LEVEL SECURITY`
+(Postgres bypasses RLS for table owners by default — `FORCE` covers the SP
+pool). The first run also emits a helpers migration with `current_user_email()`,
+which reads the `app.user_id` GUC AppKit `SET`s on every OBO connection
+(rename via [`rls.sessionVariable`](#configuration)).
+
+```bash
+npx appkit db rls case "owner_email:owner_email"        # SELECT/UPDATE/DELETE
+npx appkit db rls case "owner_email:owner_email" --action insert
+npx appkit db rls case "tenant_id = current_setting('app.tenant_id')::uuid"
+```
+
+`owner_email:<col>` expands to `<col> = current_user_email()`. Anything else
+is raw SQL (rejected on semicolons, comments, unbalanced parens). Use
+`--dry-run` to preview without writing.
+
+`--action select,update` emits one policy per verb with derived names
+(`<base>_select`, `<base>_update`); `all` is exclusive.
 
 ## OBO and forwarded headers
 
-Per-user execution reads `x-forwarded-email` and `x-forwarded-access-token`
-from the request. The Databricks Apps gateway strips inbound copies and
-injects authentic values, so the plugin trusts these headers in production.
-In dev the same headers are accepted from anywhere so the local loop stays
-unblocked.
+OBO reads `x-forwarded-email` and `x-forwarded-access-token`. The Databricks
+Apps gateway strips inbound copies and injects authentic values; the plugin
+trusts them in production. Dev accepts them from anywhere — **don't expose
+the dev server beyond loopback** unless you front it with the same trust
+boundary.
 
 ## Pool sizing
 
-The service-principal (SP) pool defaults to 10 connections. Per-user (OBO)
-pools default to 4 connections each, and the registry caps at 25 distinct
-users. Worst-case fan-out is therefore `(1 + 25) × 4 + 10 = 114` connections
-per app instance — tune via `connection.max` and `oboPoolMax` for your
-Lakebase tier.
+SP pool: 10. OBO pools: 2 connections each, registry capped at 100 users
+(LRU). Worst-case fan-out per instance: `(1 + 100) × 2 + 10 = 212`. Tune via
+`connection.max` and `oboPoolMax`. Lakebase's PgBouncer multiplexes client
+connections, so effective headroom is larger than the raw tier limit.
 
 ## Drift detection
 
 Boot fails closed in production when `schema.ts` and the live DB disagree on
 column types or declared-but-missing tables. Additive drift (live-only
-columns/tables) is logged as a warning so blue/green deploys aren't blocked.
-
-Customize with `database({ checkDrift: false })` to skip the check, or
-`tolerateSetupFailure: true` to log-and-continue on schema-load errors.
+columns/tables) is logged. Policies are not compared.
+
+`database({ checkDrift: false })` skips the check;
+`tolerateSetupFailure: true` logs schema-load errors instead of throwing.
+
+## Configuration
+
+| Key                              | Default        | Notes                                                      |
+|----------------------------------|----------------|------------------------------------------------------------|
+| `connection.max`                 | 10             | SP pool max connections                                     |
+| `oboPoolMax`                     | 100            | Distinct OBO pools kept alive (LRU evicts beyond this)      |
+| `statementTimeoutMs`             | 15_000         | Server-side `statement_timeout` per pooled connection       |
+| `checkDrift`                     | `true`         | Run drift introspection at boot                             |
+| `tolerateSetupFailure`           | `false`        | Log instead of throw on schema-load / drift errors          |
+| `healthCheck`                    | enabled        | Set `false` to suppress `/api/database/_healthz`            |
+| `entitiesDiscovery`              | enabled        | Set `false` to suppress `/api/database/_entities`           |
+| `rls.sessionVariable`            | `"app.user_id"` | GUC name AppKit `SET`s on OBO connect (RLS reads it)        |
+
+## `column.private()` — partial
+
+Filters the typegen registry, but row payloads from
+`select`/`find`/`update().returning()` still include the value. **Treat as a
+"hide from forms" hint, not authz** — keep true secrets in a separate table
+with stricter ACLs.
+
+## Known limitations (beta)
+
+- **`column.private()` is a UX hint, not authz** — see above.
+- **No policy drift detection** — `db verify` doesn't compare `pg_policies`.
+- **Browser 404 semantics** — `db.<entity>.find(missingId)` and
+  `update(missingId, ...)` return `null` (not throw).
+- **`in` lists capped** — URL builder bounds `in` to stay under proxy
+  limits; partition large lists client-side.
+- **Dev mode trusts forwarded headers from any source** — see *OBO and
+  forwarded headers*.

packages/appkit/src/database/runtime/data-path.ts

@@ -165,8 +165,8 @@ export interface DataPath {
 
   /**
    * Tagged-template SQL escape hatch. Values are bound as parameters; column
-   * and identifier interpolation is intentionally not supported here — use
-   * `getDrizzle()` from the plugin's exports for that case.
+   * and identifier interpolation is intentionally not supported here — drop
+   * to `appkit.database.getPool().query(...)` if you need that.
    */
   raw<T = Row>(
     strings: TemplateStringsArray,

packages/appkit/src/database/schema-builder/define-schema.ts

@@ -18,16 +18,16 @@ export interface DefineSchemaOptions {
 }
 
 /**
- * Define a schema. This is used to build the schema for the database.
- * @param build - A function that builds the schema.
- * @param options - Options for defining the schema.
- * @returns The defined schema.
+ * Define a schema. Single source of truth for tables, types, and routes.
+ *
+ * @param build - Receives `{ table, enum }`.
+ * @param options - `schemaName` defaults to `"app"`.
  */
 export function defineSchema<T extends Record<string, AppKitTable>>(
   build: (ctx: SchemaBuilderContext) => T,
-  options: DefineSchemaOptions = {},
+  options?: DefineSchemaOptions,
 ): Schema<T> {
-  const schemaName = options.schemaName ?? "app";
+  const schemaName = options?.schemaName ?? "app";
   const schemaInstance =
     schemaName === "public" ? { table: pgTable } : pgSchema(schemaName);
 

packages/appkit/src/plugins/database/entity-proxy.ts

@@ -216,15 +216,17 @@ export function makeEntityClient<
 
 /**
  * Thin immutable wrapper around `DataPath`. Terminators go through
- * `this.run(action, fn)` → `Plugin#execute`, so telemetry, retry, cache,
- * and timeout flow consistently per action.
+ * `this.run(action, fn)` → `Plugin#execute` so telemetry/retry/cache/timeout
+ * flow per action. `implements EntityClient` catches drift at the declaration
+ * site instead of via the factory's `as unknown as` cast.
  */
 class EntityClientImpl<
   TRow extends Row = Row,
   TInsert = TRow,
   TUpdate = Partial<TRow>,
   TIncludes = Record<string, { row: Row }>,
-> {
+> implements EntityClient<TRow, TInsert, TUpdate, TIncludes>
+{
   constructor(
     private readonly deps: EntityClientDeps,
     private readonly state: EntityClientState,

template/appkit.plugins.json

@@ -29,7 +29,7 @@
     "database": {
       "name": "database",
       "displayName": "Database",
-      "description": "Application database with schema-driven CRUD, type generation, OBO, RLS, and LLM tools",
+      "description": "Application database with schema-driven CRUD, type generation, OBO, and RLS",
       "package": "@databricks/appkit",
       "resources": {
         "required": [

template/config/database/schema.ts

@@ -1,22 +1,21 @@
 import { defineSchema } from "@databricks/appkit";
 
 /**
- * Application database schema. The database plugin auto-loads this file
- * (see config/database/) and uses it as the single source of truth for
- *  - the typed `db.<entity>` browser client,
- *  - the auto-mounted `/api/database/<entity>` REST routes,
- *  - and runtime drift detection against the live Lakebase DB.
+ * Application database schema. Source of truth for the typed browser client,
+ * `/api/database/<entity>` routes, and drift detection.
  *
- * Add tables under the returned object and run:
- *   npx appkit db migration generate
- *   npx appkit db migrate up
+ * Add tables, then `npx appkit db migration generate <name>` + `migrate up`.
  *
  * Example:
- *   user: table("user", {
- *     id: id(),
- *     email: text().notNull(),
- *     createdAt: timestamp().defaultNow().notNull(),
- *   }),
+ *   import { defineSchema, id, text, timestamp } from "@databricks/appkit";
+ *
+ *   export default defineSchema(({ table }) => ({
+ *     user: table("user", {
+ *       id: id(),
+ *       email: text().notNull(),
+ *       createdAt: timestamp().defaultNow().notNull(),
+ *     }),
+ *   }));
  */
 // biome-ignore lint/correctness/noEmptyPattern: schema is intentionally empty in the starter template.
 export default defineSchema(({}) => ({}));