feat: split out @databricks/lakebase-auth with eager refresh and retry

.github/workflows/prepare-release-lakebase-auth.yml

@@ -0,0 +1,110 @@
+name: Prepare Release Lakebase Auth
+
+on:
+ push:
+ branches:
+ - main
+ paths:
+ - 'packages/lakebase-auth/**'
+
+concurrency:
+ group: prepare-release-lakebase-auth
+ cancel-in-progress: false
+
+permissions:
+ contents: read
+ id-token: write
+
+jobs:
+ prepare:
+ runs-on:
+ group: databricks-protected-runner-group
+ labels: linux-ubuntu-latest
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ fetch-depth: 0
+
+ - name: Setup JFrog npm
+ uses: ./.github/actions/setup-jfrog-npm
+
+ - name: Setup pnpm
+ uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+
+ - name: Setup Node.js
+ uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+ with:
+ node-version: 24
+ cache: "pnpm"
+
+ - name: Install dependencies
+ run: pnpm install --frozen-lockfile
+
+ - name: Check for releasable commits
+ id: version
+ working-directory: packages/lakebase-auth
+ run: |
+ VERSION=$(pnpm exec release-it --release-version --ci) || true
+ if [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+ echo "Next version: $VERSION"
+ else
+ echo "No releasable commits — skipping release preparation"
+ echo "version=" >> "$GITHUB_OUTPUT"
+ fi
+
+ - name: Generate changelog
+ if: steps.version.outputs.version != ''
+ working-directory: packages/lakebase-auth
+ run: |
+ pnpm exec release-it ${{ steps.version.outputs.version }} --ci
+
+ - name: Sync version
+ if: steps.version.outputs.version != ''
+ run: pnpm exec tsx tools/sync-lakebase-auth-version.ts "${{ steps.version.outputs.version }}"
+
+ - name: Build
+ if: steps.version.outputs.version != ''
+ run: pnpm --filter=@databricks/lakebase-auth build:package
+
+ - name: Dist
+ if: steps.version.outputs.version != ''
+ run: pnpm --filter=@databricks/lakebase-auth dist
+
+ - name: SBOM
+ if: steps.version.outputs.version != ''
+ run: pnpm --filter=@databricks/lakebase-auth release:sbom
+
+ - name: Pack
+ if: steps.version.outputs.version != ''
+ run: npm pack packages/lakebase-auth/tmp
+
+ - name: Generate SHA256
+ if: steps.version.outputs.version != ''
+ run: sha256sum *.tgz > SHA256SUMS
+
+ - name: Write version file
+ if: steps.version.outputs.version != ''
+ run: echo "${{ steps.version.outputs.version }}" > VERSION
+
+ - name: Upload release metadata
+ if: steps.version.outputs.version != ''
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+ with:
+ name: lakebase-auth-release-meta-${{ github.run_number }}
+ retention-days: 7
+ path: VERSION
+
+ - name: Upload release artifacts
+ if: steps.version.outputs.version != ''
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+ with:
+ name: lakebase-auth-release-${{ github.run_number }}
+ retention-days: 7
+ path: |
+ *.tgz
+ packages/lakebase-auth/changelog-diff.md
+ VERSION
+ SHA256SUMS

.gitignore

@@ -4,6 +4,10 @@ tmp
 node_modules
 .env
 
+# Generated by tools/prepare-template-artifact.ts (CI artifact staging dir)
+pr-template
+appkit-template-*.zip
+
 coverage
 
 *.tsbuildinfo
@@ -13,3 +17,5 @@ coverage
 .databricks
 
 .claude/scheduled_tasks.lock
+
+.cursor/

CLAUDE.md

@@ -28,7 +28,8 @@ Examples:
 /packages/
  /appkit/ - Core SDK with plugin architecture
  /appkit-ui/ - React components and JS utilities
- /lakebase/ - Standalone Lakebase (PostgreSQL) connector package
+ /lakebase/ - Standalone Lakebase (PostgreSQL) connector package (pg.Pool + OTel)
+ /lakebase-auth/ - Driver-agnostic Lakebase OAuth credential/token-refresh package (SDK-only deps)
  /shared/ - Shared TypeScript types across packages
 
 /apps/
@@ -144,7 +145,7 @@ pnpm clean:full # Remove build artifacts + node_modules
 
 ### Releasing
 
-This project uses a two-stage release pipeline. Both packages (`appkit` and `appkit-ui`) are always released together with the same version. `@databricks/lakebase` is released independently.
+This project uses a two-stage release pipeline. Both packages (`appkit` and `appkit-ui`) are always released together with the same version. `@databricks/lakebase` and `@databricks/lakebase-auth` are each released independently.
 
 #### Stage 1: Prepare (this repo)
 
@@ -154,7 +155,7 @@ The `prepare-release` workflow runs automatically on push to `main`:
 3. Builds, packs, and uploads artifacts (`.tgz`, changelog, SHA256 digests)
 4. **Does NOT** commit, tag, push, or publish — only uploads artifacts
 
-Lakebase has a separate `prepare-release-lakebase` workflow triggered by changes to `packages/lakebase/**`.
+Lakebase has a separate `prepare-release-lakebase` workflow triggered by changes to `packages/lakebase/**`, and `@databricks/lakebase-auth` has a `prepare-release-lakebase-auth` workflow triggered by changes to `packages/lakebase-auth/**`.
 
 #### Stage 2: Publish (secure repo)
 
@@ -248,10 +249,11 @@ The AnalyticsPlugin provides SQL query execution:
 
 ### Lakebase Connector
 
-Lakebase support is split into two layers:
+Lakebase support is split into three layers:
 
-1. **`@databricks/lakebase` package** (`packages/lakebase/`) - Standalone connector with OAuth token refresh, ORM helpers, and full API. See the [`@databricks/lakebase` README](https://github.com/databricks/appkit/blob/main/packages/lakebase/README.md).
-2. **AppKit integration** (`packages/appkit/src/connectors/lakebase/`) - Thin wrapper that adds AppKit logger integration and re-exports the standalone package.
+1. **`@databricks/lakebase-auth` package** (`packages/lakebase-auth/`) - Driver-agnostic OAuth credential generation and token refresh (eager by default, plus lazy; retries transient failures). Dependency-light (Databricks SDK only, no `pg`/OTel). Exposes `getPgConfig()` and the low-level `createPasswordProvider()` for use with `pg`, `postgres.js`, `Bun.SQL`, etc. See the [`@databricks/lakebase-auth` README](https://github.com/databricks/appkit/blob/main/packages/lakebase-auth/README.md).
+2. **`@databricks/lakebase` package** (`packages/lakebase/`) - Builds on `@databricks/lakebase-auth` to provide a ready-to-use `pg.Pool` (`createLakebasePool`) with OpenTelemetry instrumentation and logger integration, plus ORM helpers. See the [`@databricks/lakebase` README](https://github.com/databricks/appkit/blob/main/packages/lakebase/README.md).
+3. **AppKit integration** (`packages/appkit/src/connectors/lakebase/`) - Thin wrapper that adds AppKit logger integration and re-exports the standalone package.
 
 **Quick Example:**
 ```typescript

docs/docs/plugins/lakebase.md

@@ -8,11 +8,14 @@ Provides a PostgreSQL connection pool for Databricks Lakebase Autoscaling with a
 
 **Key features:**
 - Standard `pg.Pool` compatible with any PostgreSQL library or ORM
-- Automatic OAuth token refresh (1-hour tokens, 2-minute refresh buffer)
+- Automatic OAuth token refresh (1-hour tokens, 2-minute refresh buffer) — eager (background) by default, or lazy (on-demand)
+- Retries transient credential-fetch failures
 - Token caching to minimize API calls
 - Built-in OpenTelemetry instrumentation (query duration, pool connections, token refresh)
 - AppKit logger configured by default for query and connection events
 
+The underlying OAuth credential generation and token-refresh logic lives in the lightweight, driver-agnostic [`@databricks/lakebase-auth`](https://www.npmjs.com/package/@databricks/lakebase-auth) package, which can also be used standalone with `pg`, `postgres.js`, or `Bun.SQL`.
+
 ## Getting started with the Lakebase
 
 The easiest way to get started with the Lakebase plugin is to use the Databricks CLI to create a new Databricks app with AppKit installed and the Lakebase plugin.

packages/appkit/src/plugins/lakebase/manifest.json

@@ -74,7 +74,7 @@
  "sslmode": {
  "env": "PGSSLMODE",
  "localOnly": true,
- "value": "require",
+ "value": "verify-full",
  "description": "Postgres SSL mode. Auto-injected by the platform at deploy time."
  }
  }

packages/appkit/tsconfig.json

@@ -7,7 +7,8 @@
  "@/*": ["src/*"],
  "@tools/*": ["../../tools/*"],
  "shared": ["../../packages/shared/src"],
- "@databricks/lakebase": ["../../packages/lakebase/src"]
+ "@databricks/lakebase": ["../../packages/lakebase/src"],
+ "@databricks/lakebase-auth": ["../../packages/lakebase-auth/src"]
  }
  },
  "include": ["src/**/*"],

packages/lakebase-auth/.release-it.json

@@ -0,0 +1,32 @@
+{
+ "$schema": "https://unpkg.com/release-it@19/schema/release-it.json",
+ "git": {
+ "commit": false,
+ "tag": false,
+ "push": false,
+ "requireBranch": false,
+ "requireCleanWorkingDir": false,
+ "requireCommits": true,
+ "requireCommitsFail": false,
+ "tagMatch": "lakebase-auth-v*",
+ "tagName": "lakebase-auth-v${version}",
+ "getLatestTagFromAllRefs": true,
+ "commitsPath": "."
+ },
+ "github": {
+ "release": false
+ },
+ "npm": false,
+ "hooks": {},
+ "plugins": {
+ "@release-it/conventional-changelog": {
+ "preset": {
+ "name": "conventionalcommits",
+ "bumpStrict": true
+ },
+ "infile": "changelog-diff.md",
+ "gitRawCommitsOpts": { "path": "." },
+ "commitsOpts": { "path": "." }
+ }
+ }
+}

packages/lakebase-auth/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+All notable changes to @databricks/lakebase-auth will be documented in this file.