BranchSQL
Get started
← Back to blog

Getting Started: How to Create Your First Database Branch in 5 Minutes

Getting Started: How to Create Your First Database Branch in 5 Minutes

If you've ever worked on a team with a shared staging or development database, you know the pain. One developer pushes a breaking schema change, and suddenly, everyone is blocked. Tests fail, QA grinds to a halt, and productivity plummets. Spinning up a fresh, isolated database for every feature branch is often too slow and expensive to be practical. This is where database branching comes in, and this database branching tutorial will show you how to get started in minutes.

Database branching applies the same principles of Git-style source control to your database. It allows you to instantly create zero-cost, isolated copies of your database for every feature, bug fix, or experiment. This means every developer can work safely on their own copy of the database without interfering with others, leading to faster development cycles and more reliable deployments.

In this guide, we'll walk you through the simple, three-step process of connecting your database and creating your very first branch using BranchSQL. Let's eliminate the "who broke staging?" mystery once and for all.

What is Database Branching? A Quick Refresher

Before we dive into the "how," let's briefly cover the "what." Think about your code workflow. When you need to start a new feature, you don't edit the main branch directly. You run a command like git checkout -b new-feature. This creates a new, isolated line of development where you can make changes, commit them, and experiment freely without affecting the stable main branch.

Database branching does the exact same thing for your database.

Instead of pointing your local development environment to a crowded, shared database, you create a new branch from a production or staging snapshot. This branch is a complete, writeable copy of both the schema and the data. You get a unique connection string, and you can run migrations, add test data, or even drop tables without any fear of impacting your colleagues or your production environment.

The key benefits include:

  • Total Isolation: Every developer works in their own sandbox. No more stepping on each other's toes.
  • Unmatched Speed: Creating a new database branch takes seconds, not hours of provisioning and seeding data. This is made possible by efficient copy-on-write technology.
  • Production-Like Data: Test your features against a realistic, full dataset, catching edge cases that would be missed with simple seed files.
  • Safe Schema Migrations: Run and test potentially destructive migrations on a branch before ever thinking about merging them.

It's a transformative approach that modernizes the database development lifecycle, bringing it in line with the speed and safety you expect from your application code.

Prerequisites: What You'll Need

Getting started is designed to be as frictionless as possible. You only need a couple of things to follow along with this tutorial:

  1. A BranchSQL Account: You can get started with a free developer account that provides all the core features needed to create and manage branches.
  2. Database Connection Details: You'll need credentials for a PostgreSQL or MySQL database that you want to branch. This can be an existing development database, a staging environment, or even a read-replica of your production database. The required details are:
    • Hostname or IP Address
    • Port (e.g., 5432 for PostgreSQL, 3306 for MySQL)
    • Database Name
    • Username
    • Password
  3. A Few Minutes: The entire process, from connecting your database to creating your first branch, really does take about five minutes.

Security Pro-Tip: For connecting your source database, we highly recommend creating a dedicated, read-only database user for BranchSQL. This follows the principle of least privilege and ensures that the platform only has the permissions it needs to read your data for branching.

Step 1: Connecting Your Source Database

The first step is to tell BranchSQL where to find the "main" version of your database—the one from which all your development branches will be created.

  1. Log in and Create a Project: After logging into your BranchSQL account, you'll be prompted to create a new project. A project is a container for a single source database and all of its associated branches. Give it a name that reflects your application, like webapp-api or analytics-db.

  2. Navigate to Sources: Inside your new project, look for a section or tab labeled "Sources" or "Databases". This is where you'll manage your primary database connections.

  3. Add a New Source: Click the "Add New Source Database" button. This will open a form asking for the connection details you gathered in the prerequisites.

  4. Enter Your Credentials: Carefully fill out the form with your database's hostname, port, database name, username, and password. Select the correct database type (PostgreSQL or MySQL).

    # Example for a PostgreSQL database:
Host: db.your-company.com
Port: 5432
Database: app_production
Username: branchsql_readonly
Password: ••••••••••••••••

  5. Test and Connect: Use the "Test Connection" button to ensure BranchSQL can successfully reach and authenticate with your database. If the test passes, click "Connect".

Once you connect, BranchSQL will begin the initial snapshot process. It performs a logical dump of your database to create the base image from which all future branches will be derived. The duration of this initial snapshot depends on the size of your database—it could be a few minutes for a small database or longer for a very large one.

This is the only time you'll experience a significant wait. Every subsequent branch you create will be virtually instantaneous. You can monitor the progress of the snapshot from your project dashboard.

Step 2: Creating Your First Branch

