lakebase-autoscaling

lakebase-autoscaling

A Claude Code plugin for managing Databricks Lakebase Postgres on the Autoscaling tier — projects, branches, endpoints, scaling, and connections — without memorizing JSON shapes or CLI flags.

> Scope: Autoscaling tier only (databricks postgres). The legacy Provisioned tier (databricks database) is intentionally out of scope.

What it does

• Six slash commands for the full Lakebase Autoscaling lifecycle: create, connect, scale, branch, status, destroy.
• One skill (lakebase-autoscaling-guide) that auto-loads when you ask about Lakebase, Postgres on Databricks, branching, scale-to-zero, or compute units.
• Helper scripts that fetch host + OAuth token + user email and exec psql for you (with brew-PATH fallback the built-in databricks psql doesn't have).
• Progressive-disclosure references for connecting (psql/psycopg/SQLAlchemy), branching, scaling guidance, the Data API, Unity Catalog integration (REST/SDK — Autoscaling has no databricks CLI subcommand for UC yet), and troubleshooting.

Prerequisites

| Requirement | Why | How | |---|---|---| | Databricks CLI 0.285.0+ | Autoscaling commands are gated on this version | brew install databricks (then databricks --version) | | Authenticated profile | All commands take -p PROFILE | databricks auth login --host <workspace-url> --profile <name> | | psql 17+ (optional) | Needed for /lakebase-connect and DDL. Match the server (Lakebase runs PG17) — psql 16 works for SELECT/CREATE but breaks meta-commands like \l against a PG17 server. | brew install postgresql@17 | | jq | Used by helper scripts | brew install jq |

A workspace with Lakebase Postgres enabled is required. Ask your Databricks workspace admin if unsure.

Installation

Install from a local clone or git URL via the Claude Code marketplace:

# Clone
git clone https://github.com/<owner>/lakebase-autoscaling.git
claude plugin marketplace add ./lakebase-autoscaling
claude plugin install lakebase-autoscaling@lakebase-autoscaling

# Or directly from a git URL
claude plugin marketplace add https://github.com/<owner>/lakebase-autoscaling.git
claude plugin install lakebase-autoscaling@lakebase-autoscaling

Verify it loaded: type / and look for the lakebase-* commands.

Quick start

# 1. Create a project (auto-creates `production` branch + `primary` endpoint)
/lakebase-create my-app --profile my-profile

# 2. Open a psql shell — shortest path is the built-in CLI wrapper
databricks psql --project my-app -p my-profile

#    Or use this plugin's command for --export (env vars), Python services, custom DB:
/lakebase-connect projects/my-app/branches/production/endpoints/primary

# 3. Branch off production for dev work
/lakebase-branch my-app dev --from production

# 4. Bump capacity for a load test (max - min ≤ 16 CU)
/lakebase-scale projects/my-app/branches/production/endpoints/primary --min 1 --max 8

# 5. See state at a glance
/lakebase-status my-app

# 6. Tear down (with confirmation)
/lakebase-destroy projects/my-app

Commands

| Command | Purpose | |---|---| | /lakebase-create <project-id> | Create a project; verify production branch + primary endpoint reach ACTIVE. | | /lakebase-connect <endpoint-path> | Fetch host + OAuth token + user email; print env vars or exec psql. | | /lakebase-scale <endpoint-path> | Update autoscaling_limit_min_cu / autoscaling_limit_max_cu (range 0.5–32). | | /lakebase-branch <project> <branch> | Branch from a source (default production) and attach an endpoint. | | /lakebase-status <project> | List branches + endpoints with current state. | | /lakebase-destroy <path> | Delete a project or branch with explicit confirmation. |

Skill

The bundled skill lakebase-autoscaling-guide activates automatically when you mention Lakebase, Postgres on Databricks, scale-to-zero, compute units, branching, or the databricks postgres CLI. It teaches Claude:

• The Autoscaling resource hierarchy: Project > Branch > Endpoint.
• That databricks psql does not work on Autoscaling (use direct psql with an OAuth token).
• That OAuth tokens expire after 1 hour and must be regenerated.
• That you must CREATE DATABASE before tables — the default postgres database has a restricted public schema.
• Sizing guidance for min_cu / max_cu based on workload.

Deep references live under skills/lakebase-autoscaling-guide/references/ and load only when relevant.

Resources

• Lakebase docs: https://docs.databricks.com/aws/en/oltp/
• Databricks CLI: https://docs.databricks.com/dev-tools/cli/index.html
• Issues / PRs: open in this repo.

License

MIT — see LICENSE.