AI VOID
DATE: 2026.06.06 00:00 CLEARANCE: PUBLIC

Setting Up Dolt and Your First Data Commit

Dolt SQL Git-for-Data Database Versioning CLI Data Management

// table of contents

▼

Welcome to Chapter 2! In the previous chapter, we explored the “why” behind Dolt and the revolutionary concept of Git for data. Now, it’s time to roll up our sleeves and get hands-on.

This chapter is your practical guide to installing Dolt, setting up your very first version-controlled SQL database, and making that crucial initial data commit. By the end, you’ll not only have Dolt running but also a foundational understanding of how to treat your data like code, ready to track every change. We’ll walk through each step, ensuring you grasp both the “how” and the “why” behind every command. This hands-on experience is critical for truly internalizing the “Git-for-Data” paradigm.

Core Concepts: Understanding Dolt’s Foundation

Before we dive into installation, let’s briefly reinforce the core ideas that make Dolt unique. This mental model will guide your understanding of the practical steps that follow.

Dolt: A Git-Powered Database

Imagine your database not just as a static storage system, but as a living, evolving entity whose entire history is trackable, revertible, and auditable. That’s Dolt. It’s a SQL database that supports all standard SQL queries you’d expect, but with the added superpower of Git-style version control.

Instead of just storing the current state of your data, Dolt stores every state. Every change, every update, every deletion can be committed, branched, merged, and diffed, just like code in a Git repository. This capability is what we call “Git-for-Data.” It’s revolutionary because it brings the robust collaboration and auditability of software development to the world of data.

The Dolt CLI: Your Gateway to Versioned Data

Your primary interaction with Dolt’s versioning capabilities will be through its command-line interface (CLI). It’s designed to feel very familiar if you’ve ever used Git. Commands like dolt init, dolt add, dolt commit, dolt branch, and dolt merge are direct parallels to their Git counterparts, but they operate on your SQL tables and data.

While you’ll use standard SQL for data manipulation (like INSERT, UPDATE, DELETE), the Dolt CLI is what brings the version control magic to life. It’s the bridge between your SQL operations and the historical record.

The Dolt Workflow: A Mental Model for Data Changes

Think of your data workflow with Dolt like this:

  1. You make changes to your database schema or data using standard SQL commands.
  2. Dolt, behind the scenes, tracks these modifications to your working set.
  3. You explicitly dolt add the tables or changes you want to include in your next saved version. This “stages” them.
  4. You dolt commit the staged changes with a descriptive message, permanently recording a new version of your data.

This simple cycle forms the basis of all version control operations in Dolt. It ensures that every significant data evolution is documented and retrievable.

flowchart TD A[Start] --> B[Edit Data with SQL] B --> C{Changes Made} C -->|Yes| D[Check Status] D --> E[Stage Changes] E --> F[Commit Changes] F --> G[New Version Saved] G --> B C -->|No| G

Dolt and Doltgres: A Quick Distinction

You might hear about both “Dolt” and “Doltgres.” Understanding the difference is key to choosing the right tool for your project.

  • Dolt is a MySQL-compatible database. This means it understands MySQL’s dialect of SQL and can often be used as a drop-in replacement for MySQL. This is what we’ll be primarily using in this chapter for our initial setup and the beginner project.
  • Doltgres is Dolt’s PostgreSQL-compatible sibling. It offers the same Git-for-Data capabilities but speaks PostgreSQL’s SQL dialect. We’ll explore Doltgres in more detail in a later chapter, especially for PostgreSQL migration considerations and the beginner-friendly project’s PostgreSQL-style data. For now, know that the core Git-for-Data concepts apply to both!

Step-by-Step Implementation: Setting Up Dolt and Your First Commit

Let’s get Dolt installed, configured, and make your very first versioned data change. This section walks you through the practical setup.

🧠 Important: Version Information

As of 2026-06-06, Dolt’s latest stable release is v1.4.2. DoltHub regularly releases updates, so always check their official documentation for the absolute latest version. We’ll use v1.4.2 for our setup instructions to ensure consistency.

Step 1: Install Dolt on Your System

This method installs the dolt CLI directly on your system, making it globally accessible.

For macOS (using Homebrew)

# Update Homebrew first to ensure you get the latest packages
brew update

# Install Dolt
brew install dolt

For Linux (using apt for Debian/Ubuntu)

# Add Dolt's official GPG key for secure package downloads
sudo apt update && sudo apt install -y gnupg ca-certificates apt-transport-https software-properties-common
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://www.dolt.tech/dolt-keyring.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/dolt-archive-keyring.gpg

# Add the Dolt repository to your system's package sources
echo "deb [signed-by=/etc/apt/keyrings/dolt-archive-keyring.gpg] https://packages.dolt.tech/apt/ /" | sudo tee /etc/apt/sources.list.d/dolt.list

# Update package lists and install Dolt
sudo apt update
sudo apt install -y dolt

For Windows (using Scoop)

First, ensure you have Scoop installed. If not, open PowerShell (as Administrator) and run:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

Then, install Dolt:

scoop install dolt

Verifying Dolt Installation

