feat(appkit-ui): add database React hooks with read invalidation

[ditadi]

Why the change

With databaseApi in place, React code still had to track loading and error state, avoid duplicate requests, and reload data after every write. This adds read and write hooks (beta) that share requests, keep error state stable, and refresh the reads on screen after a successful write.

Special things to note

• Stacked on feat(appkit-ui): add typed databaseApi client for DatabasePlugin routes #608, so the diff here shows only the hooks. Merge feat(appkit-ui): add typed databaseApi client for DatabasePlugin routes #608 first.
• By default, a successful write restarts every mounted database read. A server mutation hook can write other tables in the same transaction, and the browser can't see that. invalidate: ["notes"] narrows the restart to reads that show notes rows, including reads that reach notes through an include. false turns it off.
• The server now publishes relations for the client. DatabasePlugin.clientConfig() returns { relations: { table: { relation: targetTable } } } for exposed tables only. These are the names include already accepts and the generated types already carry. This is the one change in packages/appkit.
• Write hooks never reject, like useServingInvoke: a failure resolves null (or false for a delete) and the error is in error. They never abort a request on unmount, because aborting wouldn't undo a committed write. A successful call resolves, and leaves loading, only once the reads it restarted have reloaded. databaseApi stays the layer that throws.
• Keyed routes refuse an id of "", ".", or ".." with INVALID_REQUEST and send nothing. URL resolution would otherwise send the request to the list route or the plugin root. The check is in resolveDatabaseUrl, so databaseApi is covered too.
• bundle-size-baseline.json is regenerated. The appkit-ui tarball grows from 358 KB to 404 KB across the feat(appkit-ui): add typed databaseApi client for DatabasePlugin routes #608 + feat(appkit-ui): add database React hooks with read invalidation #609 stack, which is over the 5% budget. The increase is the new client and hooks: no dependency is added, and no test file ships.

Change outline

The new public surface, typed by the same generated registry as databaseApi:

// @databricks/appkit-ui/react/beta
useDatabaseList(entity, params | null, { enabled?, keepPreviousData?, shape? })
  // → { data: { items, limit, offset }, loading, error, refetch }
useDatabaseRecord(entity, id | null, params?, { enabled?, keepPreviousData?, shape? })
useDatabaseCreate(entity, { invalidate?, onSuccess?, onError? })  // → { create(values), data, loading, error, reset }
useDatabaseUpdate(entity, { invalidate?, onSuccess?, onError? })  // → { update(id, values), … }
useDatabaseDelete(entity, { invalidate?, onSuccess?, onError? })  // → { remove(id), loading, error, reset }
serialized<T>()                          // declares a serializer's row type, unchecked
invalidateDatabaseReads(scope?): Promise<void>  // for writes made outside the hooks

Types follow the existing hook naming: UseDatabaseListOptions / UseDatabaseListResult, UseDatabaseCreateOptions / UseDatabaseCreateResult, and so on.

Read behavior:

• null params hold a list idle, for params that depend on another read.
• keepPreviousData: true keeps the previous page visible while the next one loads.
• shape takes serialized<T>() to only declare the row type, or a function such as zod's parse to check every row at runtime. A row that fails its shape fails the read with INTERNAL; the schema error stays in cause, since it can quote row values.
• A refetch keeps the last data visible while it loads and after it fails. The exception is NOT_FOUND: the row is gone, so data is cleared.
• error keeps its identity across renders, so an effect keyed on it, such as a toast, runs once.

Write behavior: onSuccess and onError run for every call, including a superseded call and one that finishes after unmount. Inline callbacks don't change the identity of create, update, or remove.

How a read and a write move through the layers:

useDatabaseList("notes", params)
  resolveDatabaseUrl("notes", "list", query)   # unpublished → NOT_EXPOSED, bad id → INVALID_REQUEST, no request
  scope = databaseReadScope("notes", include)  # tables the read shows, via the published relations
  retainDatabaseRead(url, accept, scope)       # key = url; first subscriber fetches; last release aborts
    requestDatabase(url)                       # the databaseApi transport

useDatabaseCreate("notes").create(values)
  POST notes.create                            # never aborted; only the latest call sets state
  await invalidateDatabaseReads(invalidate)    # restartStarted(match) on the read store
    → mounted reads whose scope meets the written tables refetch, keeping their data visible
  settle state, then onSuccess(row, values)

Reads reuse the existing createRequestStore. It gains per-entry metadata and a way to restart the reads that are already running, which resolves once they settle:

 interface RequestStore<S, M> {
-  retain(key, run, autoStart?): () => void;
+  retain(key, run, options?: { autoStart?, meta?: M }): () => void;
   start(key): void;
+  restartStarted(match?: (key, meta?: M) => boolean): Promise<void>;
   subscribe(key, listener): () => void;
   getSnapshot(key): S;
 }

