The Dolt for Beginners series focuses on topics people getting started with Dolt will likely be interested in. Most of our other blog articles go pretty deep so we want a space to talk about topics that experts may find boring.

So far, in our Beginner series we've covered how to get data and schema into a local Dolt database. You can't really do much in Dolt without a database so we focused on creating a database. Once you have a database, you probably want to start using Dolt's unique Git-like version control features. Last week, we covered commits, the backbone of Git and Dolt version control. This week, we'll cover branches the next basic version control concept to learn in both Git and Dolt.

What is a Branch?

A Dolt branch is a copy of your current database. A branch has a distinguishing characteristic from other copies. A branch can be merged into another branch of your database. So a copy you can't merge is just a copy. Sometimes, in version control, a copy is called a fork.

In Dolt, branches are created from commits. In practice, branches are just pointers to commits in a commit graph. No physical copying is taking place when you branch. Thus, branches are really light weight, a Dolt database can have thousands of branches.

Merging branches is done using a special Dolt workflow. There's a lot of nuance to the merge process but an important concept to understand is conflicts. Dolt calculates whether a merge is safe and if it's not, you get conflicts. As a beginner, if you get a merge conflict, just stop the merge and ask someone more senior to help.

When to Branch

Branches are used to track long running changes to your database. Unlike changes using raw SQL, you will have a chance to review what has changed on a branch before you merge and you'll be able to roll back all changes made on a branch in a single action. Both of these features have many practical use cases.

Are you changing the schema of the database to create a new feature for your application? It might be best to do that on a branch. Do you have import jobs that change some tables in your database? You may want to have those jobs write to branches so you can review what's changed. Do you have a potentially destructive administrative action that you wish could be easily rolled back? Do it on a branch and merge it if everything looks ok. As you can see, branches in databases are really useful. Once you know database branches exist, it makes you wonder why we had SQL databases for 40 years without them.

Now, let's make a branch, change it, and merge the changes back to the main branch.

Install Dolt

The first thing you need to do to follow along with this article is install Dolt. Dolt is not complicated software. There is no complicated install process. You don't need a Docker container or multiple dependencies installed. You download the single Dolt program and run it.

We have even more convenient ways to install Dolt for every platform.

Once you have Dolt installed, you need to open a terminal like "Terminal" on Mac or Powershell on Windows. Make sure Dolt is on your PATH by typing dolt. If everything is working you'll be greeted by a help message with all the valid Dolt commands. For those familiar with the Git command line, Dolt should look pretty similar.

$ dolt
Valid commands for dolt are
                init - Create an empty Dolt data repository.
              status - Show the working tree status.
                 add - Add table changes to the list of staged table changes.
                diff - Diff a table.
... <trimmed for length>
... <trimmed for length>
... <trimmed for length>
              reflog - Show history of named refs.
              rebase - Reapplies commits on top of another base tip
                  ci - Commands for working with Dolt continuous integration configuration.

Configure Your User

Just like Git, Dolt needs a user and email to create commits on the command line. You'll need commits to make branches. To set up your user for this computer, you use the dolt config command.

$ dolt config --global --add user.name "Tim Sehn"
$ dolt config --global --add user.email "tim@dolthub.com"

Create a Database

We're going to focus on the command-line interface (CLI) to Dolt today. The CLI branch and merge workflow is similar to Git so using the CLI for this demo makes a lot of sense.

You can also run Dolt as a server and connect to it with a SQL Workbench of your choice. Branch workflows are exposed as procedures for write operations like dolt_merge() and system tables for read operations like dolt_branches.

Open a shell, like Terminal on Mac, or Powershell on Windows. Navigate to the directory where you want your Dolt databases stored. I put mine in ~/dolt. Let's call our database branch_example. To create a database, we use dolt init. Dolt names databases after the directory they are created in so we make a branch_example directory and cd into it.

$ mkdir branch_example
$ cd branch_example 
$ dolt init
Successfully initialized dolt data repository.

Make some Tables

This example is going to be very similar to the example in the commits article. When it ain't broke, don't fix it.

To create tables in Dolt, I need to either import a CSV or run SQL. To run SQL from the command line, Dolt ships with a built in SQL shell accessed via dolt sql. To run a single SQL query, dolt sql provides the -q or --query option. We'll use dolt sql -q to create a people table with an id primary key and first_name and last_name columns. To learn more about SQL schemas, check out my beginner article on the topic.

$ dolt sql -q "create table people (id int primary key, first_name varchar(100),last_name varchar(100))"

Make a Commit

If you just found this article and don't understand commits yet, go work through the commit example and come back. We'll wait.

Alright, welcome back. Time to commit to learning Dolt branches. As noted above, branches are created from commits. Thus, branches require commits. We'll commit our new table so we can insert data into it on a branch. We make commits with the aptly named dolt commit command but we need to add our changes first using dolt add.

$ dolt add people
$ dolt commit -m "Created people table"
commit tag75uafjid94kv959s1ib86rhknu4d5 (HEAD -> main) 
Author: timsehn <tim@dolthub.com>
Date:  Mon Mar 03 14:34:48 -0800 2025

        Created people table

