Manage database projects

Beta

Lakebase Postgres (Autoscaling Beta) is the next version of Lakebase, available for evaluation only. For production workloads, use Lakebase Public Preview. See choosing between versions to understand which version is right for you.

A database project is the top-level container for your Lakebase resources, including branches, computes, databases, and roles. This page explains how to create projects, understand their structure, configure settings, and manage their lifecycle.

If you're new to Lakebase, start with Get started to create your first project.

Database project structure

Understanding the Lakebase project structure helps you organize and manage your resources effectively. A database project is the top-level container for your databases, branches, computes, and related resources. Each project includes settings for compute defaults, restore windows, and updates that apply to all branches within the project.

At the top level, a project contains one or more branches. Within a project, you can create branches for different environments such as development, testing, staging, and production. Each branch contains its own computes, roles, and databases.

Project
  └── Branches (production, development, etc.)
        ├── Computes (R/W compute)
        ├── Roles (Postgres roles)
        └── Databases (Postgres databases)

Branches

Data resides in branches. Each Lakebase project is created with a root branch called production, which cannot be deleted. While you can create additional branches and designate a different branch as your default branch, the root branch cannot be deleted.

You can create child branches from any branch in your project. When you create a child branch, it inherits all databases, roles, and data from its parent branch at the time of creation. Subsequent changes in the parent branch don't automatically propagate to the child branch, enabling isolated development, testing, or experimentatation.

Each branch can contain multiple databases and roles. Learn more: Manage branches

Computes

A compute is a virtualized computing resource that includes vCPU and memory for running Postgres. When you create a project, a primary R/W (read-write) compute is created for the project's default branch. Each branch has a single primary R/W compute. To connect to a database that resides on a branch, you must connect through the R/W compute associated with the branch.

In addition to the primary R/W compute, you can add one or more read replica (read-only) computes to any branch. Read replicas enable you to offload read-only workloads from your primary compute for use cases such as horizontal read scaling, analytics and reporting queries, and read-only access for users or applications. Learn more: Manage computes, Read replicas

Roles

Roles are Postgres roles. A role is required to create and access a database. A role belongs to a branch. When you create a project, a Postgres role is automatically created for your Databricks identity (for example, user@databricks.com), which is the owner of the default databricks_postgres database. Any role created in the Lakebase UI is created with databricks_superuser privileges. There is a limit of 500 roles per branch. Learn more: Manage roles

Databases

A database is a container for SQL objects such as schemas, tables, views, functions, and indexes. In Lakebase, a database belongs to a branch. The default branch of your project is created with a database named databricks_postgres. There is a limit of 500 databases per branch. Learn more: Manage databases

Schemas

All databases in Lakebase are created with a public schema, which is the default behavior for any standard Postgres instance. SQL objects are created in the public schema by default.

Project limits

Lakebase Postgres enforces the following limits for database projects:

Resource	Limit
Maximum number of concurrently active computes	5
Maximum number of branches per project	500
Maximum number of Postgres roles per branch	500
Maximum number of Postgres databases per branch	500
Maximum logical data size per branch	8 TB
Maximum number of projects per workspace	1000
Maximum number of protected branches	5
Maximum number of root branches	5
Maximum number of snapshots	10
Maximum history retention period	35 days
Minimum scale to zero time	60 seconds

Concurrently active compute limit

The concurrently active compute limit caps how many computes can run at the same time to prevent resource exhaustion. This limit protects against accidental resource surges, such as starting many compute endpoints at once. The default limit is 5 concurrently active computes per project.

Important: The default branch is exempt from this limit, ensuring it remains available at all times.

When you exceed the limit, additional computes beyond the limit remain suspended and you see an error when attempting to connect to them. To resolve this:

1. Suspend other active computes and try again.
2. If you encounter this error often, contact Databricks Support to request a limit increase.

note

Computes with scale to zero enabled automatically suspend after a period of inactivity, helping you stay within the concurrently active compute limit.

Availability

Cloud availability

Lakebase Postgres (Beta) is currently available only on AWS.

Region availability

Lakebase Postgres (Beta) is available in the following AWS regions:

• us-east-1 (US East - N. Virginia)
• us-west-2 (US West - Oregon)
• eu-west-1 (Europe - Ireland)

Your Lakebase project is created in your Databricks workspace region.

