Skip to content

feat(appkit): serve named database operations instead of AutoCRUD - #692

Open
ditadi wants to merge 14 commits into
mainfrom
stack/database-stable/06-serve-operations
Open

ditadi wants to merge 14 commits into
mainfrom
stack/database-stable/06-serve-operations

Conversation

@ditadi

@ditadi ditadi commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

What did you change, and why?

Authored operations are now the only database HTTP surface. database() discovers the generated registry for server/database/routes/, so an app using the conventional layout no longer imports routes.gen.ts in its server entry.

  • database() discovers operations, database({ routes: false }) keeps server-side access only, and database({ routes: customRoutes }) uses an explicit registry.
  • The standard appkitServerConfig() build includes the registry, schema, and operation modules automatically. Production discovery loads the compiled registry beside the server entry, including custom output directories. Clean builds remove stale registries when sources are deleted.
  • Development setup regenerates the source registry before importing it. Native imports let tsx watch track routes, shared row schemas, and policies; first-route additions and last-route deletions reload correctly. Production uses the compiled registry without generating files.
  • Outside development, missing generation and malformed registries fail setup with actionable errors before opening a pool. Explicit routes and disabled routes bypass discovery.
  • Removes AutoCRUD, the api option, the crudRoutes check, the entity client and hooks, the CRUD HTTP facets, and the DatabricksAppKitDatabaseRegistry global, with no compatibility layer.
  • The server's JSON parser skips the operation prefix by routed path, published operation names survive client config redaction, and setup validates the registry before the pool opens.
  • The playground omits the list input schema and client argument, declares the delete ID schema explicitly, and uses skipToken for dependent note reads. Its row-answering operations declare explicit outputs without author_email, and notes.delete answers no body. Documentation explains omitted-input and omitted-output semantics, explicit schemas, that .private() does not filter an output, and that a policy's resource lookup receives actor.
  • Guidelines explain policy-resource snapshots, atomic transaction conditions and database constraints, database-generated identifiers, safe field-validation details, operation/session-scoped mutation state, and hooks for rendered React data.
  • The playground, template guidance, and documentation use automatic discovery. The playground writes a note and its event in one transaction, and only the author may edit or delete a note.

This replaces the beta database HTTP API. Operations without input schemas accept no parameters, and operations without output schemas answer no body.

Interface

import { createApp, server } from "@databricks/appkit";
import { database } from "@databricks/appkit/beta";

await createApp({ plugins: [server(), database()] });