A runner may return a promise that settles when its run does. restartStarted skips entries whose last subscriber already left. useAnalyticsQuery passes { autoStart } and is otherwise unchanged.

databaseApi changes in two ways. It exports its transport helpers, marked @internal: resolveDatabaseUrl, requestDatabase, and the untyped row writers. It also gains the id check described above.

The playground's BoardExplorer drops its last hand-written request:

 <BoardExplorer> (apps/dev-playground/client)
-  boards / notes = databaseApi.list(…) in effects; timeline and full body via fetch
-  submit(): fetch POST → reload everything
+  boards   = useDatabaseList("boards", { include: { notes: { limit: 5 } } })
+  notes    = useDatabaseList("notes", board ? { where: { board_id }, order, limit: 5 } : null)
+  timeline = useDatabaseRecord("boards", board?.id, { include: { notes: { include: { note_events } } } })
+  fullNote = useDatabaseRecord("notes", revealedId)
+  createBoard / createNote = useDatabaseCreate(…)   # reads refresh through invalidation
 <RefusalProbe>                                     # unchanged: raw fetch on purpose

The database plugin docs gain a "React hooks (beta)" section: lists, pagination, records, serializer shapes, writes, callbacks, invalidation, and lifecycles.

The PR has four commits: read hooks, write hooks, strict query types, and the hardening above. The hook tests share database-test-utils.ts.

This pull request and its description were written by Isaac.

[github-actions]

📦 Bundle size report

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

@databricks/appkit

npm tarball (packed): 1.2 MB (+32 B) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist	raw	gzip
JS (runtime)	1.2 MB (+86 B)	447 KB (+9 B)
Type declarations	456 KB	165 KB (+2 B)
Source maps	2.5 MB (+20 B)	837 KB (+13 B)
Other	11 KB	3.7 KB
Total	4.1 MB (+106 B)	1.4 MB (+24 B)

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

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
.	102 KB (-1 B)	2.5 KB (-1 B)	105 KB (-2 B)	external	331 KB
./beta	98 KB	484 B	99 KB	external	297 KB
./testing	42 KB	32 KB (+2 B)	74 KB (+2 B)	external	215 KB
./tsdown	520 B	0 B	520 B	external	813 B
./type-generator	23 KB	0 B	23 KB	external	66 KB

Chunks:

Entry	Chunk	Load	Size (gz)
.	index.js	initial	97 KB
.	utils.js	initial	4.6 KB
.	remote-tunnel-manager.js	lazy	2.5 KB
./beta	beta.js	initial	81 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	wide-event-emitter.js	initial	3.2 KB
./beta	client.js	initial	594 B
./beta	index.js	initial	20 B
./beta	supervisor-api.js	lazy	193 B
./beta	databricks.js	lazy	176 B
./beta	index.js	lazy	115 B
./testing	manifest.js	initial	29 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	23 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)	428 KB	146 KB
Type declarations	266 KB	98 KB (-2 B)
Source maps	852 KB	285 KB
CSS	16 KB	3.2 KB
Total	1.5 MB	533 KB (-2 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]

🤖 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 37697602718 -R databricks/appkit -n appkit-template-0.86.0-pr.95ff9d5-stack-database-hooks-02-react-hooks-609 -D appkit-pr-609 \
  && unzip -o "appkit-pr-609/appkit-template-0.86.0-pr.95ff9d5-stack-database-hooks-02-react-hooks-609.zip" -d "appkit-pr-609" \
  && databricks apps init --template "appkit-pr-609"

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]

Re-reviewed at a29a2e1.

Fixed since the first pass:

• Bundle baseline is regenerated (e010f53, a29a2e1).
• A write now follows superseding refreshes instead of resolving when another refresh aborts its reads, with tests for overlapping restartStarted and two concurrent write hooks.

Hooks and database client tests pass locally (301).

Accepted as-is, worth follow-ups:

• Default invalidate: true still restarts every mounted read per write. Consider defaulting to the written entity plus its relations.
• Coalesce overlapping invalidations to bound W×R refetches.
• Sync optionsRef in a layout effect so a changed invalidate/onSuccess is not missed by a write that settles first.
• Public clearDatabaseReads() for logout / account switch, plus a docs note.
• Catch URIError from encodeURIComponent on lone surrogates and throw INVALID_REQUEST.
• encodeURIComponent(String(boardId)) in the docs example near database.md:597.