Getting Started with Dolt and Claude

5 min read

This guide will help you set up Dolt (a version-controlled SQL database) with Claude Code, enabling you to use AI to make database changes that you can track, review, and manage through the Dolt Workbench.

What You’ll Accomplish#

By the end of this guide, you’ll be able to:

Use Claude Code to make changes to a Dolt database using natural language
View all changes Claude makes in the Dolt Workbench
Track database modifications with version control (commits, branches, diffs)

Step 1: Install Dolt#

For Mac:#

Option 1 (Homebrew):

brew install dolt

Option 2 (Install Script):

sudo bash -c 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'

For Linux:#

sudo bash -c 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'

For Windows:#

Option 1 (Chocolatey): choco install dolt
Option 2 (MSI Installer): Download from Dolt Releases
Option 3 (winget): winget install DoltHub.Dolt

Verify Installation:#

dolt version

Step 2: Configure Dolt#

Set your name and email (similar to Git):

dolt config --global --add user.email "you@example.com"
dolt config --global --add user.name "Your Name"

Step 3: Install Claude Code (or Another AI Agent)#

Follow the instructions at https://docs.claude.com/en/docs/claude-code to install Claude Code for your platform.

Once installed, verify by running:

claude --version

Note: While this guide uses Claude Code, Dolt works with other AI agents and coding assistants that can read documentation files and execute SQL commands. The AGENT.md file (covered in Step 5) provides context that helps any AI tool understand how to work with Dolt databases.

Step 4: Install Dolt Workbench#

The Dolt Workbench is a GUI application that lets you visualize your database and Dolt’s version control features.

Install Dolt Workbench:#

Mac:

Download from Mac App Store
Or download from GitHub Releases

Windows:

Download from Microsoft Store
Or download from GitHub Releases

Linux:

Download AppImage from GitHub Releases

Note: While Dolt is compatible with any MySQL workbench or database client (like MySQL Workbench, DBeaver, or DataGrip), only the Dolt Workbench displays Dolt’s unique version control features such as commit history, diffs, branches, and uncommitted changes directly in the interface.

Step 5: Clone the Stocks Database#

Clone the stocks database from DoltHub:

# Clone the stocks database
dolt clone post-no-preference/stocks
cd stocks

This database contains historical stock market data that you can query and analyze with Claude.

Step 6: Set Up Claude Code with Dolt’s AGENT.md#

Dolt includes an AGENT.md file that helps Claude understand how to work with Dolt databases.

Extract the AGENT.md file:#

# Navigate to your Dolt database directory
cd stocks

# Export Dolt's AGENT.md to a CLAUDE.md file
dolt docs print AGENT.md > CLAUDE.md

This creates a CLAUDE.md file in your database directory that Claude Code will automatically read.

Start Claude Code:#

# From within your Dolt database directory
claude

Claude Code will detect the CLAUDE.md file and understand it’s working with a Dolt database.

Step 7: Start a Dolt SQL Server#

To allow the Dolt Workbench to connect to your database, start a Dolt SQL server:

# From your database directory
dolt sql-server --host 0.0.0.0 --port 3306

Leave this terminal running. The server will be accessible at localhost:3306.

Step 8: Connect Dolt Workbench to Your Database#

Connect to Your Database:#

Launch Dolt Workbench
Click “Add Database”
Enter connection details:
- Host: localhost
- Port: 3306
- Database: stocks
- User: root
- Connection Type: MySQL
- Use SSL Not checked
Click “Connect”

You should now see your database tables and can browse your data!

Step 9: Use Claude to Make Database Changes#

Open a new terminal window (keep the SQL server running) and navigate to your database directory:

cd stocks
claude

Example Prompts to Try#

Now that Claude has access to the database. Let’s try a few reads and writes. These prompts will work with any database, but only Dolt will stage the writes so you have insight into what the agent has changed.

Query stock data:

Show me the top 10 stocks by trading volume from the most recent date

Analyze trends:

Calculate the average closing price for Apple stock over the last year

Add custom views:

Create a view that shows daily price changes as percentages for all stocks

Write to the database (try this!):

Add a fictional DOLT IPO that happened 3 weeks ago. Make the change on the main branch and don't commit the changes; leave them staged. Populate the relevant tables with 3 weeks of daily stock data. Use an opening price of $50, and create realistic daily trading data with some volatility - maybe it went up to $65 in week 2 and settled around $58 by week 3. Include open, high, low, close prices, and volume for each trading day.

This write operation is particularly interesting because Claude will need to examine the database schema, understand which tables to populate, generate realistic stock data for multiple trading days (skipping weekends), and you’ll be able to see all the inserted rows in the Dolt Workbench’s uncommitted changes view. You can review exactly what Claude added before committing!

Claude will execute SQL commands to make these changes. After each operation:

Switch to Dolt Workbench - You’ll see the changes reflected in real-time
Check the “Uncommitted Changes” tab - You can see exactly what Claude modified
View the Diff - See row-by-row changes

Step 10: Commit Claude’s Changes#

After reviewing what Claude did in the Workbench, you can commit the changes:

Option 1: Using Claude Code:

Commit the changes with the message "Added stock analysis view"

Option 2: Using the terminal:

dolt add .
dolt commit -m "Added stock analysis view via Claude"

Option 3: Using Dolt Workbench:

Click the “Commit” button in the Workbench
Enter a commit message
Click “Commit Changes”

Step 11: View History in Workbench#

In the Dolt Workbench:

Click on the “Commit Log” tab
You’ll see all commits, including those made by Claude
Click on any commit to see what changed
You can diff between any two commits

Tips & Best Practices#

Review Before Committing: Always check the Workbench to see exactly what Claude changed before committing
Use Branches: For experimental changes, ask Claude to create a new branch first
Clear Prompts: Be specific with your requests to Claude (e.g., “Show me Apple stock prices for October 2024”)
Rollback Capability: If Claude makes a mistake, you can always revert: dolt reset --hard
View SQL: In Claude Code, you can see the actual SQL queries it’s running

Troubleshooting#

Cannot connect to Dolt server:

Ensure dolt sql-server is running
Check that port 3306 isn’t already in use

Claude doesn’t recognize Dolt commands:

Make sure you created the CLAUDE.md file using dolt docs print AGENT.md > CLAUDE.md
Restart Claude Code after creating the file

Changes don’t appear in Workbench:

Click the refresh button in Workbench
Ensure you’re looking at the correct branch

What’s Next#

We’d love to hear from users about interesting workflows or tools they are thinking about building now that an agent can safely write to the database. Come by our Discord or shoot me an email if you need help with this tutorial or have an idea you want to discuss.

Resources#

Blog