How to Collaborate on Dolt Repositories: Git-Style Workflows for SQL Databases

Collaborating on Dolt repositories follows standard Git workflows—fork, clone, branch, commit, push, and merge—while applying them to tables, rows, and schemas using either CLI commands or SQL stored procedures.

Dolt is a MySQL-compatible database that adds version control to data, enabling teams to collaborate on Dolt repositories using familiar source control patterns. Whether you are sharing datasets with analysts or managing schema migrations across environments, Dolt bridges the gap between database operations and Git semantics. This guide covers the complete collaboration lifecycle based on the dolthub/dolt source code, from local branching to remote server deployment.

Understanding Dolt's Git-Style Architecture

A Dolt repository is created with dolt init or obtained by cloning a remote using dolt clone <url>. The repository stores data files and a hidden .dolt directory that contains the commit graph, branch refs, and system tables. According to /README.md, this architecture allows Dolt to track every row-level change while maintaining full SQL compatibility.

System tables such as dolt_status, dolt_log, and dolt_diff_<table> expose version control state directly to SQL queries. These tables let you inspect pending changes and history programmatically, as detailed in go/libraries/doltcore/doltdb/AGENT.md lines 92-108.

Setting Up Your Collaboration Environment

Forking and Cloning Remote Repositories

Anyone can fork a public DoltHub repository (or any remote supporting the Dolt protocol) and then clone their fork locally. Forking creates a separate server-side copy, while dolt clone pulls the entire history and creates a working copy on the developer’s machine.

# Clone a forked repository

dolt clone https://doltremoteapi/dolthub/us-housing-prices
cd us-housing-prices

Configuring Local Remotes

Remotes are stored in the dolt_remotes system table and managed via CLI commands. To add a custom remote:

dolt remote add origin https://doltremoteapi/dolthub/us-housing-prices

You can query configured remotes using SQL:

SELECT * FROM dolt_remotes;

Branching Strategies for Database Development

Branches in Dolt are lightweight pointers to commits, identical to Git's model. The branching commands and their SQL equivalents are documented in go/libraries/doltcore/doltdb/AGENT.md.

Creating and Switching Branches

Create a branch using the CLI:

dolt checkout -b feature/add-sales-data

Or switch branches within a SQL session:

CALL dolt_checkout('feature/add-sales-data');

Querying Branch Metadata

Inspect available branches and current state through system tables:

-- List all branches
SELECT * FROM dolt_branches;

-- Check current branch and working set status
SELECT * FROM dolt_status;

Committing and Sharing Changes

After modifying data with standard SQL (INSERT, UPDATE, ALTER TABLE), you must stage and commit changes to record them in history.

Staging Changes via CLI and SQL

CLI workflow:

dolt add .
dolt commit -m "Add Q1 sales data"

SQL workflow:

CALL dolt_add('.');
CALL dolt_commit('-m', 'Add Q1 sales data');

Pushing to Remote Servers

Upload local commits to a remote using dolt push:

dolt push origin feature/add-sales-data

This transfers new commits to the remote server, making your branch available for pull requests on DoltHub or other hosting platforms.

Pulling and Merging Updates

Synchronize your local repository with remote changes:

dolt pull origin main

This fetches remote commits and merges them into your current branch. For SQL-only environments, use:

CALL dolt_pull('origin', 'main');

Advanced Collaboration Patterns

Running Custom Remote Servers with remotesrv

For on-premises or CI scenarios, Dolt provides remotesrv, a lightweight remote server implementation documented in go/utils/remotesrv/README.md. This tool provides an HTTP file store and gRPC chunkstore API.

Deploy a local remote server:

go install ./go/utils/remotesrv
remotesrv --dir /tmp/dolt-remote --http-port 8080 --grpc-port 50051 &

Configure your repository to use this custom remote:

dolt remote add ci http://localhost:8080/org/repo
dolt push ci main

CI Integration for Data Validation

Dolt includes built-in CI capabilities to validate data integrity on pull requests. According to go/libraries/doltcore/doltdb/AGENT.md (lines 10-30), you can initialize CI configurations and run validation checks:

dolt ci init
dolt ci run

These commands integrate with DoltHub to enforce data quality gates before merging changes, ensuring that schema modifications or data imports meet team standards.

Summary

• Dolt applies Git semantics to SQL databases, enabling teams to collaborate on Dolt repositories using familiar fork, branch, commit, and merge workflows.
• All version control operations are available via both CLI commands and SQL stored procedures, allowing seamless integration with existing database tools.
• System tables like dolt_status, dolt_branches, and dolt_diff_<table> provide programmatic access to repository state.
• For enterprise scenarios, the remotesrv utility enables self-hosted remote servers, while built-in CI commands support automated data validation.

Frequently Asked Questions

How does Dolt branching differ from Git branching?

Dolt branching uses the same underlying mechanics as Git—lightweight pointers to commits in a Merkle tree—but applies them to database state rather than source code. While Git tracks file changes, Dolt tracks row-level modifications, schema changes, and table additions. You can switch branches instantly using dolt checkout or CALL dolt_checkout(), and each branch maintains an independent working set of data.

Can I use standard SQL tools to collaborate on Dolt repositories?

Yes. Dolt is fully MySQL-compatible and exposes version control functions as stored procedures. You can connect standard clients like MySQL Workbench, TablePlus, or programmatic drivers to a dolt sql-server and execute CALL dolt_commit(), CALL dolt_push(), and other commands. This allows data analysts to collaborate using familiar SQL interfaces while still benefiting from Git-style version control.

How do I resolve merge conflicts in Dolt?

When dolt pull or dolt merge encounters conflicting changes to the same row, Dolt marks the conflict in the working set. You can inspect conflicts using the dolt_conflicts system table or dolt conflicts cat CLI command. Resolve conflicts by updating the rows with the desired values, then stage the resolution with dolt add and complete the merge with dolt commit. For automated resolution, Dolt supports custom merge strategies through SQL procedures.

What is the difference between DoltHub and a self-hosted remote?

DoltHub is a cloud-hosted platform (similar to GitHub) that provides a web interface for browsing Dolt repositories, creating pull requests, and managing access control. A self-hosted remote uses the remotesrv tool documented in go/utils/remotesrv/README.md to run an HTTP/gRPC server on your own infrastructure. Self-hosted remotes are ideal for air-gapped environments, CI pipelines, or teams requiring complete control over data storage location and access patterns.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}