Manage branches

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.

Create and manage database branches to support different development workflows, testing scenarios, and production environments. Branches allow you to work with isolated database environments without affecting production.

note

To learn about how database branching works, including parent-child relationships, copy-on-write storage, and branch strategies, see Database branches. The following sections focus on the procedures for creating and managing branches.

Branch overview

A branch in Lakebase Postgres is an independent database environment that shares storage with its parent branch through copy-on-write. Branches enable you to:

• Create isolated development and testing environments
• Test applications against realistic data sets
• Implement database development workflows

Create a branch

When creating a branch, you can choose from several options depending on your specific needs. Each option creates a branch with different data characteristics and use cases.

To create a branch:

1. Navigate to your project's Branches page in the Lakebase App.
2. Click Create branch and configure your branch options:
   • Enter a descriptive branch name
   • Select your preferred branch type (Current data or Past data)
   • Optionally, set an expiration time for automatic deletion by checking Expire branch after and selecting a preset (1 hour, 1 day, or 7 days). See Branch expiration for details.
   • Configure any additional settings for your chosen option
3. Click Create to create the branch.

Branch creation options

Choose the option that best fits your use case.

Option	Description
Current data	Creates a branch from the latest state of your parent branch. Ideal for development, testing with current data, and feature branches.
Past data	Creates a branch from a specific point in time within your restore window. Perfect for point-in-time recovery, historical analysis, rollback scenarios, and time travel queries. Use the date picker to select the desired point in time.

Branch expiration

Branch expiration allows you to set automatic deletion timestamps on branches. When a branch reaches its expiration time, it is automatically deleted. This feature helps manage temporary branches and reduce storage costs.

Why use branch expiration

Branch expiration is ideal for temporary branches that have predictable lifespans:

• CI/CD environments: Test branches that should clean up after pipeline completion.
• Feature development: Time-boxed feature branches with known deadlines.
• Automated testing: Ephemeral test environments created by scripts.
• Development workflows: Temporary environments that don't need to persist indefinitely.

Without automatic expiration, these branches accumulate over time, increasing storage costs and project clutter.

tip

Example expiration durations: CI/CD pipelines (2-4 hours), demos (24-48 hours), feature development (1-7 days), long-term testing (30 days).

How branch expiration works

Branch expiration uses a time-to-live (TTL) model. When you set an expiration on a branch, you're defining how long the branch should exist before automatic deletion.

When you set an expiration timestamp on a branch:

1. The system stores both the expiration timestamp (the scheduled date and time when the branch will be deleted) and the TTL interval (the duration between creation or update and expiration)
2. A background process monitors branches and deletes them after their expiration time is reached
3. If you reset a branch from its parent, the TTL countdown restarts using the original interval

important

Branch deletion is permanent and cannot be recovered. All associated data and compute resources are also deleted. Verify expiration times carefully before setting them.

Set branch expiration

You can set an expiration timestamp when creating a branch or update it later.

When creating a branch

1. Navigate to your project's Branches page in the Lakebase App.
2. Click Create branch, configure your branch options, and check Expire branch on to select a preset (1 hour, 1 day, or 7 days).
3. Click Create.

Update branch expiration

To update or remove an expiration timestamp on an existing branch:

1. Navigate to your project's Branches page in the Lakebase App.
2. Click the menu next to the branch and select Update expiration.
3. Select a new date and time or uncheck Expire branch on to remove the expiration, then click Save.

View branch expiration

To check if a branch has an expiration set, navigate to your project's Branches page and click on the desired branch. The expiration information is displayed in the branch details.

Branch expiration restrictions

To maintain system integrity, expiration timestamps cannot be added to:

• Protected branches: Cannot expire protected branches or protect branches with expiration.
• Default branches: Cannot expire default branches or set expiring branches as default.
• Parent branches: Cannot expire branches that have children or create children from expiring branches.

note

When a branch expires and is deleted, all associated compute resources are also deleted. Ensure any critical workloads are migrated before expiration.

Maximum expiration period

The maximum expiration period is 30 days from the current time. If you need a branch to persist longer than 30 days, you can update the expiration timestamp before it expires to extend its lifetime.

View branches

To view all branches in your Lakebase project, select your database project in the Lakebase App and navigate to Branches in the left navigation.

The branches table displays key information about each branch:

The branches page shows a comprehensive table with information about each branch in your project:

Column	Description
Branch	The branch name. The default branch shows a "DEFAULT" label.
Parent	Indicates the parent branch from which this branch was created, helping you track your branch hierarchy.
Active time	Number of hours the branch's compute has been active.
Primary compute	Shows the current compute size and status (such as IDLE or ACTIVE) for the branch's compute.
Data size	Indicates the logical data size of the branch. Data size doesn't include history.
Created by	The user or service that created the branch.
Last active	Shows when the branch's compute was last active.

Branch overview

Click any branch in the table to view the branch overview page, which displays detailed information about the selected branch:

The branch overview page displays detailed information at the top, including key metrics and metadata:

Field	Description
ID	The unique branch identifier (with br- prefix)
Created on	The date and time when the branch was created
Compute hours	Total compute hours used by the branch
Active hours	Compute hours used since a specific date
Data size	The logical data size of the branch (doesn't include history)
Created by	The user who created the branch

The branch overview page includes several tabs for managing different aspects of the branch:

Tab	Description
Computes	View and manage the primary compute for the branch. See Manage computes.
Roles & Databases	Manage database roles and databases associated with the branch. See Manage databases and Manage roles.
Child branches	View any branches that were created from this branch

Compare branch schemas

Review schema differences between a child branch and its parent branch before merging changes. Schema diff shows a side-by-side SQL DDL comparison that highlights added, removed, or modified database objects such as tables, columns, indexes, and constraints.

To compare schemas between branches:

1. Navigate to a child branch overview page in the Lakebase App.
2. In the Parent branch section, click Schema diff.
3. In the Schema Diff dialog:
   • Base: Select the base branch for comparison (defaults to parent branch).
   • Database: Select the database to compare.
   • Compare: Select the branch to compare against base (defaults to current child branch).
4. Click Compare.

Understand the diff results

When schemas differ, the diff view displays a side-by-side comparison of SQL DDL statements:

Red lines show what was removed or changed from the base branch, green lines show what was added or changed in the compare branch. The diff captures changes to table definitions, columns, constraints, indexes, and other database objects.

If no differences exist between the selected branches, you see a success message confirming the schemas are in sync:

Use schema diff for pre-merge validation, development tracking, drift detection, and change documentation. To see schema diff in a complete development workflow, see Tutorial: Branch-based development workflow.

note

Schema diff compares database schema (DDL) only, not data content. Comparison uses the latest available data (head) from both branches.

Reset branch from parent

You can reset a branch to instantly update it with the latest schema and data from its parent branch. This helps you recover from issues, start on new feature development, or keep the different branches in your environment in sync.

Example scenario

When working with database branches, you might find yourself in a situation where you need to update your working branch to the latest data from your production branch.

For example, let's say you have two child branches staging and development forked from your production branch. You've been working on the development branch and find it's now too far out of date with production.

You have no schema changes in development to consider or preserve; you just want a quick refresh of the data. You can perform a clean, instant reset to the latest data from the parent in a single operation, saving you the complication of manually creating and restoring branches.

How Reset from parent works

When you reset a branch to its parent, the data and schema is completely replaced with the latest data and schema from its parent.

Key points:

• You can only reset a branch to the latest data from its parent. Point-in-time resets based on timestamp are possible using point-in-time restore, a similar feature with some differences: point-in-time restore creates a new branch and is intended more for data recovery than development workflow.
• This reset is a complete overwrite, not a refresh or a merge. Any local changes made to the child branch are lost during this reset.
• Existing connections are temporarily interrupted during the reset. However, your connection details don't change. All connections are re-established as soon as the reset is done.
• Root branches (like your project's production branch) can't be reset because they have no parent branch to reset to.

Reset a branch from its parent

To reset a branch to its parent:

1. Navigate to your project's Branches page in the Lakebase App.
2. Click the menu next to the branch you want to reset and select Reset from parent.
3. Confirm the reset operation.

note

If the branch has child branches of its own, resetting is blocked. You must delete the child branches first before you can reset the parent branch.

Set a branch as default

Each Lakebase project is created with a default branch called production, but you can designate any branch as the default. The default branch is exempt from the concurrently active compute limit, ensuring it remains available at all times.

To set a branch as default:

1. Navigate to your project's Branches page in the Lakebase App.
2. Click the menu next to the branch you want to set as default.
3. Select Set as default and confirm the operation.

Set a branch as protected

Protected branches help you safeguard critical database branches from accidental modifications or deletions. Protected branches cannot be deleted, reset, or archived due to inactivity. Projects with protected branches and their associated computes also cannot be deleted.

To set a branch as protected:

1. Navigate to Branches in the Lakebase App and select the branch you want to protect.
2. Click Protect and confirm your selection.

Your branch is now designated as protected, as indicated by the shield icon that appears next to the branch name.

For complete details about protected branches, including password management for child branches, see Protected branches.

Delete a branch

important

Deleting a branch is a permanent action that cannot be undone. Deleting a branch also removes:

• All databases that belong to the branch
• All roles associated with the branch
• The compute resources associated with the branch
• All data and changes specific to that branch

You cannot delete a branch that has child branches. The child branches must be deleted first.

To delete a branch:

1. Navigate to your project's Branches page in the Lakebase App.
2. Click the menu next to the branch you want to delete and select Delete branch.
3. Enter the branch name to confirm deletion and click Delete.