/databricks-lakebase

name: databricks-lakebase
description: "Databricks Lakebase Postgres: projects, scaling, connectivity, Lakebase synced tables, and Data API. Use when asked about Lakebase databases, OLTP storage, or connecting apps to Postgres on Databricks."
compatibility: Requires databricks CLI (>= v0.294.0)
metadata:
  version: "0.1.0"
parent: databricks-core

Lakebase Postgres Autoscaling

**FIRST**: Use the parent `databricks-core` skill for CLI basics, authentication, and profile selection.

Lakebase is Databricks' serverless Postgres-compatible database, available on both AWS and Azure (GA). It provides fully managed OLTP storage with autoscaling, branching, and scale-to-zero.

> **Provisioned Lakebase no longer exists — never create it.** The old Provisioned tier (static, non-scalable Postgres; `databricks database` CLI / `w.database` SDK) is being migrated to Autoscaling over summer 2026, with no customer action required. Lakebase today is Autoscaling-only (`databricks postgres` / `w.postgres`). Do not attempt to create Provisioned instances; if a user asks for one, tell them Provisioned instances don't exist anymore and point them to Autoscaling. Treat the legacy `database` resource key in app configs as retired — migrate to the `postgres` resource key. For the legacy DAB `synced_database_tables` resource, use the `databricks postgres create-synced-table` CLI flow instead (see the Common Issues row and `references/synced-tables.md`).

For context when reading older configs or docs, here is how the retired Provisioned tier maps to Autoscaling:

| Aspect | Provisioned (retired) | Autoscaling (current) | |--------|-----------------------|-----------------------| | CLI group | `databricks database` | `databricks postgres` | | Top-level resource | Instance | Project | | Capacity | CU_1–CU_8 (16 GB/CU) | 0.5–112 CU (2 GB/CU) | | Branching | Not supported | Full support | | Scale-to-zero | Not supported | Configurable | | HA | Readable secondaries | 1–3 secondaries + read replicas | | Data API | Not available | PostgREST HTTP API | | Cloud | AWS only | AWS and Azure |

**Compliance:** Supports HIPAA, C5, TISAX, or None.

Capabilities

• **Project lifecycle** -- create, update, delete Lakebase Postgres Autoscaling projects
• **Branching** -- copy-on-write branches with TTL, point-in-time recovery, and reset
• **Compute scaling** -- autoscale 0.5--32 CU, fixed 36--112 CU, scale-to-zero
• **High availability** -- 1 primary + 1--3 secondaries, automatic failover
• **PostgreSQL connectivity** -- OAuth token refresh, connection pooling, SSL
• **Data API** -- PostgREST-compatible HTTP CRUD (Autoscaling only)
• **Lakebase synced tables** -- sync Unity Catalog Delta tables into Postgres (previously known as Reverse ETL)
• **Databricks App integration** -- scaffold apps with Lakebase feature, deploy-first workflow
• **Cloud support** -- AWS and Azure (GA)

**Reference docs:**

• [computes-and-scaling.md](references/computes-and-scaling.md) — Sizing, endpoint management, scale-to-zero, HA
• [connectivity.md](references/connectivity.md) — Connection patterns, token refresh, Data API
• [synced-tables.md](references/synced-tables.md) — Lakebase synced tables, data type mapping, capacity planning
• [lakehouse-sync.md](references/lakehouse-sync.md) — CDC from Lakebase Postgres to Unity Catalog Delta tables (programmable via `databricks postgres *-cdf-config` / `w.postgres.*_cdf_config`, Beta)
• [pgvector.md](references/pgvector.md) — Vector similarity search with pgvector extension
• [off-platform.md](references/off-platform.md) — Off-platform Lakebase (NOT Databricks Apps): external Node.js apps connecting via `@databricks/lakebase`, env management, token refresh, Drizzle ORM

Resource Hierarchy

Project (top-level container)
  └── Branch (isolated database environment, copy-on-write)
        ├── Endpoint (read-write or read-only)
        ├── Database (standard Postgres DB)
        └── Role (Postgres role)

• **Project**: Top-level container. Creating one auto-provisions a `production` branch and a `primary` read-write endpoint.
• **Branch**: Isolated database environment sharing storage with parent (copy-on-write). States: `READY`, `ARCHIVED`.
• **Endpoint** (called **Compute** in UI): Compute resource powering a branch. Types: `ENDPOINT_TYPE_READ_WRITE`, `ENDPOINT_TYPE_READ_ONLY`.
• **Database**: Standard Postgres database within a branch. Default: `databricks_postgres`.
• **Role**: Postgres role within a branch.

Resource Name Formats

| Resource | Format | |----------|--------| | Project | `projects/{project_id}` | | Branch | `projects/{project_id}/branches/{branch_id}` | | Endpoint | `projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}` | | Database | `projects/{project_id}/branches/{branch_id}/databases/{database_id}` |

All IDs: 1-63 characters, start with lowercase letter, lowercase letters/numbers/hyphens only (RFC 1123).

CLI Discovery -- ALWAYS Do This First

> **Note:** "Lakebase" is the product name; the CLI command group is `postgres`. All commands use `databricks postgres ...`.

**Do NOT guess command syntax.** Discover available commands dynamically:

databricks postgres -h                    # List all subcommands
databricks postgres <subcommand> -h       # Flags, args, JSON fields

Create a Project

> **First decide: reuse or create.** When building or attaching to an app, ask the user whether to reuse an existing project/branch/database — list them with `databricks postgres list-projects` (then `list-branches` / `list-databases`), let the user pick, and confirm which schema the app will own — or create a new project. Only skip listing and create directly when the user explicitly asked for a brand-new project.

databricks postgres create-project <PROJECT_ID> \
  --json '{"spec": {"display_name": "<DISPLAY_NAME>"}}' \
  --profile <PROFILE>

Auto-creates: `production` branch + `primary` read-write endpoint (1 CU min/max, scale-t