databricks-lakebase
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.
By databricks · 761 installs
npx skills add databricks/databricks-agent-skills --skill databricks-lakebase
Source repository · Upstream listing
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 AWS and Azure (GA) and on GCP (Beta). It provides fully managed OLTP storage with autoscaling, branching, and scale to zero.
Regions: Lakebase runs only in the commercial regions listed in [Region availability](https://docs.databricks.com/oltp/projects/manage projects availability) (check the page for the user's cloud). It isn't available on AWS GovCloud, and the Azure list has no Azure Government or Azure China regions. If the workspace is in one of these clouds or an unlisted region, tell the user that Lakebase isn't available there. Don't try to create a project.
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, and migrate to the postgres resource key. For the legacy DAB synced database tables resource, use the postgres synced tables bundle resource or 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 (GA), GCP (Beta)
Compliance: Supports HIPAA, C5, TISAX, or None. Before any PHI goes into Lakebase, apply the HIPAA gate below.
HIPAA Gate (PHI)
HIPAA coverage comes from the workspace: the compliance security profile with the HIPAA standard, plus a Business Associate Agreement. Confirm both with the user before PHI goes in. Then:
Preview features: do not use a Preview or Beta feature (for example, Lakehouse Sync) for PHI unless it is listed for your region in [Regional support for features](https://docs.databricks.com/aws/en/security/privacy/hipaa). Check the list each time.
Existing projects: a project that was running when HIPAA was turned on has no HIPAA audit logging until its compute restarts. Databricks does not restart it for you. Restart each compute.
No PHI in metadata: never put PHI in database, schema, table, column, or role names, in tags, or in other customer defined fields. These appear in audit logs and system metadata, and Databricks cannot remove them later.
No PHI in SQL text: pass PHI values as query parameters, never as literals. Audit logs record statement text.
No PHI in logs or tickets: keep PHI out of app logs, error messages, screenshots, diagnostic output, and support requests.
Least privilege: grant each role only the schemas, tables, and operations it needs.
Sources: [HIPAA compliance for Lakebase](https://docs.databricks.com/aws/en/oltp/projects/hipaa compliance), [Enable HIPAA compliance](https://docs.databricks.com/aws/en/oltp/projects/enable hipaa compliance).
Row Level Security and Data API: Must Follow Rules
Apply these whenever a design has per user rows, RLS, or the Data API. Details and tests are in [connectivity.md](references/connectivity.md).
Many end users: a branch holds at most 500 Postgres roles. Never create one role per app user. The app connects as its service principal over a pool and sets the user per transaction: SELECT set config('app.user', $1, true) .
RLS on a setting: wrap it in NULLIF : USING (owner email = (SELECT NULLIF(current setting('app.user', true), ''))) . On a reused pooled connection, an unset value reads '' , not NULL. Also run ALTER TABLE ... FORCE ROW LEVEL SECURITY , because the table owner bypasses RLS otherwise.
Testing RLS: never test as the project owner or databricks superuser , and never grant databricks superuser to a teammate for local work. Both bypass RLS. Use a role with only USAGE on the app's schema and the table privileges it needs.
Views over RLS tables: create them WITH (security invoker = true) , and grant the caller SELECT on the base table too. A default view checks RLS as its owner, so every caller sees all rows.
Data API before production: the defaults are open. Empty CORS origins means all origins, and empty maximum rows means no limit. Set the exact app origins and a row limit, and expose only the schema built for the API, not public .
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 64 CU, fixed up to 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), GCP (Beta)
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. 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:
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.
Auto creates: production branch + primary read write endpoint with scale to zero on (24 h timeout). The documented default size is 8–16 CU (autoscaling), but a project created with the CLI can get a 1 CU min/max endpoint instead. Check the size with get endpoint and resize with update endpoint if the workload needs more. Long running operation; CLI waits by default. Use no wait to return immediately.
After creation, verify:
Extract connection values from JSON output:
Value JSON path Used for
Endpoint host status.hosts.host PGHOST , lakebase.postgres.host
Endpoint resource path name LAKEBASE ENDPOINT , lakebase.postgres.endpointPath
Database resource path name lakebase.postgres.database
PostgreSQL database name status.postgres database PGDATABASE , lakebase.postgres.databaseName
Updating a Project
Deleting a Project
WARNING: Permanent deletes all branches, computes, databases, roles, and data. Do not delete without explicit user permission.
Autoscaling
Endpoints use compute units (CU) (~2 GB RAM per CU). Range: 0.5 64 CU (autoscaling or fixed), 65 112 CU (fixed only). Scale to zero enabled by default on every branch, including production (24 h timeout; computes ≤ 32 CU only).
See [computes and scaling.md](references/computes and scaling.md) for sizing tables, endpoint CRUD, and configuration details.
Branches
Branches are copy on write snapshots. Use for testing schema migrations, trying queries, or previewing data changes without affecting production.
Branches require an expiration policy: "no expiry": true for permanent, or "ttl": "<seconds s" (max 30 days).
Limits: 500 branches per project. Per branch storage quota is adjustable on request (contact Databricks Support). 500 Postgres roles per branch. 1,000 projects per workspace. For apps with many end users, do not create one role per user; see "Many Users: Roles and RLS at Scale" in [connectivity.md](references/connectivity.md).
Use Case TTL
CI/CD environments 2 4 hours ( "ttl": "14400s" )
Demos 24 48 hours ( "ttl": "172800s" )
Feature development 1 7 days ( "ttl": "604800s" )
Long term testing Up to 30 days ( "ttl": "2592000s" )
Point in time branching: Create from a past state (within restore window) for recovery. The time specification fields live inside the json spec ( spec.source branch time , spec.source branch lsn ), not as top level create branch flags.
Reset: Replaces branch data and schema with the latest from its parent. Local changes are lost. Root branches and branches with children cannot be reset; protected branches ( spec.is protected ) cannot be reset either.
Reset is UI only — there is no databricks postgres reset branch CLI command and no API/SDK method for it. In the Lakebase App, go to the project's Branches page, click the menu next to the branch, and select Reset from parent .
CLI workarounds:
Delete + recreate: delete branch , then create branch with spec.source branch set to the parent (unprotect via update branch first if protected).
Point in time: create branch with spec.source branch time or spec.source branch lsn . Timestamp based reset is not supported; use PITR branching instead.
Delete: Protected branches must be unprotected first ( update branch to set spec.is protected to false ). Cannot delete branches with children. Never delete the production branch.
What's Next
Build a Databricks App
After creating a project, scaffold a connected Databricks App:
For the full app workflow, use the databri