Creating Your First Lakebase Project and Database
Who this is for:
Architecture / Concept Overview: Creating Your First Lakebase Project and Database
A Lakebase project is the top-level container for databases, branches, and configurations. Each project can hold multiple databases, and each database supports Git-like branching for development workflows.
%%{init: {"theme":"base","themeVariables":{"background":"#0B0E14","primaryTextColor":"#E0E6ED","lineColor":"#5D6470","darkMode":true,"primaryColor":"#2E4A4A","secondaryColor":"#374151","secondaryTextColor":"#E0E6ED","tertiaryColor":"#111827","tertiaryTextColor":"#E0E6ED","edgeLabelBackground":"#1f2937"}}}%%
graph TD
classDef source fill:#3F4B59,stroke:#9CA3AF,stroke-width:2px,rx:8,ry:8,color:#E0E6ED
classDef ingestion fill:#5A4B36,stroke:#C9A86B,stroke-width:2px,rx:8,ry:8,color:#E0E6ED
classDef processing fill:#535072,stroke:#8E82B4,stroke-width:2px,rx:8,ry:8,color:#E0E6ED
classDef storage fill:#2E4A4A,stroke:#5FAFA8,stroke-width:2px,rx:8,ry:8,color:#E0E6ED
classDef serving fill:#3D5550,stroke:#6BB7AA,stroke-width:2px,rx:8,ry:8,color:#E0E6ED
classDef governance fill:#5A3F52,stroke:#C28BB0,stroke-width:2px,rx:8,ry:8,color:#E0E6ED
A[Workspace] --> B[Lakebase Project]
B --> C[Database: production]
B --> D[Database: staging]
C --> E[Branch: main]
C --> F[Branch: feature/user-auth]
D --> G[Branch: main]
E --> H[Tables & Schemas]
F --> I[Tables & Schemas]
A:::governance
B:::processing
C:::storage
D:::storage
E:::ingestion
F:::ingestion
G:::ingestion
H:::source
I:::source
*Lakebase organizes resources hierarchically: workspace → project → database → branch → tables.*
%%{init: {"theme":"base","themeVariables":{"background":"#0B0E14","primaryTextColor":"#E0E6ED","lineColor":"#5D6470","darkMode":true,"primaryColor":"#2E4A4A","secondaryColor":"#374151","secondaryTextColor":"#E0E6ED","tertiaryColor":"#111827","tertiaryTextColor":"#E0E6ED","edgeLabelBackground":"#1f2937"}}}%%
flowchart LR
classDef source fill:#3F4B59,stroke:#9CA3AF,stroke-width:2px,rx:8,ry:8,color:#E0E6ED
classDef ingestion fill:#5A4B36,stroke:#C9A86B,stroke-width:2px,rx:8,ry:8,color:#E0E6ED
classDef processing fill:#535072,stroke:#8E82B4,stroke-width:2px,rx:8,ry:8,color:#E0E6ED
classDef storage fill:#2E4A4A,stroke:#5FAFA8,stroke-width:2px,rx:8,ry:8,color:#E0E6ED
classDef serving fill:#3D5550,stroke:#6BB7AA,stroke-width:2px,rx:8,ry:8,color:#E0E6ED
classDef governance fill:#5A3F52,stroke:#C28BB0,stroke-width:2px,rx:8,ry:8,color:#E0E6ED
A[Create Project] --> B[Create Database]
B --> C[Define Schema & Tables]
C --> D[Insert Seed Data]
D --> E[Connect from Client]
E --> F[Enable Unity Catalog Sync]
A:::processing
B:::storage
C:::source
D:::ingestion
E:::serving
F:::governance
*The setup workflow progresses from project creation through schema definition, data seeding, and optional Unity Catalog sync.*
Key Terms
Prerequisites and Setup
- A Databricks workspace with Lakebase enabled
- Workspace admin or account admin privileges
- Access to the Databricks UI or the Databricks CLI
- A PostgreSQL client installed locally (
psql, DBeaver, or pgAdmin) for connection testing
Step-by-Step Implementation
Configuration Reference
| Parameter | Description | Default |
|---|---|---|
project.name | Unique project identifier (alphanumeric and underscores) | Required |
project.comment | Human-readable description of the project | Empty |
database.name | Database name within the project | Required |
database.default_branch | The branch used for new connections | main |
compute.size | Instance size for the Lakebase engine | small |
compute.auto_suspend | Minutes of inactivity before suspending compute | 15 |
networking.allowed_ips | CIDR ranges allowed to connect | All (workspace default) |