Make a Branch

So, in Git and Dolt, there are a number of ways to make a branch with the two most popular being dolt branch and dolt checkout -b. Branches by default are created from the current commit you are on. Right now, if I create a branch using dolt branch it will be from commit tag75uafjid94kv959s1ib86rhknu4d5 which I just created. If I want to create a branch from a different commit, I can pass in the commit hash to the dolt branch command. Branches also require a name. I'll call mine insert-new-people. I want to create a branch from my current commit so I run the following command:

$ dolt branch insert-new-people

It runs without returning an error which usually indicates it worked. We can inspect which branches exist and which one is checked out using dolt branch with no arguments.

$ dolt branch
  insert-new-people                             	
* main        

It looks like I created an insert-new-people branch. That * indicates the branch you have "checked out". A "checked out" branch is the current active branch. Any changes you make are applied to the current active branch. Since we only created insert-new-people, we still have the main branch checked out.

Switch Branches

To switch branches we use the dolt checkout command. This is why the active branch is often referred to as the "checked out" branch. checkout is the most confusing Git command because it does a bunch of things. Unfortunately, because Dolt mimics Git exactly, Dolt has the same confusion problem with the checkout command. The one thing no other command can do that only checkout can do is switch branches. Let's switch to our new insert-new-people branch.

$ dolt checkout insert-new-people
Switched to branch 'insert-new-people'
$ dolt branch
* insert-new-people                             	
  main  

The * has moved to insert-new-people meaning that is now our current active branch.

Insert Some Data

Now, let's add a couple rows to the people table. I again do this using SQL and the dolt sql -q command.

$ dolt sql -q "insert into people values (0, 'Tim', 'Sehn'), (1, 'Brian', 'Hendriks'), (2, 'Aaron', 'Son')"
Query OK, 3 rows affected (0.01 sec)

This is where things get kind of cool. You can use SQL as of syntax to query data on different branches. Dolt is a merge of Git and SQL into a beautiful new thing, the world's first version controlled SQL database.

$ dolt sql -q "select * from people"
+----+------------+-----------+
| id | first_name | last_name |
+----+------------+-----------+
| 0  | Tim        | Sehn      |
| 1  | Brian      | Hendriks  |
| 2  | Aaron      | Son       |
+----+------------+-----------+

$ dolt sql -q "select * from people as of main"

$

As you can see, we have rows on our current branch but there are no rows on main.

Make Another Commit

Now, we intend to merge this data back into main. Merges work on commits so we need to commit our changes on this branch.

$ dolt commit -am "Inserted data"
commit dakhh3o38coarjhhfghtiakr4mde6klt (HEAD -> insert-new-people) 
Author: timsehn <tim@dolthub.com>
Date:  Mon Mar 03 14:49:32 -0800 2025

        Inserted data

Switch Back to the main Branch

Now we switch back to main using dolt checkout.

$ dolt checkout main
Switched to branch 'main'
$ dolt branch
  insert-new-people                             	
* main  

We can again confirm there is no data on main, this time using count(*).

$ dolt sql -q "select count(*) from people"
+----------+
| count(*) |
+----------+
| 0        |
+----------+

View the diff between Branches

If we want to view the diff between branches before we merge, we can use dolt diff. dolt diff with no arguments shows you if you have uncommitted changes on your branch. But you can pass two branches into it to compare the branches.

$ dolt diff main insert-new-people 
diff --dolt a/people b/people
--- a/people
+++ b/people
+---+----+------------+-----------+
|   | id | first_name | last_name |
+---+----+------------+-----------+
| + | 0  | Tim        | Sehn      |
| + | 1  | Brian      | Hendriks  |
| + | 2  | Aaron      | Son       |
+---+----+------------+-----------+

It looks like that branch is doing exactly what it claims to have done. It has inserted new people into the people table.

Merge into main

Since the changes look good, it's now time to merge my branch changes into main. I merge using the dolt merge command. It takes a branch name as an argument.

$ dolt merge insert-new-people
Fast-forward
Updating dakhh3o38coarjhhfghtiakr4mde6klt..dakhh3o38coarjhhfghtiakr4mde6klt
people | 3 +++
1 tables changed, 3 rows added(+), 0 rows modified(*), 0 rows deleted(-)

It looks like it merged with no conflicts. Let's make sure we have the new people inserted on main.

$ dolt sql -q "select * from people"       
+----+------------+-----------+
| id | first_name | last_name |
+----+------------+-----------+
| 0  | Tim        | Sehn      |
| 1  | Brian      | Hendriks  |
| 2  | Aaron      | Son       |
+----+------------+-----------+

It looks good. Just to confirm, let's make sure there is no diff between the two branches now.

$ dolt diff main insert-new-people  
$

Empty just as we would expect. The insert-new-people branch is merged into the main branch.

Conclusion

Branches are used to isolate long running changes to your database. In this article, we walked through a simple example of creating a branch, making some changes on it, and merging it into the main branch. More questions? Check out the rest of our Dolt for Beginners series or come by our Discord and ask us questions. We're here to help.