After installation, open your terminal or command prompt and run:

dolt version

You should see output similar to this (version numbers may vary slightly if a newer version is released):

dolt version v1.4.2

If you see the version number, congratulations! Dolt is installed and ready.

Option: Using Docker (Great for Isolation and CI/CD)

Docker provides a portable way to run Dolt without installing it directly on your system. This is excellent for ensuring consistent environments across development, testing, and production.

Prerequisites

  • Docker Desktop installed and running on your system.

Pulling the Dolt Docker Image

docker pull dolthub/dolt:latest

This command fetches the latest Dolt Docker image from DoltHub’s official repository. ⚡ Real-world insight: For production or shared development environments, it’s often a best practice to pin to a specific version (e.g., dolthub/dolt:v1.4.2) rather than latest to ensure consistency and prevent unexpected updates.

Verifying Installation (within Docker)

You can run a quick command to check the Dolt version inside a temporary container:

docker run --rm dolthub/dolt:latest dolt version

This will spin up a container, execute the dolt version command, and then automatically remove the container. You should see the version output.

Step 2: Install a SQL Client

Since Dolt is MySQL-compatible, the standard MySQL command-line client is perfect for interacting with it.

For macOS (using Homebrew)

brew install mysql-client

For Linux (Debian/Ubuntu)

sudo apt install -y mysql-client

For Windows

You can download the MySQL Shell or MySQL Workbench from the official MySQL website. For a command-line experience, you might need to install MySQL Server (which includes the client binaries) or use a Docker container for the MySQL client.

Verifying MySQL Client Installation

mysql --version

You should see the installed MySQL client version.

Step 3: Initialize Your First Dolt Database

Now that Dolt is installed, let’s create our first version-controlled database.

  1. Create a dedicated directory for your project. Let’s call it my-first-dolt-db.

    mkdir my-first-dolt-db
cd my-first-dolt-db

  2. Initialize the Dolt database inside this directory. This command transforms your empty directory into a Dolt repository.

    dolt init

    You’ll see output like:

    Successfully initialized dolt data repository.

    What just happened? Dolt created a hidden .dolt directory within my-first-dolt-db. This directory is where Dolt stores all its version control metadata, including the entire history of your data and schema. It’s the heart of your versioned database, analogous to Git’s .git directory.

Step 4: Start the Dolt SQL Server

Dolt runs as a SQL server, just like MySQL or PostgreSQL. You need to start this server to interact with your data using SQL.

dolt sql-server

You’ll see output indicating the server is starting and listening on a specific port (default is 3306). Keep this terminal window open; the server needs to run in the foreground.

Starting dolt sql server
...
[INFO]    Listening on 0.0.0.0:3306
...

⚡ Quick Note: If port 3306 is already in use by another MySQL instance, Dolt will tell you. You can specify a different port using dolt sql-server --port 3307.

Step 5: Connect with Your SQL Client

Open a new terminal window (leave the dolt sql-server running in the first one). Now, connect to your running Dolt server using the MySQL client.

mysql -h 127.0.0.1 -P 3306 -u root -p

Let’s break down these flags:

  • -h 127.0.0.1: Specifies the host to connect to (your local machine).
  • -P 3306: Specifies the port (Dolt’s default).
  • -u root: Dolt’s default username is root.
  • -p: Dolt does not require a password by default for root locally, so just press Enter when prompted for the password.

You should now see the MySQL client prompt:

mysql>

Congratulations! You’re connected to your version-controlled Dolt database.

Creating Data and Making Your First Commit

Now for the exciting part: adding some data and saving its history. This is where the “Git-for-Data” paradigm truly comes alive.

Step 1: Create a Table

Let’s create a simple table to store product information for our beginner-friendly inventory management project.

In your mysql> client, execute this SQL:

CREATE TABLE products (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(255) NOT NULL,
    price DECIMAL(10, 2) NOT NULL,
    stock INT NOT NULL DEFAULT 0
);

You’ll see Query OK, 0 rows affected (0.XX sec). This confirms the table was created.

Now, let’s verify the schema.

DESCRIBE products;

This command will output the structure of your products table, ensuring it matches your CREATE TABLE statement.

Step 2: Insert Some Data

Let’s add our first product records.

INSERT INTO products (name, price, stock) VALUES ('Laptop Pro', 1200.00, 50);

And another one:

INSERT INTO products (name, price, stock) VALUES ('Wireless Mouse', 25.50, 200);

You can verify the data was inserted correctly:

SELECT * FROM products;

You should see your two products listed, confirming the data is present in your Dolt database.

Step 3: Check Dolt Status

Now, switch back to your first terminal (where you ran dolt init and from where you’ll issue dolt CLI commands). You might need to open a third terminal window if you want to keep the dolt sql-server running and the mysql client open simultaneously. Navigate to your my-first-dolt-db directory in this new terminal.

Run the dolt status command:

dolt status

You’ll see output similar to:

On branch main
Untracked tables:
  (use "dolt add <table-name>..." to include in what will be committed)
        products

Explanation: Dolt detected that you created a products table and inserted data, but you haven’t yet told Dolt to track this table for versioning. This is very similar to git status showing untracked files – changes exist, but they are not yet staged for a commit.

