Dolt for Beginners: Dolt Basics
Dolt is like Git and MySQL had a baby. What does that mean in practice?
We've been building Dolt for over six years now. We've been writing three blog articles a week for five years and five blog articles a week for almost a year. As we've produced more content, our articles tend to get pretty deep and expert focused. For example, we have deep dives on Prolly Trees and Auth changes to MySQL 9.0. I can't blame newcomers to Dolt for being a bit overwhelmed by our blog.
This article aims to change that. We're starting a new article series entitled Dolt for Beginners. The first article is focused on the basics: installation, creating a database, doing something git-ty, starting a server, and doing something SQL-y. By going over the basics, it should be obvious that Dolt is like Git and MySQL had a baby.
Installation
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.
reset - Remove table changes from the list of staged table changes.
clean - Remove untracked tables from working set.
commit - Record changes to the repository.
sql - Run a SQL query against tables in repository.
sql-server - Start a MySQL-compatible server.
log - Show commit logs.
show - Show information about a specific commit.
branch - Create, list, edit, delete branches.
checkout - Checkout a branch or overwrite a table from HEAD.
merge - Merge a branch.
conflicts - Commands for viewing and resolving merge conflicts.
cherry-pick - Apply the changes introduced by an existing commit.
revert - Undo the changes introduced in a commit.
clone - Clone from a remote data repository.
fetch - Update the database from a remote data repository.
pull - Fetch from a dolt remote data repository and merge.
push - Push to a dolt remote.
config - Dolt configuration.
remote - Manage set of tracked repositories.
backup - Manage a set of server backups.
login - Login to a dolt remote host.
creds - Commands for managing credentials.
ls - List tables in the working set.
schema - Commands for showing and importing table schemas.
table - Commands for copying, renaming, deleting, and exporting tables.
tag - Create, list, delete tags.
blame - Show what revision and author last modified each row of a table.
constraints - Commands for handling constraints.
migrate - Executes a database migration to use the latest Dolt data format.
read-tables - Fetch table(s) at a specific commit into a new dolt repo
gc - Cleans up unreferenced data from the repository.
fsck - Verifies the contents of the database are not corrupted.
filter-branch - Edits the commit history using the provided query.
merge-base - Find the common ancestor of two commits.
version - Displays the version for the Dolt binary.
dump - Export all tables in the working set into a file.
docs - Commands for working with Dolt documents.
stash - Stash the changes in a dirty working directory away.
profile - Manage dolt profiles for CLI global options.
query-diff - Shows table diff between two queries.
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
Dolt is a MySQL-compatible database. You create tables and insert data into them. The logical container for tables is a database. So, the first thing you do when using Dolt is create a database. On the command line, you create a database using dolt init.
Dolt stores your newly created database in files in a .dolt directory in your current working directory. In most terminals, the terminal opens to your home directory. We recommend you make a dolt directory in your home directory to house any Dolt databases you create. If you want your database named something other than dolt, make another directory called the name you desire. I called mine beginner.
$ mkdir dolt
$ cd dolt
$ mkdir beginner
$ cd beginner
$ dolt init
Successfully initialized dolt data repository.Do Something Git-ty
Git marks versions as commits in a log. Dolt works the same way. When we created our beginner database, Dolt made an initial commit in the log. To access the log, we run the dolt log command. This prints out all entries in the log.
$ dolt log
commit i3aoe9qt68dfk98qh97qv48fuuv7v207 (HEAD -> main)
Author: timsehn <tim@dolthub.com>
Date: Tue Jan 21 16:35:51 -0800 2025
Initialize data repository
You have the full power of the Dolt command line for this database when you are in this directory. You can create branches using dolt branch. You can switch branches using dolt checkout. You can create commits with dolt commit. Almost anything you can do with the Git command line, you can also do with the Dolt command line.
Start a Server
But Dolt is not just a Git clone. It is also a MySQL-compatible database server. MySQL operates in a client/server model. You start a server and connect to it with one or many clients. Dolt can work the same way. To start a MySQL-compatible server, you run the dolt sql-server command. This will take over your terminal and print any logs until you stop the program, usually with Control-C.
$ dolt sql-server
Starting server with Config HP="localhost:3306"|T="28800000"|R="false"|L="info"|S="/tmp/mysql.sock"Do Something SQL-y
Now, you need a MySQL client to connect to the now running server. Let's open a new terminal and connect with Dolt's built in client dolt sql. If you navigate to the directory where your database is stored, you don't need the host or port, Dolt just determines those things for you.
$ cd dolt/beginner
$ dolt sql
# Welcome to the DoltSQL shell.
# Statements must be terminated with ';'.
# "exit" or "quit" (or Ctrl-D) to exit. "\help" for help.
beginner/main>While we're here, let's create a simple table.
beginner/main> create table t (id int primary key, words varchar(100));
beginner/main*> show tables;
+--------------------+
| Tables_in_beginner |
+--------------------+
| t |
+--------------------+
1 row in set (0.00 sec)Dolt has the full power of SQL. Let's insert a row and select * just to show off a bit more.
beginner/main*> insert into t values (0, 'first');
Empty set (0.01 sec)
beginner/main*> select * from t;
+----+-------+
| id | words |
+----+-------+
| 0 | first |
+----+-------+
1 row in set (0.00 sec)If you have MySQL installed on your computer, you can also connect with that. But, you'll need the host, port, and user.
$ mysql -h localhost -P 3306 -u root
WARNING: option --ssl-verify-server-cert is disabled, because of an insecure passwordless login.
Welcome to the MariaDB monitor. Commands end with ; or \g.
Your MySQL connection id is 6
Server version: 8.0.33 Dolt
Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
MySQL [(none)]> use beginner;
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A
Database changed
MySQL [beginner]> select * from t;
+----+-------+
| id | words |
+----+-------+
| 0 | first |
+----+-------+
1 row in set (0.001 sec)Any other tool that connects to a MySQL database should connect to Dolt in the same way.
Do something Git-ty in SQL
Now from that same connected MySQL client, let's commit our changes, marking a permanent version in the log. In Dolt SQL, Git functionality is exposed as system tables, procedures, and functions. The naming and argument passing follows the command line so dolt branch becomes select * from dolt_branch and dolt checkout main becomes call dolt_checkout('main').
To add and commit our tables in SQL, we run the following procedures.
MySQL [beginner]> call dolt_add('t');
+--------+
| status |
+--------+
| 0 |
+--------+
1 row in set (0.015 sec)
MySQL [beginner]> call dolt_commit('-m', 'Added table t');
+----------------------------------+
| hash |
+----------------------------------+
| ucs8jpq7uut9hp6kdfrmdngl7f8s2hc3 |
+----------------------------------+
1 row in set (0.013 sec)And finally, to see our new commit in the log, we read the dolt_log system table.
MySQL [beginner]> select * from dolt_log;
+----------------------------------+-----------+-----------------+---------------------+----------------------------+
| commit_hash | committer | email | date | message |
+----------------------------------+-----------+-----------------+---------------------+----------------------------+
| ucs8jpq7uut9hp6kdfrmdngl7f8s2hc3 | root | root@localhost | 2025-01-22 18:16:05 | Added table t |
| i3aoe9qt68dfk98qh97qv48fuuv7v207 | timsehn | tim@dolthub.com | 2025-01-22 00:35:51 | Initialize data repository |
+----------------------------------+-----------+-----------------+---------------------+----------------------------+
2 rows in set (0.003 sec)Conclusion
As you can see, Dolt really is like Git and MySQL had a baby. Curious to keep learning? Follow one of our Getting Started guides. Want to talk to a Dolt to learn more? Come by our Discord and say hi.