// Alternatives:
database({ routes: false });
database({ routes: customRoutes });
config/database/schema.ts                       schema declarations
server/database/routes/*.ts                     defineOperation exports
server/database/policies.ts                     shared policies outside routes/
server/database/routes.gen.ts                   generated, committed
shared/appkit-types/database-operations.d.ts     generated, committed

An explicit schema overrides conventional schema discovery. With an explicit routes registry, the schema must be the same object the registry loads. Custom server builds must include the registry entry beside their server using the same file extension, or import and pass the registry explicitly.

Removed without a compatibility layer:

  • database({ api }), its AutoCRUD configuration types, and routes under /api/database/<table>.
  • databaseApi.list, get, create, update, and remove; the entity CRUD hooks; and invalidateDatabaseReads.
  • The DatabricksAppKitDatabaseRegistry global that the entity hooks read.
  • The CRUD column codecs and table compiler (crud/codecs.ts, compileCrudTables) and the shared WireOutput type, which lost their last consumers.

Validation

  • After the review-feedback commit: 840 database and type-generator tests (including the tsx watch test below) and the playground smoke test (10) pass.
  • A real tsx watch + Vite test covers schema-only startup, first route creation, route edits, shared schema edits, added routes, deletions, and final route removal without a restart loop.
  • pnpm build, pnpm docs:build, pnpm check:fix, and pnpm -r typecheck pass.
  • Not rerun after the review-feedback commit: the playground client typecheck and production build, and the local AML scenario tests below.
  • The source-less production bundle check loads all three fixture operations under plain Node after removing TypeScript sources.
  • Application scenario validation is local only: 10 real operation/PostgreSQL integration tests and 5 screen tests pass. The disposable database uses a private Unix socket and no TCP listener. The AML app, its migrations, and its tests remain ignored and are not included in this or any other PR.

Live Databricks Apps identity and Lakebase were not exercised. The docs build reports an existing broken anchor in custom-plugin telemetry documentation; it completes successfully.

Stack

#683 → #687 → #688 → #689 → #690 → #691 → #692

Design: #683. Previous layer: #691.

Review feedback: refactor(appkit): migrate operations to explicit outputs migrates the playground, tests, and guide, and removes the orphaned codecs.

Review feedback (round 2): the hooks guard from #687 stays, pointing to named operations. docs(appkit): follow the operation review fixes in the guide documents these behaviors:

  • the origin check runs first;
  • a verified token is reused for 30 s;
  • proxy write failures are unknown outcomes;
  • discovery skips dotfiles;
  • route modules must not open handles at import.

Restack: the conflicts with main's #712 (skipBodyParsing patterns, kept alongside the operation prefixes) and #680 (design plugin exports) are resolved. Integration spans are filtered under the stable HTTP conventions.


Stack created with GitHub Stacks CLI • Give Feedback 💬

@ditadi
ditadi added this pull request to stack #693 October 23, 2026 15:01
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

📦 Bundle size report

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

@databricks/appkit

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

dist raw gzip
JS (runtime) 1.4 MB (-601 B) 500 KB (+862 B)
Type declarations 482 KB (-1.2 KB) 174 KB (-424 B)
Source maps 2.7 MB (-1.3 KB) 930 KB (+1.4 KB)
Other 11 KB 3.7 KB
Total 4.6 MB (-3.1 KB) 1.6 MB (+1.8 KB)
Per-entry composition (own code — deps external (as shipped))
Entry Initial (gz) Lazy (gz) Total (gz) node_modules (min) Own code (min)
. 118 KB (+103 B) 2.4 KB 121 KB (+103 B) external 378 KB (+281 B)
./beta 118 KB (+3.1 KB) 4.5 KB (+4.1 KB) 123 KB (+7.1 KB) external 356 KB (+14 KB)
./testing 47 KB (+41 B) 38 KB (+118 B) 85 KB (+159 B) external 246 KB (+281 B)
./tsdown 630 B (+110 B) 0 B 630 B (+110 B) external 1.0 KB (+233 B)
./type-generator 31 KB (-59 B) 0 B 31 KB (-59 B) external 89 KB (-292 B)

Chunks:

Entry Chunk Load Size (gz)
. index.js initial 114 KB
. utils.js initial 4.6 KB
. remote-tunnel-manager.js lazy 2.4 KB
./beta beta.js initial 92 KB
./beta stream-manager.js initial 5.9 KB
./beta define-schema.js initial 5.8 KB
./beta service-context.js initial 4.3 KB
./beta modular.js initial 3.6 KB
./beta databricks.js initial 3.3 KB
./beta wide-event-emitter.js initial 2.8 KB
./beta client.js initial 645 B
./beta index.js initial 20 B
./beta index.js lazy 4.0 KB
./beta supervisor-api.js lazy 201 B
./beta databricks.js lazy 186 B
./beta index.js lazy 124 B
./testing manifest.js initial 34 KB
./testing index.js initial 10 KB
./testing wide-event-emitter.js initial 2.9 KB
./testing index.js lazy 34 KB
./testing remote-tunnel-manager.js lazy 2.4 KB
./testing utils.js lazy 1.8 KB
./tsdown index.js initial 630 B
./type-generator index.js initial 31 KB

@databricks/appkit-ui

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

dist raw gzip
JS (runtime) 427 KB (-29 KB) 145 KB (-12 KB)
Type declarations 249 KB (-33 KB) 92 KB (-12 KB)
Source maps 831 KB (-75 KB) 279 KB (-27 KB)
CSS 16 KB 3.2 KB
Total 1.5 MB (-137 KB) 519 KB (-52 KB)
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.4 KB (-1.1 KB) 0 B 2.4 KB (-1.1 KB) 0 B 5.3 KB (-4.1 KB)
./react 441 KB 49 KB 489 KB 1.4 MB 179 KB
./react/beta 13 KB (-3.1 KB) 0 B 13 KB (-3.1 KB) 25 KB (-18 B) 12 KB (-10 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.4 KB
./react index.js initial 439 KB
./react tslib initial 2.1 KB
./react apache-arrow lazy 49 KB
./react/beta beta.js initial 13 KB

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

🤖 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 44777343257 -R databricks/appkit -n appkit-template-0.101.0-pr.81ef51e-stack-database-stable-06-serve-operations-692 -D appkit-pr-692 \
  && unzip -o "appkit-pr-692/appkit-template-0.101.0-pr.81ef51e-stack-database-stable-06-serve-operations-692.zip" -d "appkit-pr-692" \
  && databricks apps init --template "appkit-pr-692"

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.

@ditadi
ditadi force-pushed the stack/database-stable/06-serve-operations branch from f72c9a7 to 8a9f21c Compare October 26, 2026 10:41
@ditadi
ditadi marked this pull request as ready for review October 28, 2026 11:05
@ditadi
ditadi requested a review from a team as a code owner October 28, 2026 11:05
@ditadi
ditadi requested a review from atilafassina October 28, 2026 11:05
@ditadi
ditadi force-pushed the stack/database-stable/06-serve-operations branch from 4b113fa to 2fd1455 Compare November 3, 2026 13:01
@ditadi
ditadi force-pushed the stack/database-stable/06-serve-operations branch from 2fd1455 to 30d4a43 Compare November 3, 2026 13:47
@ditadi
ditadi requested review from MarioCadenas and removed request for atilafassina November 3, 2026 13:55
@ditadi
ditadi removed this pull request from stack #693 November 3, 2026 15:18
@ditadi
ditadi force-pushed the stack/database-stable/06-serve-operations branch from 30d4a43 to a483f29 Compare November 3, 2026 15:18
@ditadi
ditadi added this pull request to stack #704 November 3, 2026 15:19
@ditadi
ditadi force-pushed the stack/database-stable/06-serve-operations branch from a483f29 to 4fb8105 Compare November 4, 2026 19:15
@ditadi
ditadi force-pushed the stack/database-stable/06-serve-operations branch 2 times, most recently from 2f36a19 to 5fef7c8 Compare November 6, 2026 10:49
@ditadi
ditadi force-pushed the stack/database-stable/06-serve-operations branch from cbeeec2 to b6887df Compare November 17, 2026 13:57
@ditadi
ditadi force-pushed the stack/database-stable/06-serve-operations branch from b6887df to eae9822 Compare November 20, 2026 10:04
@ditadi
ditadi force-pushed the stack/database-stable/06-serve-operations branch 2 times, most recently from 8fe680e to 32310be Compare November 20, 2026 14:20
@ditadi
ditadi force-pushed the stack/database-stable/06-serve-operations branch from 32310be to 88de7f0 Compare November 20, 2026 14:27
@ditadi
ditadi force-pushed the stack/database-stable/06-serve-operations branch 3 times, most recently from 65584c8 to b540231 Compare November 20, 2026 16:39
Base automatically changed from stack/database-stable/05-client-operations to main November 20, 2026 16:50
ditadi and others added 14 commits November 20, 2026 16:50
database({ routes }) mounts the generated registry under

/api/database/operations/<name>; without routes the plugin serves no

HTTP endpoint. The table routes, the api and crudRoutes options, the

entity client and hooks, and their HTTP facets are removed.

The playground, template, and docs move to named operations. The

playground writes a note and its event in one transaction, and only

the author may change or delete the note.

Signed-off-by: ditadi <victordperd@gmail.com>
Signed-off-by: ditadi <victordperd@gmail.com>
Signed-off-by: ditadi <victordperd@gmail.com>
The plugin validates and serves operations without the schema's table set,
and the playground declares an output on boards.create, notes.create, and
notes.update while notes.delete answers no body. The database guide drops
the entity field and the default-output table, says that every callback,
the resource lookup included, receives the actor, and states that private()
does not sanitize an operation's output. The table contract and column
codecs that only default outputs used go with them, along with the shared
WireOutput type.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
The upgraded instrumentation names the server by server.port, not
http.host, so the fake workspace's spans are dropped by port.

[#tern:skip]

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
The guide states the origin check first, the 30-second reuse of a
verified token, proxy write failures as unknown outcomes, and which
files discovery skips.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
The watcher test ran its server without the development export condition,
so shared resolved to its unbuilt dist and the test failed on a fresh
install. The child now gets the condition through NODE_OPTIONS, which
reaches the node process that tsx watch spawns.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
…hema

Operations in server/database/routes/ still need config/database/schema.ts
with an explicit schema, because type generation and the generated registry
import it. The guide says so and shows a one-line re-export for a different
layout.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
Writes without Origin or Sec-Fetch-Site are now refused before the caller
is identified, so the unauthenticated and absolute-form cases send what a
same-origin page sends and still reach the identity check.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
…licy failures

An answer is bounded by 5 MiB and an unusable one is logged, a write must
carry Origin or Sec-Fetch-Site, a database failure inside a policy fails the
request instead of refusing it, and a 403 from the identity check is logged.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
A database failure inside a policy answers 503 or 500, and a database
permission error still refuses. A policy whose queries run only for an
existing record can reveal that record while the database is failing.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
The client now opens a new session when someone signs in after a 401,
so queries that showed a sign-in error ask again.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
The template's build now runs `appkit generate-types` under
`NODE_ENV=production`, so a custom build that calls the command needs
the same setting to fail on an operation without authorization.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
@ditadi
ditadi force-pushed the stack/database-stable/06-serve-operations branch from b540231 to 6d0c849 Compare November 20, 2026 16:50
@ditadi
ditadi requested a review from MarioCadenas November 20, 2026 17:24

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants