Tutorial: Branch-based development workflow

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.

Learn how to use database branches like Git branches, giving each developer an isolated database branch for independent work, then resetting to stay in sync.

Prerequisites

• A Lakebase project (comes with production and development branches)
• Basic familiarity with SQL and Postgres

Set up your starting schema

Before creating your developer branch, set up a simple schema on the development branch. This serves as the shared starting point that all developers will fork from. When you create your personal branch, it instantly inherits this schema through copy-on-write.

1. Navigate to your development branch in the Lakebase UI.
2. Open the SQL Editor.
3. Create a basic users table with sample data:

SQL

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email TEXT NOT NULL UNIQUE,
    created_at TIMESTAMP DEFAULT NOW()
);

INSERT INTO users (email) VALUES
    ('alice@example.com'),
    ('bob@example.com'),
    ('charlie@example.com');

Create your developer branch

Each developer on your team can have a long-lived branch for ongoing work. Reset it periodically to stay in sync with the parent.

From your project's branch list, select the development branch, then click Create child branch. Name it dev/alex (following the pattern dev/<your-name>) and click Create.

The branch is created instantly and includes all schemas and data from development through copy-on-write.

Your branch hierarchy:

production (root)
  └── development (has users table + data)
        └── dev/alex (instantly inherits users table + data)

Develop your feature

Point your application at your dev branch by updating the connection string in your .env file, then develop your feature using your normal workflow.

For example, adding user preference tracking to your application would involve updating your user model, generating a migration with your framework (Prisma, Alembic, Django, etc.), and running it on your dev/alex branch. Your migration file might contain:

SQL

ALTER TABLE users ADD COLUMN preferences JSONB DEFAULT '{}';
CREATE INDEX idx_users_preferences ON users USING GIN (preferences);

After running the migration, develop the preference feature in your application code and test the complete flow locally. Your branch is completely isolated—changes don't affect production or other developers.

Review your changes

Before promoting to other environments, use schema diff to verify exactly what changed. Navigate to your dev/alex branch overview, click Schema diff, and compare against development.

The side-by-side comparison shows your new preferences column and index in green:

This verification step helps catch unintended changes before they reach production. For complete schema diff documentation, see Compare branch schemas.

Promote your changes

When you're confident in your changes, promote them to upstream branches. Apply the same schema changes you validated on dev/alex to your development branch, then deploy your application code. This workflow ensures your schema changes are tested in isolation before reaching shared environments.

Reset and start fresh

When you're ready to start new work, reset your personal branch to stay in sync with development, which may have had changes from other developers. This gives you a fresh start from the current shared baseline.

Navigate to your dev/alex branch and click Reset from parent. The reset modal confirms that all databases and roles will be replaced with the latest data from development. This action is not reversible, so make sure you've promoted any changes you want to keep before confirming.

Your branch now matches development exactly, ready for your next task.

Best practices

• Use consistent naming: Follow the dev/<name> pattern for developer branches.
• Reset regularly: Keep your branch in sync with development to avoid drift.
• Protect production: Use protected branches to prevent accidental changes