@dbx-tools/appkit

Node-side helpers for Databricks AppKit apps.

Import this package when backend code needs AppKit execution context, typed plugin lookup, Databricks SDK cancellation, layered config resolution, or Lakebase auto-configuration without taking on a heavier feature package.

Key features:

• Auto-configuration before AppKit setup, especially for Lakebase/Postgres env values that AppKit plugins read during initialization.
• Runtime-safe context access for code that may run inside an AppKit request, from a CLI, or from a background script.
• Typed plugin lookup helpers for AppKit plugins that depend on exports from sibling plugins.
• Config resolution across explicit options, CLI flags, env vars, Databricks Asset Bundle outputs, and app.yaml.
• SDK cancellation bridging from web AbortSignal values into Databricks SDK Context values.
• Lakebase cache-schema provisioning for deployments where the app identity must be granted access before persistent cache initialization.

Why Use This Over Native AppKit

Use native AppKit directly when your app can read its required env vars before createApp() and does not need extra setup around plugin exports or config sources.

Use this package when the friction is around bootstrapping and reuse:

• AppKit plugins read Lakebase/Postgres env during initialization; this package resolves and applies those values before setup.
• AppKit exposes request context inside AppKit handlers; these helpers make code safe to call from scripts, tests, and background jobs too.
• AppKit plugin instances are generic; the lookup helpers keep sibling-plugin access typed and errors actionable.
• AppKit does not own your local CLI flags, bundle validation output, or app.yaml; config.resolveConfigValue() gives setup scripts one resolution path across those sources.

Create An Auto-Configured App

createApp.createApp is a drop-in wrapper around AppKit createApp with the same config and the same typed plugin-export map. It runs createApp.autoConfigure() first so enabled capabilities can populate environment variables before plugin setup runs.

import { lakebase, server } from "@databricks/appkit";
import { createApp } from "@dbx-tools/appkit";

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

When lakebase() is present, auto-config resolves Lakebase Postgres connection settings and fills missing PG* / LAKEBASE_* variables. That avoids a startup race where the Lakebase plugin reads env before another async setup step can discover it.

Auto-configuration is conservative: existing env vars win unless a caller passes explicit options, and local-only discovery is skipped inside a Databricks App environment. This makes the same entrypoint usable in local development, Databricks Asset Bundle validation, and deployed Apps.

Boot-time resolution runs as the service principal before any plugin exists, so it sits outside AppKit's interceptor chain. It carries its own timeout, and createApp.autoConfigure() accepts an AbortSignal when a caller wants to cancel it earlier.

Use the lower-level functions when you need to inspect or customize the result:

import { lakebaseResolver } from "@dbx-tools/appkit";

const resolved = await lakebaseResolver.resolveLakebaseConnection({
  endpoint: process.env.LAKEBASE_ENDPOINT,
  autoCreate: false,
});

lakebaseResolver.applyLakebaseToEnv(resolved);

Configuration

createApp.createApp() accepts everything AppKit's createApp does, plus:

| Option | Type | Default | Description | | --------------- | ------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | autoConfigure | "provision" \| "env" \| false | "provision" | What to run before AppKit boots. "provision" resolves the Lakebase connection into process.env and grants the AppKit cache schema; "env" resolves the connection only; false skips auto-configuration. Omit it to gate the default on a lakebase plugin being registered, or set it explicitly to run regardless. |

lakebaseResolver.resolveLakebaseConnection() accepts:

| Option | Type | Default | Description | | ------------ | ------------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | endpoint | string | LAKEBASE_ENDPOINT | Any address pgaddress.parseAddress() understands: resource path, Postgres URI, hostname, or bare project id. | | project | string | discovered | Lakebase project id. Resolved from the workspace when unset. | | branch | string | project default | Branch id within the project. | | database | string | PGDATABASE, else databricks_postgres | Postgres database name. | | host | string | PGHOST, else the endpoint's host | Postgres hostname. | | port | number | PGPORT, else 5432 | Postgres port. | | sslMode | "require" \| "disable" \| "prefer" | PGSSLMODE, else require | Postgres TLS mode. | | autoCreate | string \| false | slug of the package name | Project id to create when the workspace has none. false fails instead of creating. |

Environment variables read during resolution:

| Variable | Description | | ------------------- | ------------------------------------------------------------------------------------------------ | | LAKEBASE_ENDPOINT | Endpoint resource path, Postgres URI, hostname, or project id. | | PGHOST | Postgres hostname. Skips the endpoint lookup when set with PGDATABASE and LAKEBASE_ENDPOINT. | | PGDATABASE | Postgres database name. | | PGPORT | Postgres port. A value outside 1-65535 fails with a ValidationError. | | PGSSLMODE | require, disable, or prefer. Any other value fails with a ValidationError. | | PGUSER | Connecting role. Filled from the workspace identity when unset. |