Step 4: Stage Your Changes (dolt add)

To tell Dolt to include the products table and its initial data in the next commit, we need to “stage” it. Staging prepares your changes for recording.

dolt add products

Or, to stage all changes (new tables, modified tables, deleted tables, etc.) in your current directory:

dolt add .

Now, run dolt status again to see the effect of staging:

dolt status

Output:

On branch main
Changes to be committed:
  (use "dolt reset <table-name>..." to unstage)
        new table: products

Explanation: The products table is now in the “staging area.” Dolt knows you want to save its current state in the next commit. If you were to make more SQL changes after dolt add, those new changes would appear as “Changes not staged for commit.”

Step 5: Commit Your Changes (dolt commit)

Finally, let’s create our first commit, permanently recording this initial state of our database’s schema and data into Dolt’s history.

dolt commit -m "Initial commit: Created products table and added two products"

You’ll see output confirming the commit:

[main d10b8d7] Initial commit: Created products table and added two products
 2 tables changed, 2 insertions(+), 0 deletions(-)

The string d10b8d7 (this will be a unique identifier for your commit) is the unique commit hash, just like in Git. This hash represents a snapshot of your entire database at this point in time.

Run dolt status one last time:

dolt status

Output:

On branch main
nothing to commit, working tree clean

Explanation: All your changes are now committed and saved in Dolt’s history! Your database’s initial state is versioned, and your working directory is “clean,” meaning there are no pending changes to commit.

Mini-Challenge: Evolve Your Data

It’s your turn to practice the commit cycle and solidify your understanding of Dolt’s core workflow.

Challenge:

  1. In your mysql> client, add a new product to the products table.
  2. Update the price of an existing product.
  3. Observe the changes using dolt status in your Dolt CLI terminal. Notice how Dolt identifies modified tables.
  4. Stage these changes using dolt add ..
  5. Commit them with a clear, descriptive message like “Added new product and updated existing product price.”
  6. Verify your working directory is clean using dolt status again.

Hint: Remember the complete sequence: make SQL changes, then dolt status to see what’s changed, then dolt add . to stage, and finally dolt commit -m "Your message" to save.

What to observe/learn: This exercise reinforces the fundamental Dolt workflow of making changes, staging them, and committing them. It helps build muscle memory for versioning your data and understanding how dolt status reflects the state of your database. You’re actively building a historical record of your data’s evolution.

Common Pitfalls & Troubleshooting

Even simple setups can have hiccups. Here are a few common issues you might encounter and how to resolve them:

  • Forgetting dolt add: If you make SQL changes and then directly run dolt commit, Dolt will tell you there are “no changes to commit.”
    • Solution: Remember, dolt add . (or dolt add <table-name>) is crucial to move changes from your working set to the staging area before committing.
  • dolt sql-server not running: If your mysql client can’t connect, you’ll get an error like “Can’t connect to MySQL server.”
    • Solution: Ensure the dolt sql-server command is still active in its dedicated terminal. If it crashed or was closed, simply restart it.
  • Port 3306 in use: If Dolt can’t start because port 3306 is busy, it will report an error.
    • Solution: Stop any other process using port 3306 (e.g., another MySQL server), or start Dolt on a different port: dolt sql-server --port 3307. If you use a different port, remember to connect your mysql client to that new port: mysql -h 127.0.0.1 -P 3307 -u root -p.
  • mysql client command not found: If the mysql command fails, indicating it’s not recognized.
    • Solution: Ensure you’ve installed the MySQL client correctly and that its executable is in your system’s PATH environment variable. Revisit the installation steps if needed.
  • Incorrect directory for dolt commands: If dolt commands aren’t working as expected (e.g., dolt status says “not a dolt repository”), you might not be in the correct directory.
    • Solution: Always cd into the directory where you ran dolt init before executing dolt CLI commands.

Summary

You’ve just completed a significant milestone in your Dolt journey! In this chapter, you’ve moved from theory to practice, achieving several key objectives:

  • Dolt Installation: Successfully installed the Dolt CLI on your operating system or pulled its Docker image, verifying the setup.
  • SQL Client Setup: Configured a MySQL-compatible client to interact with Dolt.
  • Database Initialization: Created your very first version-controlled Dolt database using dolt init.
  • Server Operation: Started the Dolt SQL server and connected your SQL client to it.
  • Data Manipulation: Created a SQL table and inserted initial data, just like with any relational database.
  • Git-for-Data Workflow: Applied the core dolt status, dolt add, and dolt commit commands to version your data and schema.
  • Practical Application: Completed a mini-challenge to reinforce the fundamental commit cycle, building muscle memory for data versioning.

You now have a fully functional, version-controlled database and a practical understanding of the core “Git-for-Data” workflow. This foundation is critical for everything we’ll do next, as every advanced feature of Dolt builds upon these basic operations.

In the upcoming chapter, we’ll dive deeper into exploring your data’s history, understanding dolt log and dolt diff to see what changes have been made, and beginning to unlock the true power of time travel for your data. Get ready to explore the past!

References

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.