Dolt for Beginners: Commits
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. The backbone of Git's version control is the commit and Dolt is no different. Understanding commits is a good place to start on the topic of version control. This blog will explain how to make and use commits in Dolt.
What is a Commit?
A commit is a marker of the state of the Dolt database at the time the commit was made. Underneath the hood, Dolt is maintaining all the objects in your database in a content-addressed store. This means that your database contents can be summarized into a single SHA-256 encoded hash. These look like random 32 letter amd number combinations, for example, t5d5inj4bpc1fltrdm9uoscjdsgebaih. When you make a commit, a hash is calculated using the state of your database and the commit metadata like user, date, and message. That hash is stored in a commit graph that represents the history of your database.
If you want to deep dive into commits and how they are stored in Dolt, our documentation has a great article on the Dolt Commit Graph that has a lot of beginner-friendly pictures.
When to Commit
This is all rather complicated for a beginner so it might be better to think about when you should make a commit instead. You should make a commit when you want to be able to refer to that database state again. Did you make important changes to your database? Make a commit. Do you want to go back to this state in the future? Make a commit. Do you want to compare changes in your database to this point in time? Make a commit. Commits in Dolt are very light weight so when in doubt, commit.
Install Dolt
Now, let's make a few commits.
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. 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. Given commits being very Git-ty, 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. To create commits in SQL, you use the dolt_commit() procedure.
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 commit_example. To create a database, we use dolt init. Dolt names databases after the directory they are created in so we make a commit_example directory and cd into it.
$ mkdir commit_example
$ cd commit_example
$ dolt init
Successfully initialized dolt data repository.At this point you already have a commit. dolt init implicitly makes one. To view commits, you use dolt log or dolt show. dolt show only shows the most recent commit so let's use that one.
$ dolt show
commit g4u3k56h0bs3onviolmrqev9rftajt9e (HEAD -> main)
Author: timsehn <tim@dolthub.com>
Date: Mon Feb 24 13:25:21 -0800 2025
Initialize data repository
dolt show will also show you what changed in the last commit. In this case, the init commit contains no changes.
Make some Tables
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))"Now let's make sure it exists using the dolt status command. This is analogous to the git status command which shows you which files have changed since the last commit in your Git repository. dolt status shows you which tables have changed in Dolt since the last commit with some additional helpful information.
$ dolt status
On branch main
Untracked tables:
(use "dolt add <table>" to include in what will be committed)
new table: peopleIt looks like I created a new people table successfully.
Make a Commit
Schema changes are a good time to make a commit. I added a new table which qualifies as a schema change. dolt status conveniently suggests I use dolt add people to stage the table for commit. By default, both Git and Dolt have what is called a staging area. Changes must be staged using add in order to be committed. You don't need to stage every change you made for a commit. This adds a bit of complexity to the commit process. I often just add -a or -A meaning --all to my dolt commit command to stage all my changes as part of my commits. But, in this case, I'll add the table using dolt add people.
$ dolt add people
$ dolt status
On branch main
Changes to be committed:
(use "dolt reset <table>..." to unstage)
new table: peopleNow, dolt status suggests my changes are staged. It's time to commit. Commits require a message which I'll pass in using the -m or --message flag.
$ dolt commit -m "Created table people"
commit fatrtlokffa26e7m3itjvn7ge1h139u1 (HEAD -> main)
Author: timsehn <tim@dolthub.com>
Date: Mon Feb 24 14:01:54 -0800 2025
Created table people
Now, let's again use dolt show to inspect our handy-work.
$ dolt show
commit fatrtlokffa26e7m3itjvn7ge1h139u1 (HEAD -> main)
Author: timsehn <tim@dolthub.com>
Date: Mon Feb 24 14:01:54 -0800 2025
Created table people
diff --dolt a/people b/people
added table
+CREATE TABLE `people` (
+ `id` int NOT NULL,
+ `first_name` varchar(100),
+ `last_name` varchar(100),
+ PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_bin;This time dolt show includes a handy diff of what we changed in the latest commit. Producing diffs between commits to see what changed in human readable or queryable fashion is one of the primary uses of commits.
Add 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)Again, let's consult dolt status to see what we've done.
$ dolt status
On branch main
Changes not staged for commit:
(use "dolt add <table>" to update what will be committed)
(use "dolt checkout <table>" to discard changes in working directory)
modified: peopleWe can also see what we've changed since the last commit using dolt diff to make sure the changes are good.
$ dolt diff
diff --dolt a/people b/people
--- a/people
+++ b/people
+---+----+------------+-----------+
| | id | first_name | last_name |
+---+----+------------+-----------+
| + | 0 | Tim | Sehn |
| + | 1 | Brian | Hendriks |
| + | 2 | Aaron | Son |
+---+----+------------+-----------+Make Another Commit
This all looks good. Let's make another commit. We're going to skip the add step this time and do it all in one commit command using the -a or --all flag.
$ dolt commit -am "Added some rows to people"
commit 57q90hfvfd6mm1d3b2r64o37fgidsho2 (HEAD -> main)
Author: timsehn <tim@dolthub.com>
Date: Mon Feb 24 14:23:28 -0800 2025
Added some rows to people
View the Log
Now let's view the log of all the commits going back to the start of the database. This information is accessed via the dolt log command. As expected, we now have three commits.
$ dolt log
commit 57q90hfvfd6mm1d3b2r64o37fgidsho2 (HEAD -> main)
Author: timsehn <tim@dolthub.com>
Date: Mon Feb 24 14:23:28 -0800 2025
Added some rows to people
commit fatrtlokffa26e7m3itjvn7ge1h139u1
Author: timsehn <tim@dolthub.com>
Date: Mon Feb 24 14:01:54 -0800 2025
Created table people
commit g4u3k56h0bs3onviolmrqev9rftajt9e
Author: timsehn <tim@dolthub.com>
Date: Mon Feb 24 13:25:21 -0800 2025
Initialize data repository
You can inspect any commit by using dolt show and the commit in question's commit hash like so:
$ dolt show fatrtlokffa26e7m3itjvn7ge1h139u1
commit fatrtlokffa26e7m3itjvn7ge1h139u1
Author: timsehn <tim@dolthub.com>
Date: Mon Feb 24 14:01:54 -0800 2025
Created table people
diff --dolt a/people b/people
added table
+CREATE TABLE `people` (
+ `id` int NOT NULL,
+ `first_name` varchar(100),
+ `last_name` varchar(100),
+ PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_bin;Using Dolt commits, you have an audit log of every change to your database going back to inception.
Go Back In Time
Finally, let's imagine the last commit was made in error and we really want an empty table again. We can go back in time to the commit listed above in dolt show by using the dolt reset --hard command. I pass the commit hash of the commit I want to reset to into dolt reset --hard.
$ dolt reset --hard fatrtlokffa26e7m3itjvn7ge1h139u1Now, the database looks exactly like it did before I inserted the rows.
$ dolt log
commit fatrtlokffa26e7m3itjvn7ge1h139u1 (HEAD -> main)
Author: timsehn <tim@dolthub.com>
Date: Mon Feb 24 14:01:54 -0800 2025
Created table people
commit g4u3k56h0bs3onviolmrqev9rftajt9e
Author: timsehn <tim@dolthub.com>
Date: Mon Feb 24 13:25:21 -0800 2025
Initialize data repository
$ dolt sql -q "select * from people"
$ dolt sql -q "show create table people"
+--------+------------------------------------------------------------------+
| Table | Create Table |
+--------+------------------------------------------------------------------+
| people | CREATE TABLE `people` ( |
| | `id` int NOT NULL, |
| | `first_name` varchar(100), |
| | `last_name` varchar(100), |
| | PRIMARY KEY (`id`) |
| | ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_bin |
+--------+------------------------------------------------------------------+
With dolt reset you get instantaneous rollbacks to any commit.
Conclusion
Dolt commits are the backbone of its version control functionality. This article showed you how to create and examine commits. It also showed how to work with commits to inspect and control the state of your database. 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.