Resolved values are written back to process.env by lakebaseResolver.applyLakebaseToEnv(), which never overwrites a variable that is already set.

Resolve Local And Bundle Config

config.resolveConfigValue() checks explicit options, CLI overrides, env vars, Databricks Asset Bundle validation output, and app.yaml env entries, in AppKit's precedence order: explicit config, then environment variable, then the app or bundle definition.

import { config } from "@dbx-tools/appkit";

const warehouseId = await config.resolveConfigValue("DATABRICKS_WAREHOUSE_ID", {
  cli: { DATABRICKS_WAREHOUSE_ID: flags.warehouse },
  sources: config.withCliSources(),
});

Use this in CLIs and setup scripts that should behave the same locally and in a Databricks App deployment. config.bundle() and config.appYaml() expose the parsed files when you need to diagnose which source won.

Parse Lakebase Addresses

pgaddress.parseAddress() accepts resource paths, Postgres URLs, bare Lakebase hosts, and partial inputs. It gives the resolver a common shape without requiring users to remember one canonical format.

import { pgaddress } from "@dbx-tools/appkit";

pgaddress.parseAddress(
  "postgresql://[email protected]/databricks_postgres?sslmode=require",
);

pgaddress.parseResourcePath() is useful when you specifically expect a projects/<id>/branches/<id>/endpoints/<id> value.

Use AppKit Execution Context Safely

appkit.tryGetExecutionContext() returns the active AppKit request context when code is running under AppKit, and undefined elsewhere. That lets libraries preserve OBO auth in apps while still working from scripts.

import { appkit } from "@dbx-tools/appkit";
import { WorkspaceClient } from "@databricks/sdk-experimental";

const client = appkit.tryGetExecutionContext()?.client ?? new WorkspaceClient({});

appkit.ensureInitialized() lazily initializes AppKit runtime state before context lookup in code paths that may run early.

Adapt Databricks SDK Cancellation

Databricks SDK calls accept a Context. Many app and web APIs use AbortSignal. databricks.toContext() bridges the two.

import { databricks } from "@dbx-tools/appkit";

await client.apiClient.request(
  {
    path: "/api/2.0/serving-endpoints",
    method: "GET",
    headers: new Headers(),
    raw: false,
  },
  databricks.toContext(request.signal),
);

databricks.isAppEnv() checks the Databricks App environment shape for setup code that should skip local-only filesystem or bundle discovery.

Look Up Sibling Plugins

AppKit's plugin map is intentionally generic. plugin.data(), plugin.instance(), and plugin.require() keep lookups typed and produce better errors when a required plugin is missing.

import { lakebase } from "@databricks/appkit";
import { plugin } from "@dbx-tools/appkit";

const lake = plugin.instance(this.context, lakebase);
const pool = lake?.exports().pool;

const required = plugin.require(this.context, lakebase, "my-plugin").exports();

Use this in AppKit plugins that depend on sibling plugin exports but should not hard-code registered names or casts at every call site. A missing required plugin throws AppKit's ConfigurationError, naming both the caller and the plugin to register.

Provision Lakebase Cache Schema

provision.provisionCacheSchema() grants the AppKit cache schema in Lakebase to the Postgres role that will run the app. Use it after Lakebase connection env has been resolved and before AppKit initializes its persistent cache.

import { provision } from "@dbx-tools/appkit";

await provision.provisionCacheSchema("[email protected]");

Pass a second argument to report progress on your own logger. The grants are skipped inside a Databricks App, and any failure is logged rather than thrown so a degraded cache never blocks startup.

Modules

| Module | Responsibility | | ------------------ | ------------------------------------------------------------------------------------------ | | createApp | createApp() wrapper and autoConfigure(). | | lakebaseResolver | Lakebase connection discovery, default picking, optional auto-create, and env application. | | pgaddress | Permissive Lakebase/Postgres address parser. | | config | Local/env/bundle/app-yaml config lookup. | | appkit | Execution context lookup and initialization. | | databricks | App env detection and SDK context cancellation adapters. | | plugin | Typed AppKit plugin data, instance, and required-instance lookup. | | provision | Cache schema provisioning helpers. |

The shell-facing wrapper for auto-config is @dbx-tools/cli-appkit-env. Higher-level agent composition is in @dbx-tools/appkit-mastra.