Postgres version support

Lakebase Postgres (Autoscaling Beta) supports Postgres 16 and Postgres 17.

Create a database project

You can create multiple database projects in Lakebase Postgres to keep applications or customers fully isolated, ensuring clean separation of data and resources.

To create a database project:

1. Click the apps switcher in the top right corner to open the Lakebase App.
2. Click New project.
3. Configure your project settings:
   • Project name: Enter a descriptive name for your project. Common naming patterns include naming after the application (for example, my-analytics-app) or the customer or tenant the project serves (for example, acme-corp-db).
   • Postgres version: Select the Postgres version you want to use.

The Create project dialog shows the project configuration options.

The Region for your Lakebase project is set to your Databricks workspace region and cannot be modified.

A new project includes the following resources by default:

• Two branches: production (main branch) and development (child branch)

• A single primary read-write compute associated with each branch with the following default settings:

  Branch	Compute Units (CU)	RAM	Autoscaling	Scale-to-zero
  production	8 - 32 CU	16 - 64 GB	Enabled	Disabled
  development	2 - 4 CU	4 - 8 GB	Enabled	Enabled

• A Postgres database (named databricks_postgres)

• A Postgres role for your Databricks identity (for example, user@databricks.com)

To change compute settings for an existing project, see Configure project settings. To modify default compute settings for new projects, see Compute defaults in Configure project settings.

Configure project settings

After creating a project, you can modify various settings from the project dashboard by navigating to Settings:

General settings

You can update the project name. The project ID cannot be modified.

Compute defaults

Set initial settings for primary computes, including:

• Compute size (measured in Compute Units)
• Scale to zero timeout (default is 5 minutes)

These settings are used when you create new primary computes.

note

To modify settings for an existing compute, see Manage computes.

Lakebase Postgres supports compute sizes from 0.5 CU to 32 CU (0.5, then integer increments: 1, 2, 3... 16, then 24, 28, 32). Each Compute Unit (CU) provides 2 GB of RAM.

note

Lakebase Public Preview vs Autoscaling Beta: In Lakebase Public Preview, each Compute Unit allocated approximately 16 GB of RAM. In Lakebase Autoscaling Beta, each CU allocates 2 GB of RAM. This change provides more granular scaling options and cost control.

Representative sizes:

Compute Units	RAM
0.5 CU	1 GB
1 CU	2 GB
4 CU	8 GB
16 CU	32 GB
32 CU	64 GB

• To enable autoscaling, set a compute size range using the slider. Autoscaling dynamically adjusts compute resources based on workload demand. Learn more: Autoscaling
• Adjust the scale-to-zero setting to increase or decrease the amount of inactive compute time before a compute suspends. You can also disable scale-to-zero for an always-active compute. Learn more: Scale to zero

Instant restore

Configure the restore window length for your project. By default, Lakebase retains a history of changes for all branches in your project, enabling point-in-time restore for recovering lost data, time travel queries for investigating data issues, and branching from past states for development workflows.

You can set the restore window from 2 days up to 35 days. Note that:

• Extending the restore window increases your storage
• The restore window setting affects all branches in your project

Updates

To keep your Lakebase computes and Postgres instances up to date, Lakebase automatically applies scheduled updates that include Postgres minor version upgrades, security patches, and platform features. Updates are applied to the computes within your project and require a brief compute restart that takes only a few seconds.

Updates are applied automatically, but you can set a preferred day and time for updates. Restarts occur within your selected time window.

For detailed information about updates, see Updates.

Delete a project

Deleting a project is a permanent action that also deletes any computes, branches, databases, roles, and data that belong to the project.

important

This action cannot be undone. Be cautious when deleting a database project, as doing so deletes all associated branches and data.

Before deleting

Databricks recommends deleting all associated Unity Catalog catalogs and synced tables before deleting the database project. Otherwise, attempting to view catalogs or run SQL queries that reference them results in errors.

If you are not the owner of the tables or catalogs, you must reassign ownership to yourself before deletion.

note

In Lakebase Autoscaling Beta, any Databricks identity with access to the workspace where the database project was created can delete database projects.

Delete a project

To delete a project:

1. Navigate to your database project's Settings in the Lakebase App.
2. In the Delete project section, click Delete and enter the project name to confirm deletion.