feat: introduce Lakebase Autoscaling driver (#98)

Author: pkosiec

.github/workflows/release-lakebase.yml

@@ -0,0 +1,61 @@
+name: Release @databricks/lakebase
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: "Dry run (no actual release)"
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  release:
+    runs-on:
+      group: databricks-protected-runner-group
+      labels: linux-ubuntu-latest
+
+    environment: release
+
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: "https://registry.npmjs.org"
+          cache: "pnpm"
+
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Release
+        working-directory: packages/lakebase
+        run: |
+          if [ "${{ inputs.dry-run }}" == "true" ]; then
+            pnpm release:dry
+          else
+            pnpm release:ci
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CLAUDE.md

@@ -233,6 +233,39 @@ The AnalyticsPlugin provides SQL query execution:
 - Built-in caching with configurable TTL
 - Databricks SQL Warehouse connector for execution
 
+### Lakebase Autoscaling Connector
+
+**Location:** `packages/appkit/src/connectors/lakebase/`
+
+AppKit provides `createLakebasePool()` - a factory function that returns a standard `pg.Pool` configured with automatic OAuth token refresh for Databricks Lakebase (OLTP) databases.
+
+**Key Features:**
+- Returns standard `pg.Pool` (compatible with all ORMs)
+- Automatic OAuth token refresh (1-hour tokens, 2-minute buffer)
+- Token caching to minimize API calls
+- Battle-tested pattern (same as AWS RDS IAM authentication)
+
+**Quick Example:**
+```typescript
+import { createLakebasePool } from '@databricks/appkit';
+
+// Reads from PGHOST, PGDATABASE, LAKEBASE_ENDPOINT env vars
+const pool = createLakebasePool();
+
+// Standard pg.Pool API
+const result = await pool.query('SELECT * FROM users');
+```
+
+**ORM Integration:**
+Works with Drizzle, Prisma, TypeORM - see [Lakebase Integration Docs](docs/docs/integrations/lakebase.md) for examples.
+
+**Architecture:**
+- Connector files: `packages/appkit/src/connectors/lakebase/`
+  - `pool.ts` - Pool factory with OAuth token refresh
+  - `types.ts` - TypeScript interfaces (`LakebasePoolConfig`)
+  - `utils.ts` - Helper functions (`generateDatabaseCredential`)
+  - `auth-types.ts` - Lakebase v2 API types
+
 ### Frontend-Backend Interaction
 
 ```

docs/docs/api/appkit/Enumeration.RequestedClaimsPermissionSet.md

@@ -0,0 +1,13 @@
+# Enumeration: RequestedClaimsPermissionSet
+
+Permission set for Unity Catalog table access
+
+## Enumeration Members
+
+### READ\_ONLY
+
+```ts
+READ_ONLY: "READ_ONLY";
+```
+
+Read-only access to specified UC tables

docs/docs/api/appkit/Function.createLakebasePool.md

@@ -0,0 +1,20 @@
+# Function: createLakebasePool()
+
+```ts
+function createLakebasePool(config?: Partial<LakebasePoolConfig>): Pool;
+```
+
+Create a Lakebase pool with appkit's logger integration.
+Telemetry automatically uses appkit's OpenTelemetry configuration via global registry.
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `config?` | `Partial`\<[`LakebasePoolConfig`](Interface.LakebasePoolConfig.md)\> | Lakebase pool configuration |
+
+## Returns
+
+`Pool`
+
+PostgreSQL pool with appkit integration

docs/docs/api/appkit/Function.generateDatabaseCredential.md

@@ -0,0 +1,55 @@
+# Function: generateDatabaseCredential()
+
+```ts
+function generateDatabaseCredential(workspaceClient: WorkspaceClient, request: GenerateDatabaseCredentialRequest): Promise<DatabaseCredential>;
+```
+
+Generate OAuth credentials for Postgres database connection using the proper Postgres API.
+
+This generates a time-limited OAuth token (expires after 1 hour) that can be used
+as a password when connecting to Lakebase Postgres databases.
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `workspaceClient` | `WorkspaceClient` | Databricks workspace client for authentication |
+| `request` | [`GenerateDatabaseCredentialRequest`](Interface.GenerateDatabaseCredentialRequest.md) | Request parameters including endpoint path and optional UC claims |
+
+## Returns
+
+`Promise`\<[`DatabaseCredential`](Interface.DatabaseCredential.md)\>
+
+Database credentials with OAuth token and expiration time
+
+## See
+
+https://docs.databricks.com/aws/en/oltp/projects/authentication
+
+## Examples
+
+```typescript
+// Format: projects/{project-id}/branches/{branch-id}/endpoints/{endpoint-id}
+// Note: Use actual IDs from Databricks (project-id is a UUID)
+const credential = await generateDatabaseCredential(workspaceClient, {
+  endpoint: "projects/6bef4151-4b5d-4147-b4d0-c2f4fd5b40db/branches/br-sparkling-tree-y17uj7fn/endpoints/ep-restless-pine-y1ldaht0"
+});
+
+// Use credential.token as password
+const conn = await pg.connect({
+  host: "ep-abc123.database.us-east-1.databricks.com",
+  user: "user@example.com",
+  password: credential.token
+});
+```
+
+```typescript
+// Format: projects/{project-id}/branches/{branch-id}/endpoints/{endpoint-id}
+const credential = await generateDatabaseCredential(workspaceClient, {
+  endpoint: "projects/6bef4151-4b5d-4147-b4d0-c2f4fd5b40db/branches/br-sparkling-tree-y17uj7fn/endpoints/ep-restless-pine-y1ldaht0",
+  claims: [{
+    permission_set: RequestedClaimsPermissionSet.READ_ONLY,
+    resources: [{ table_name: "catalog.schema.users" }]
+  }]
+});
+```

docs/docs/api/appkit/Function.getLakebaseOrmConfig.md

@@ -0,0 +1,84 @@
+# Function: getLakebaseOrmConfig()
+
+```ts
+function getLakebaseOrmConfig(config?: Partial<LakebasePoolConfig>): {
+  password: string | () => string | () => Promise<string> | undefined;
+  ssl:   | boolean
+     | {
+     rejectUnauthorized: boolean | undefined;
+   };
+  username: string | undefined;
+};
+```
+
+Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.
+
+Designed for ORMs like TypeORM and Sequelize that need connection parameters
+rather than a pre-configured pool instance.
+
+Returns connection config with field names compatible with common ORMs:
+- `username` instead of `user`
+- Simplified SSL config
+- Password callback support for OAuth token refresh
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `config?` | `Partial`\<[`LakebasePoolConfig`](Interface.LakebasePoolConfig.md)\> | Optional configuration (reads from environment if not provided) |
+
+## Returns
+
+```ts
+{
+  password: string | () => string | () => Promise<string> | undefined;
+  ssl:   | boolean
+     | {
+     rejectUnauthorized: boolean | undefined;
+   };
+  username: string | undefined;
+}
+```
+
+ORM-compatible connection configuration
+
+### password
+
+```ts
+password: string | () => string | () => Promise<string> | undefined;
+```
+
+### ssl
+
+```ts
+ssl: 
+  | boolean
+  | {
+  rejectUnauthorized: boolean | undefined;
+};
+```
+
+### username
+
+```ts
+username: string | undefined = user;
+```
+
+## Example
+
+```typescript
+// TypeORM
+const dataSource = new DataSource({
+  type: 'postgres',
+  ...getLakebaseOrmConfig(),
+  entities: [User],
+  synchronize: true,
+});
+
+// Sequelize
+const sequelize = new Sequelize({
+  dialect: 'postgres',
+  ...getLakebaseOrmConfig(),
+  logging: false,
+});
+```

docs/docs/api/appkit/Function.getLakebasePgConfig.md

@@ -0,0 +1,31 @@
+# Function: getLakebasePgConfig()
+
+```ts
+function getLakebasePgConfig(
+   config?: Partial<LakebasePoolConfig>, 
+   telemetry?: DriverTelemetry, 
+   logger?: Logger): PoolConfig;
+```
+
+Get Lakebase connection configuration for PostgreSQL clients.
+
+Returns pg.PoolConfig with OAuth token authentication configured.
+Best used with pg.Pool directly or ORMs that accept pg.Pool instances (like Drizzle).
+
+For ORMs that need connection parameters (TypeORM, Sequelize), use getLakebaseOrmConfig() instead.
+
+Used internally by createLakebasePool().
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `config?` | `Partial`\<[`LakebasePoolConfig`](Interface.LakebasePoolConfig.md)\> | Optional configuration (reads from environment if not provided) |
+| `telemetry?` | `DriverTelemetry` | Optional pre-initialized telemetry (created internally if not provided) |
+| `logger?` | `Logger` | Optional logger (silent if not provided) |
+
+## Returns
+
+`PoolConfig`
+
+PostgreSQL pool configuration with OAuth token refresh

docs/docs/api/appkit/Function.getWorkspaceClient.md

@@ -0,0 +1,17 @@
+# Function: getWorkspaceClient()
+
+```ts
+function getWorkspaceClient(config: Partial<LakebasePoolConfig>): Promise<WorkspaceClient>;
+```
+
+Get workspace client from config or SDK default auth chain
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `config` | `Partial`\<[`LakebasePoolConfig`](Interface.LakebasePoolConfig.md)\> |
+
+## Returns
+
+`Promise`\<`WorkspaceClient`\>

docs/docs/api/appkit/Interface.DatabaseCredential.md

@@ -0,0 +1,30 @@
+# Interface: DatabaseCredential
+
+Database credentials with OAuth token for Postgres connection
+
+## Properties
+
+### expire\_time
+
+```ts
+expire_time: string;
+```
+
+Token expiration time in UTC (ISO 8601 format)
+Tokens expire after 1 hour from generation
+
+#### Example
+
+```ts
+"2026-02-06T17:07:00Z"
+```
+
+***
+
+### token
+
+```ts
+token: string;
+```
+
+OAuth token to use as the password when connecting to Postgres