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

> Learn how to query data in Dolt using MySQL compatible syntax. Explore three methods: the dolt sql CLI, interactive REPL, and dolt sql-server.

- Repository: [DoltHub/dolt](https://github.com/dolthub/dolt)
- Tags: how-to-guide
- Published: 2026-03-14

---

**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`](https://github.com/dolthub/dolt/blob/main/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.

```bash

# 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.

```bash
$ 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`](https://github.com/dolthub/dolt/blob/main/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`](https://github.com/dolthub/dolt/blob/main/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:

```bash

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

dolt sql-server --port=3307 &

```

Connect with any MySQL client:

```bash
mysql -h 127.0.0.1 -P 3307 -u root

```

Once connected, run standard queries:

```sql
-- 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`.

```sql
-- 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`](https://github.com/dolthub/dolt/blob/main/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.