How to Query Data in Dolt: 3 Methods Using MySQL-Compatible Syntax

You can query data in Dolt using standard MySQL 8 syntax through the dolt sql CLI command, an interactive REPL, or a running dolt sql-server process that accepts connections from any MySQL client.

Dolt is a version-controlled SQL database that combines Git-like versioning with MySQL-compatible querying. Whether you need a quick one-off command or a persistent server connection, Dolt exposes your repository data through a full-featured SQL engine built on the same components that power MySQL 8. This guide covers the three primary methods to query data in Dolt based on the source implementation in dolthub/dolt.

How the Dolt SQL Engine Works

When you run a query in Dolt, the request flows through a layered architecture that bridges Git-style storage with SQL execution. In go/cmd/dolt/commands/sql.go, the CLI entry point parses flags like -q to determine whether to execute a single statement or start an interactive session. The actual SQL processing happens in go/libraries/doltcore/sqle, which implements the parser, optimizer, and executor using the go-mysql-server library.

The storage layer in go/libraries/doltcore/doltdb maps SQL tables to Dolt's immutable Noms value store, handling branch isolation and commit semantics. Dolt-specific features—such as the dolt_log table and dolt_checkout() procedure—are implemented in go/libraries/doltcore/sqle/dtablefunctions, allowing you to query version metadata using standard SELECT statements.

Method 1: Execute One-Off Queries with the CLI

For quick queries or shell scripts, use the dolt sql command with the -q flag. This passes your SQL string directly to the engine in go/libraries/doltcore/sqle and returns results immediately without entering an interactive session.

# List all rows in the customers table

dolt sql -q "SELECT * FROM customers;"

# Count recent orders using a WHERE clause

dolt sql -q "
  SELECT COUNT(*) AS recent_orders
  FROM orders
  WHERE order_date > '2023-01-01';
"

The -q flag triggers the ExecuteSelect path in the SQL engine, streaming results back to the console before exiting. This method is ideal for CI/CD pipelines or automation scripts that need to extract data from a specific commit or branch.

Method 2: Query Interactively Using the REPL

Running dolt sql without the -q flag starts an interactive Read-Eval-Print Loop (REPL) that maintains a persistent connection to your repository. This allows you to run multiple statements, inspect schemas, and switch branches within a single session.

$ dolt sql
dolt> SELECT name, email FROM users WHERE active = true;
+----------+----------------------+
| name     | email                |
+----------+----------------------+
| Alice    | alice@example.com    |
| Bob      | bob@example.net      |
+----------+----------------------+
dolt> CALL dolt_checkout('dev');
dolt> SELECT COUNT(*) FROM tickets;
+----------+
| count(*) |
+----------+
|     1283 |
+----------+
dolt> \q

The REPL handles session state in go/cmd/dolt/commands/sql.go, ensuring that your current branch and transaction context remain consistent across commands. Use CALL dolt_checkout('<branch>') to switch branches without restarting the client, or query version metadata using virtual tables like dolt_log.

Method 3: Connect via MySQL-Compatible Server

For external applications or GUI tools, start dolt sql-server to expose your repository over the MySQL wire protocol. This mode, implemented in go/cmd/dolt/commands/sqlserver/server.go, allows any MySQL 8 compatible client to connect using standard TCP/IP.

Start the server in the background:

# Run a server on port 3307 (default is 3306)

dolt sql-server --port=3307 &

Connect with any MySQL client:

mysql -h 127.0.0.1 -P 3307 -u root

Once connected, run standard queries:

-- Query current data
SELECT * FROM inventory LIMIT 5;

-- Switch to a different branch without restarting the server
CALL dolt_checkout('release-1.2');

-- Query historical state
SELECT * FROM inventory AS OF 'HEAD~1' WHERE qty < 20;

Because the server speaks the MySQL protocol, tools like mysqldump, DataGrip, MySQL Workbench, and ORMs such as TypeORM and Hibernate work without modification. The SQL engine in go/libraries/doltcore/sqle handles query parsing and optimization identically regardless of whether queries arrive via CLI or network connection.

Querying Historical Data with AS OF

Dolt's version control features are exposed as SQL syntax extensions. You can query any commit, branch, or tag using the AS OF clause, which the engine resolves through the storage layer in go/libraries/doltcore/doltdb.

-- Query the main branch as it existed yesterday
SELECT * FROM employees AS OF 'main';

-- Query a specific commit hash
SELECT * FROM employees AS OF 'abc1234';

-- View commit history using the dolt_log virtual table
SELECT commit_hash, message, date 
FROM dolt_log 
AS OF 'main' 
ORDER BY date DESC 
LIMIT 5;

The dolt_log, dolt_diff_*, and dolt_history_* tables are implemented in go/libraries/doltcore/sqle/dtablefunctions, providing relational access to Git-style metadata without requiring external commands.

Summary

• MySQL 8 compatibility: Dolt uses go-mysql-server to provide native support for standard SELECT statements, joins, and aggregate functions.
• Three entry points: Use dolt sql -q for scripts, dolt sql for interactive exploration, and dolt sql-server for external client connections.
• Version-aware querying: Append AS OF <branch|commit> to any table to query historical states, or use dolt_log to inspect commit metadata via SQL.
• Branch switching: Execute CALL dolt_checkout('<branch>') in any SQL session to change the working branch without restarting the client or server.

Frequently Asked Questions

Does Dolt support all MySQL 8 queries?

Yes, Dolt implements the MySQL 8 parser and optimizer in go/libraries/doltcore/sqle, so any valid MySQL 8 SELECT statement works out-of-the-box. Complex joins, subqueries, window functions, and common table expressions (CTEs) are supported. However, Dolt may not implement every MySQL-specific configuration variable or privilege system feature.

How do I query a specific commit or branch without checking it out?

Use the AS OF syntax in your SELECT statement. For example, SELECT * FROM table_name AS OF 'branch-name' queries the data at the tip of that branch, while AS OF 'commit-hash' queries a specific revision. This feature is handled by the storage layer in go/libraries/doltcore/doltdb without modifying your working set.

Can I use standard MySQL tools like phpMyAdmin or TablePlus with Dolt?

Yes, when running dolt sql-server, Dolt speaks the MySQL wire protocol on port 3306 (or your specified port). You can connect using the MySQL CLI, DBeaver, DataGrip, phpMyAdmin, or any ODBC/JDBC driver. The server implementation in go/cmd/dolt/commands/sqlserver/server.go ensures protocol compatibility.

Is there a performance difference between dolt sql and dolt sql-server?

Both use the same SQL engine in go/libraries/doltcore/sqle, so query execution performance is identical. The difference lies in connection overhead: dolt sql spins up a temporary engine instance for each invocation, while dolt sql-server maintains a persistent process with connection pooling, making it more efficient for high-volume application traffic.

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