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.