Skip to main content
⚠️ AppKit is in an early development phase and is subject to change without notice. DO NOT use in production environments.

# @databricks/appkit

Core library for building Databricks applications with type-safe SQL queries, plugin architecture, and React integration.

## Enumerations​

Enumeration | Description
--- | ---
RequestedClaimsPermissionSet | Permission set for Unity Catalog table access
ResourceType | Supported resource types that plugins can depend on. Each type has its own set of valid permissions.

## Classes​

Class | Description
--- | ---
AppKitError | Base error class for all AppKit errors. Provides a consistent structure for error handling across the framework.
AuthenticationError | Error thrown when authentication fails. Use for missing tokens, invalid credentials, or authorization failures.
ConfigurationError | Error thrown when configuration is missing or invalid. Use for missing environment variables, invalid settings, or setup issues.
ConnectionError | Error thrown when a connection or network operation fails. Use for database pool errors, API failures, timeouts, etc.
ExecutionError | Error thrown when an operation execution fails. Use for statement failures, canceled operations, or unexpected states.
InitializationError | Error thrown when a service or component is not properly initialized. Use when accessing services before they are ready.
Plugin | Base abstract class for creating AppKit plugins.
ResourceRegistry | Central registry for tracking plugin resource requirements. Deduplication uses type + resourceKey (machine-stable); alias is for display only.
ServerError | Error thrown when server lifecycle operations fail. Use for server start/stop issues, configuration conflicts, etc.
TunnelError | Error thrown when remote tunnel operations fail. Use for tunnel connection issues, message parsing failures, etc.
ValidationError | Error thrown when input validation fails. Use for invalid parameters, missing required fields, or type mismatches.

## Interfaces​

Interface | Description
--- | ---
BasePluginConfig | Base configuration interface for AppKit plugins
CacheConfig | Configuration for caching
DatabaseCredential | Database credentials with OAuth token for Postgres connection
GenerateDatabaseCredentialRequest | Request parameters for generating database OAuth credentials
ITelemetry | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins.
LakebasePoolConfig | Configuration for creating a Lakebase connection pool
PluginManifest | Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property.
RequestedClaims | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables
RequestedResource | Resource to request permissions for in Unity Catalog
ResourceEntry | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership.
ResourceFieldEntry | Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance_name, database_name or scope, key).
ResourceRequirement | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements().
StreamExecutionSettings | Configuration for streaming execution with default and user-scoped settings
TelemetryConfig | OpenTelemetry configuration for AppKit applications
ValidationResult | Result of validating all registered resources against the environment.

## Type Aliases​

Type Alias | Description
--- | ---
ConfigSchema | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types.
IAppRouter | Express router type for plugin route registration
ResourcePermission | Union of all possible permission levels across all resource types.

## Variables​

Variable | Description
--- | ---
sql | SQL helper namespace

## Functions​

Function | Description
--- | ---
appKitTypesPlugin | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood.
createApp | Bootstraps AppKit with the provided configuration.
createLakebasePool | Create a Lakebase pool with appkit's logger integration. Telemetry automatically uses appkit's OpenTelemetry configuration via global registry.
generateDatabaseCredential | Generate OAuth credentials for Postgres database connection using the proper Postgres API.
getExecutionContext | Get the current execution context.
getLakebaseOrmConfig | Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.
getLakebasePgConfig | Get Lakebase connection configuration for PostgreSQL clients.
getPluginManifest | Loads and validates the manifest from a plugin constructor. Normalizes string type/permission to strict ResourceType/ResourcePermission.
getResourceRequirements | Gets the resource requirements from a plugin's manifest.
getWorkspaceClient | Get workspace client from config or SDK default auth chain
isSQLTypeMarker | Type guard to check if a value is a SQL type marker