Once your source database has finished its initial sync, you'll see a representation of it in your project's dashboard, often named main. This is your base. Now for the magic.

  1. Find the "Create Branch" Button: From your project's branch view, which often looks like a Git commit graph, locate the main branch. You'll see an option to create a new branch from it.

  2. Name Your Branch: Click "Create Branch". A dialog will appear asking you to name your new branch. It's a best practice to use a name that corresponds to your Git branch or the ticket you're working on. For example:

    • feat/add-user-profiles
    • bugfix/checkout-api-error
    • ch-1234-update-reporting-logic

  3. Create the Branch: Click the final confirmation button. In a matter of seconds—literally—your new database branch will be created and provisioned. You'll see it appear in the workflow visualization, branching off from main.

That's it. You've successfully created a complete, isolated, and writeable copy of your database. Behind the scenes, BranchSQL's copy-on-write technology makes this possible without duplicating all the data, making it incredibly fast and storage-efficient.

Step 3: Connecting and Using Your New Branch

A branch isn't useful until you can connect to it. For every branch you create, BranchSQL provides a unique, dedicated connection string.

  1. Get the Connection String: Select your newly created branch in the UI. You will see a panel or section displaying its connection details. This will include a new hostname, port, database name, and credentials specifically for this branch. There is usually a convenient "Copy" button to grab the full connection string URL.

  2. Connect with Your Favorite Tool: You can now use this connection string just like any other database connection.

    • In your application code: Update your .env file or configuration management system to point your local development environment to the new branch's connection string.
    • In a database GUI: Open your favorite tool like TablePlus, DBeaver, Postico, or DataGrip and create a new connection. Paste the connection string, and you'll be connected to your isolated branch.

  3. Develop in Isolation: Now you can start making changes. Let's try it. Connect to your feat/add-user-profiles branch and run some SQL:

    -- Run a new migration to add a profiles table
CREATE TABLE user_profiles (
    id SERIAL PRIMARY KEY,
    user_id INTEGER NOT NULL UNIQUE REFERENCES users(id),
    bio TEXT,
    website VARCHAR(255)
);

-- Seed some data for testing
INSERT INTO user_profiles (user_id, bio) VALUES (1, 'This is a test bio.');

You can now run your application locally and build out the new user profiles feature against a database that has your new schema changes and data.

The most important part? If you now connect back to your main database branch (or if a colleague connects to their own branch), the user_profiles table will not exist. Your changes are completely contained within your branch, just as they should be.

Next Steps: Integrating Branching Into Your Workflow

You've successfully mastered the basics by creating and using your first branch. This manual process is powerful for local development, but the real magic happens when you integrate database branching into your team's automated workflows.

  • CI/CD and Preview Environments: Use the BranchSQL CLI or REST API to automate this process. You can configure your CI/CD pipeline (e.g., GitHub Actions, GitLab CI) to automatically create a new database branch for every single pull request. The unique connection string can then be injected as an environment variable into a preview deployment of your application. This gives developers, QA, and product managers a live, interactive environment to test every change with its own isolated database.

  • Team Collaboration: Invite your QA engineers, DevOps team, and other developers to your BranchSQL project. They can easily connect to feature branches to perform tests or collaborate on complex changes without needing to set up a database on their own machines.

  • Painless Schema Migrations: Database branching is the ultimate safety net for testing schema migrations. Before merging a pull request with a new migration, you can run it against an isolated branch. You can even run tests that seed large amounts of data to check for performance regressions or logical errors, all without any risk to your shared environments.

Frequently Asked Questions

What databases does BranchSQL support? Currently, BranchSQL offers full support for PostgreSQL and MySQL, two of the most popular open-source databases. Support for other SQL databases is on the roadmap.

How long does it take to create a branch? After the one-time initial snapshot of your source database, creating a new branch is nearly instantaneous. It typically takes only a few seconds.

Is my source database affected when I make changes on a branch? No, absolutely not. Every branch is a completely isolated, copy-on-write clone. Any changes you make—including ALTER TABLE, DROP TABLE, or TRUNCATE—are confined to that specific branch and will never affect the source database or any other branches.

Conclusion

You've just completed a foundational database branching tutorial and seen how simple it is to bring modern, Git-like workflows to your database. In just a few minutes, you connected a source database, created an isolated branch, and made changes in a completely safe environment.

By adopting this workflow, you can eliminate staging environment bottlenecks, empower your developers to move faster, and deploy changes with significantly more confidence. The days of disruptive, shared development databases are over. You're now equipped to build, test, and iterate with the speed and safety your team deserves.

Ready to bring database branching to your own projects? Explore our plans at /pricing or /login to get started.