DoltHub Blog - Latest Posts

How Dolt Represents and Evaluates Queries: A Case Study

Nick Tobey — Mon, 20 Apr 2026 00:00:00 GMT

Want to know a cool secret about database engines? They’re literally the same thing as compilers.

At my previous job, I worked on Google’s internal Java compiler. Now, I’m one of the developers of Dolt, the first version-controlled SQL database, as well as go-mysql-server, the SQL engine that Dolt depends on.

It turns out that the skills and techniques that I first learned while writing a compiler are the exact same techniques that Dolt uses in its database engine. And that’s because when you break it down, database engines are just a domain-specific compiler:

General-purpose compilers turn human-readable source code into machine-readable programs that manipulate variables and produce side-effects.
SQL engines turn human-readable SQL queries into machine-readable execution plans that manipulate table columns and produce a stream of rows.

Most compiler concepts map directly onto database engines. Some database engines like SQLite even work by producing bytecode that executes in a special-purpose VM.. Dolt doesn’t do that, but it does create an abstract syntax tree almost exactly like one you would see in any other interpreted language.

The main difference is that in most languages, evaluating a syntax tree produces a return value and side effects. In Dolt, evaluating a syntax tree produces an iterator. This also means that each intermediate node in the tree is an iterator defined in terms of one or more child iterators. This approach is often called the volcano model or iterator model of database engine design.

This means that database engines can have the same types of bugs as traditional languages and a lot of the same thorns. We recently fixed a correctness issue in Dolt that does a good job demonstrating this. You can find the writeup and the fix here.

To trigger the incorrect behavior, you needed a query that looked like this.

CREATE TABLE ab (a INT PRIMARY KEY, b INT);
CREATE TABLE three_pk (pk1 TINYINT, pk2 TINYINT, pk3 TINYINT, col TINYINT, PRIMARY KEY (pk1, pk2, pk3));
SELECT * FROM ab AS ab1 WHERE EXISTS (
  SELECT * FROM ab AS ab2 WHERE EXISTS (
    SELECT * FROM ab AS ab3 WHERE EXISTS (
      SELECT * FROM three_pk WHERE pk1 = ab1.a and pk2 = ab2.a and pk3 = ab3.a
    )
  )
);

Running this query on older versions of Dolt would trigger a panic. To understand why, let’s talk about scopes.

Scopes#

Scopes are something that every programmer has to deal with even if they don’t realize it. It’s how programs resolve symbols to the things that are actually being referenced.

SQL queries reference tables and columns by name, and Dolt needs to map those names onto the tables and columns they represent. This is not as simple as it looks, because the same name can refer to different tables based on where it appears in the statement. The following is a valid SQL query:

SELECT * FROM test_table WHERE EXISTS (SELECT * FROM test_table where test_table.id = 1) and test_table.id = 2;

In this query, there are two tables named test_table and two filter conditions that name test_table. Which condition refers to which child iterator? If Dolt resolves these names incorrectly, it will produce incorrect output.

Two names can also refer to the same table, again depending on where the names appear. Consider this simple query with a two-part primary key:

CREATE TABLE test_table(pk1 INT, pk2 INT, PRIMARY KEY (pk1, pk2));
SELECT * FROM (SELECT * FROM test_table WHERE test_table.pk2 = 1) AS table_alias where table_alias.pk1 = 2;

This query can be optimized into a simple table lookup, but only if Dolt can detect that the two WHERE clauses refer to the same table, even though the two clauses use different table names.

Thus, it does not suffice for Dolt to simply keep a global dictionary that maps names onto tables, because the rules for resolving references are not global. Different parts of the query introduce their own namespace, which changes how names are resolved. These namespaces are scopes.

So how does a database engine keep these scopes straight? How are table references actually represented in the abstract syntax tree?

Scopes at Analysis Time#

The most naive approach is to simply store the same names in the AST as they appear in the query. Then, whenever the engine wants to analyze, optimize, or execute part of the tree, it resolves the name using scope rules. This works, but it’s incredibly brittle:

Any optimization that transforms the AST needs to be very careful. If a node contains a reference, moving that node to another part of the tree could change the meaning of that reference, and change the behavior of the query. Whenever the engine transforms the tree, it would need to update any references.
In fringe cases, a transformation may result in an impossible tree, where we need to reference a table but it’s impossible to do so because that table’s name is being shadowed by another.
Needing to resolve references repeatedly is slow and wasteful.

This is actually how Dolt used to operate years ago, and it was the source of subtle bugs. So we switched to a better approach: when analyzing a query, we assign incrementing globally unique IDs to tables and columns. Every reference is resolved once, and then the name gets replaced with the ID. Since each ID always refers to the same table or column, we can safely modify the AST without any risk of changing the query’s meaning.

But this is only half of the situation of scopes.

Scopes at Runtime#

It’s not enough to just be able to resolve references to the table or column they represent, we also need to track those values while the query is running. Operations that produce column values need to be able to send those values to the operations that read them.

In general-purpose languages, this might be accomplished with registers, or by writing to values in memory. But SQL queries are declarative and functional and don’t have state: when evaluating a node in the syntax tree, the iterator it produces is often a pure function of:

Columns inherited from parent nodes
- Example: In SELECT id FROM a WHERE EXISTS (SELECT id FROM b WHERE a.id = b.id), the inner query references a column from the outer query.
Columns returned from child nodes
- Example: In SELECT id FROM (SELECT id FROM a) AS a_alias where a_alias.id = 1, the outer query references a column from the inner query.
Columns defined in sibling nodes
- Example: In SELECT id FROM a JOIN LATERAL (SELECT id FROM b WHERE a.id = b.id), the right side of the join references a column from the left side of the join.

Each of these columns can have multiple values over the lifetime of the query, but only one at a time. A SQL engine needs a strategy to represent this internally.

A naive approach might be to maintain a mapping from each column name to its current value. Except as we already saw, names don’t map one-to-one onto columns. In fact, it’s perfectly valid MySQL to for a table alias to have multiple columns with the same name. For example, the below query produces a table alias with two columns both named pk.

CREATE TABLE test_table(pk INT PRIMARY KEY);
SELECT * FROM (SELECT * FROM test_table JOIN test_table) AS table_alias;

Even more problematic is that a table alias column might have no name:

SELECT * FROM (SELECT 1+1) AS table_alias;

In either case, it’s not possible to reference these columns in filters, but they can still impact the results of the query if the alias is used in a SELECT *.

So if we can’t track values by their column name, another approach might be to use the unique column IDs we discussed in the previous section. But there could be many such IDs, and each node in the AST only cares about a small number of them. Managing lots of small maps is also not very performant, and we care about performance.

Fortunately, there’s an approach to that gives us both clarity and performance. Every scope in a SQL query always has the same number of columns. So the number of columns referenceable from any node in the AST is a constant value that can be determined by statically analyzing the query. The number of columns in that node’s iterator is also a constant value.

Examples:

A table reference with N columns produces an iterator that returns a list of five values.
A SELECT col1, col2, ... colN WHERE EXISTS (...) construct creates N referenceable columns for every node within the subquery.

Each node can have an array where we store the value of each of these columns. Each element in the array corresponds to a different column. Before we evaluate the query, we can analyze the AST to determine which column each array element represents. Now if we want to represent an expression that reads a column, we don’t need to store the name of the column in the AST, and we don’t need to store that column’s globally unique ID either: all we need to store is the offset within that node’s own array corresponding to that column.

This is the approach that Dolt uses: it analyzes the tree, determines the exact set of columns visible to each node, and replaces column references with the correct offset into that node’s array that will contain that column at runtime.

We can illustrate this process with some diagrams. In each case, we show the nodes in the AST, and each node has both an ordered sequence of columns it produces (the output schema), and an ordered lists of columns it can reference (the input schema). The color of each cell indicates the node that originally produced the value. Note how nodes can contain column references from children, siblings, or parents, but in each case the number of columns can be statically determined.

A node referencing its child:

CREATE TABLE test_table(a int, b int, c int);
SELECT c+1 AS d FROM test_table;

Would result in an AST that looks like this:

A node referencing its parent:

CREATE TABLE test_table(a int, b int, c int);
SELECT a FROM test_table AS t1 WHERE EXISTS (SELECT b FROM test_table AS t2 WHERE t1.a = t2.a)

Would result in an AST that looks like this:

In order for this optimization to work correctly, every node must agree on how many columns it receives from each of their children, and how many columns are visible from parent and sibling scopes. If these numbers don’t agree, it could lead to situations where Dolt accesses the wrong value at runtime, or accesses the array out-of-bounds and panics.

So with all this in mind, let’s look back at the query that triggered the bug:

CREATE TABLE ab (a INT PRIMARY KEY, b INT);
CREATE TABLE three_pk (pk1 TINYINT, pk2 TINYINT, pk3 TINYINT, col TINYINT, PRIMARY KEY (pk1, pk2, pk3));
SELECT * FROM ab AS ab1 WHERE EXISTS (
  SELECT * FROM ab AS ab2 WHERE EXISTS (
    SELECT * FROM ab AS ab3 WHERE EXISTS (
      SELECT * FROM three_pk WHERE pk1 = ab1.a and pk2 = ab2.a and pk3 = ab3.a
    )
  )
);

The simplest explanation for the root cause was this:

When Dolt optimized this query, it would transform it into multiple nested join nodes.
Each of these join nodes introduced a new table alias that could be referenced by its children.
If a join condition referenced a column, then Dolt would need to compute the offset of that column in the join node’s array of column references. This required knowing how many of the columns in the array came from parent scopes, how many came from sibling scopes, and how many were from that node’s children.
The logic for computing how many columns in the input schema came from outer scopes did not consider the fact scopes could be introduced in the middle of a nested join. This made it impossible to correctly calculate this for every node in the AST.

There were some attempts made to account for this issue, but in adjusting the calculations for common queries, it broke the calculations for less common queries. Ultimately, these adjustments made the logic harder to reason about. In the end, we fixed the issue by completely rewriting how we generated iterators during join in order to make it simpler to analyze them.

The full scope of the issue and the fix are more complicated, but this was the general idea.

I hope this illuminates what actually goes on inside a database engine.

As always, if you have any thoughts about database design, or if you’re curious how a version-controlled database can benefit you, then you should hop into our Discord and we’d love to discuss it with you.

Vibe-Coded Agents for Vibe-Coded Issues

Elian Deogracia-Brito — Fri, 03 Apr 2026 00:00:00 GMT

Dolt is a SQL database with Git-style version control. It speaks the MySQL wire protocol, so any MySQL client can connect to it, and it adds version control primitives on top: branch, merge, diff, clone, and push, all over SQL. Under the hood, go-mysql-server handles the SQL execution layer between clients and Dolt’s storage engine.

Gas Town builds on those primitives. It is a multi-agent coding orchestrator built on write-only code, and as it scaled to hundreds of concurrent workers, those agents were constantly branching, merging, and committing against Dolt. That load surfaced a new class of issues: vibe-coded issues.

To be clear, I’m not throwing shade. After all, I’m familiar with running agents in parallel to work through MySQL correctness work, but we’re also entering a new ballpark here. It’s hard to expect clear reproductions when hundreds of agents unpredictably use a tool at the same time. I would know, since I recently spent hours trying to get a reproduction on a couple of Gas Town Dolt issues, some leading to nowhere.

So, in the spirit of Vibe Code vs Trad Code, sometimes you fight fire with fire. I’ve “vibe-coded” grunt, a Go CLI that provisions isolated Docker agent environments in parallel but with options this time around.

The Problem: Pre-Baked Containers Don’t Scale#

The obvious answer to “Gas Town introduced these issues, why not use Gas Town to reproduce them?” is that issue reproduction isn’t really a Gas Town job. Gas Town is built for long-running, write-only work where persistent agent memory via Beads accumulates across sessions. Reproducing a GitHub issue is the opposite in that it’s a short-lived, discrete task where you spin up, get a failing test, and tear down.

My previous setup relied on a single container image with all dependencies pre-baked. That worked when I was targeting a specific repository and task. The moment I needed to handle two repos with different requirements, it broke down and I had to manually update things.

What I actually wanted was to configure at launch time via CLI flags what each agent container and repo needs: which post-install scripts to run, how much memory to give it, what prompt to start it with.

So I pointed an agent at the problem. I had it follow Go best practices from the official docs and address IDE warnings as it went, rather than letting it freewheel. The result is grunt. I can read the code, which puts it firmly in Trad Code territory even if it got there via an agent.

How grunt Works#

One command does everything:

grunt agent create -name gms -repo dolthub/go-mysql-server

create resolves the repo’s configuration, builds the Docker image with the right post-install scripts applied, clones the repo, starts the container, and drops you straight into a zellij session with Claude already running. There is no separate start step.

The nice part is that grunt agent create -repo dolthub/dolt already knows what that repo needs without me specifying anything. dolthub/dolt needs CGo build dependencies plus bats for its test suite. dolthub/go-mysql-server needs something lighter. That comes from the configuration layer, covered in the next section. Even if you don’t have a config, it’ll figure out the GitHub URL automatically for any new repositories.

If I want to override the post-install scripts or provider (only claude so far) for a specific run, I pass them directly:

grunt agent create -name dolt -repo dolthub/dolt -repo dolthub/go-mysql-server -issue 1234 \
  -post-install go,bats,dolt-cgo-deps \
  -provider claude

When I have several issues to chase at once, -d starts the container in the background and hands control back immediately. Then I attach to whichever is idle.

grunt agent create -d -name dolt -repo dolthub/dolt -issue 10782
grunt agent create -d -name gms -repo dolthub/go-mysql-server
grunt agent ls
ID                 STATE    ACTIVITY  PROVIDER  REPOS                         ISSUES              CREATED
gms-41b27c1c       running  -         claude    dolthub/go-mysql-server (+2)  10190               2026-03-27T18:20:49Z
gms-c35d524e       stopped  -         claude    dolthub/go-mysql-server (+1)  dolthub/dolt#10757  2026-03-30T20:12:06Z
dolt-d32698b0      running  working   claude    dolthub/dolt                  10782               2026-03-31T17:16:23Z
gms-a573c42c       running  idle      claude    dolthub/go-mysql-server (+1)  -                   2026-04-01T17:39:20Z
grunt agent attach gms-a573c42c

For changes I want to stick across all runs of a repo, I use grunt config set. I’ll usually do this when working on any new repo to set their post-install scripts.

grunt config set branch.prefix -value elian -repo dolthub/dolt
branch.prefix[dolthub/dolt]=elian

grunt config ls -repo dolthub/dolt
$ grunt config ls -repo dolthub/dolt
agent.provider=claude
agent.memory-limit=8g
branch.prefix=elian
issue.prompt=Create a failing reproduction for the following issue {{....
repo.post-install=go,bats,expect,dolt-cgo-deps
repo.services=

That config ls output is the resolved view of a three-layer system. The UX borrows directly from git config.

Per-Repo Config#

Rather than making users configure everything from scratch, grunt ships with per-repo defaults embedded directly in the binary using //go:embed. Each supported repo gets one JSON file covering the two things that vary most: which post-install scripts to run and a default prompt to seed the agent with.

{
  "scripts": ["go", "bats", "expect", "dolt-cgo-deps"],
  "prompt": "Create a failing reproduction for the following issue {{.IssueRef}} under the relevant available repositories..."
}

Adding a new repository means adding one JSON file. On top of those sit two user-owned layers: a global config that applies across all repos and a per-repo override. Every lookup walks the same three layers.

func (s ProfileService) AgentProvider(repo string) (string, error) {
    profile, err := s.Store.Load()
    if err != nil {
        return "", fmt.Errorf("load profile: %w", err)
    }
    if provider, ok := profile.RepoAgentProviders[repo]; ok {
        return provider, nil
    }
    return profile.AgentProvider, nil
}

This works fine for the number of config values grunt has today. It’s worth noting that the agent duplicated this walk across every accessor instead of merging the layers once at load time. A cleaner approach would resolve everything in Load() and let accessors just read fields. With only a handful of values, this is not a real problem yet, but it’s worth revisiting.

Adding a New Agent Type#

grunt only ships with Claude today, but it was designed so that swapping in a different agent is one interface implementation away. Each agent type implements AgentProvider, which covers everything that varies between providers, including how to set up the agent in the Docker container, where to find the agent’s config files, how to read its activity status, and what command to launch it with.

type AgentProvider interface {
    Name() string
    Spec() Spec
    PrepareRuntime(input RuntimeInput) (RuntimeOutput, error)
    ActivityStatusPath(workspaceRoot string) string
    ReadActivityStatus(workspaceRoot string) (string, error)
    EnsureGlobalConfig(paths config.Paths) error
    SaveAPIKey(key string, paths config.Paths) error
    ConfigPaths(paths config.Paths) ConfigPaths
    Validate() error
}

PrepareRuntime handles the container setup by returning the Docker mounts, environment files, and build commands specific to that provider. Spec returns the startup command and shell. Those get passed into a zellij layout file that grunt generates at runtime using Go’s text/template (has also been useful in other templates i.e. the Dockerfile).

layout {
    tab {
        pane name="Claude" command={{ printf "%q" .StartupCommand }}
    }
    new_tab_template {
        pane name="Shell" command={{ printf "%q" .PaneShell }}
    }
}

Zellij is a terminal multiplexer, similar to tmux, that lets grunt give each agent its own named panes. Because the layout is generated from a template, a different provider produces a different layout with no special casing anywhere in the terminal code. Provider selection is a single switch:

func LookupAgentProvider(name string) (AgentProvider, error) {
    switch strings.ToLower(strings.TrimSpace(name)) {
    case "", domain.DefaultProvider:
        return ClaudeProvider{}, nil
    default:
        return nil, fmt.Errorf("%q: %w", name, errUnsupportedProvider)
    }
}

Conclusion#

grunt is a vibe-coded tool for reproducing issues caused by a vibe-coded tool. That is about as recursive as it gets. We could go on about each aspect of implementation, but the above represents the main goal of these ephemeral configurable agent instances. It’s readable-enough, and it works.

It’s already helped me spin up multiple reproductions in parallel and close issues faster. I’ve also gotten new ideas on putting this against CI flaky tests in the background too. If you have questions about the setup or want to dig into Dolt, come find us on Discord. We are always happy to talk Go.

Branch Permissions in the Hosted Dolt Workbench

Taylor Bantle — Thu, 12 Mar 2026 00:00:00 GMT

Hosted Dolt’s SQL workbench is a great collaboration tool for teams looking for a modern, easy-to-use UI for your version-controlled database. Its permission model allows for infinite users with varying access to your database.

In addition to user roles, Dolt supports branch permissions, which let you limit access of certain branches to all or some users. Hosted Dolt now supports branch permissions directly from the workbench UI.

Background and implementation details#

Restricting access to certain branches is a common workflow on GitHub. Users want to prevent direct writes to their main branch, instead only allowing reviewed and approved pull requests to make it into production code. We have a synonymous branch permission model on DoltHub, which we released a few years ago.

The online nature of Hosted Dolt is different from the offline model of DoltHub and GitHub. And unlike DoltHub, there are two layers of users on Hosted: Hosted application users (the user that logs into hosted.doltdb.com) and SQL users (users that connect to the SQL server or workbench).

For the workbench specifically, depending on the role of the application user (via organization roles or deployment collaborators) an internal SQL user with corresponding permissions will be used to connect to the workbench. If you have this feature enabled in your deployment settings, you’ll see them here:

mysql> select host, user from mysql.user where user like 'hosted-ui-%';
+------+------------------+
| host | user             |
+------+------------------+
| %    | hosted-ui-admin  | -- all writes, including GRANT OPTION privilege
| %    | hosted-ui-writer | -- all writes,  does not include GRANT OPTION privilege
| %    | hosted-ui-reader | -- read-only for all branches
+------+------------------+
3 rows in set (0.037 sec)

Dolt’s branch permission model initially included three available permissions - admin, write, and read. Creating a branch control for branch main with permission read would prevent all of the above users from writing to main.

One of our customers requested a featured where their organization members can make changes on a branch, create a pull request on the workbench, and merge this branch into main, but cannot write directly to main. This is more similar to the GitHub/DoltHub model and makes sense for a workbench product that enables this kind of collaboration on data.

So we added an additional branch permission to Dolt - merge. Creating a branch control for branch main with permission merge would prevent all users from writing to main, with the exception of the dolt_merge and dolt_commit SQL procedures, which are used when merging a pull request from the workbench.

While all changes in Dolt are version-controlled, a branch permission of this nature creates even greater oversight and transparency for what changes are making it into your production database.

How it works#

Suppose Tim has a Hosted database to keep track of employees and teams at DoltHub. Tim hired a Human Resources employee to manage this database, but they are not SQL savvy and he does not want them to make changes to main without reviewing their pull requests first.

First, Tim adds the HR employee as a collaborator with write permissions in his deployment settings.

Next, Tim launches the workbench and navigates to the Settings tab, which will have a “Branch Protections” form. Only deployment admin have access to this Settings tab.

He adds branch main with permission level Merge. He can add any branch or branch name pattern here.

Note that this feature only affects users with Write permission on the deployment. Readers will always only have read-only access to the workbench and admin will always have full access.

Now, the new hr-employee user logs in and accesses the workbench. They have been tasked with adding a new “Human Resources” team and adding themselves as an employee. You can see that the built-in cell buttons makes this easy and does not require knowledge of SQL.

However, hr-employee cannot make changes directly to main since Tim has prevented that with branch permissions.

hr-employee must create a new branch to make this change.

This time adding the “Human Resources” team is successful, since the branch protection only affects the main branch.

hr-employees adds to employees and employees_teams and commits these changes using the “Create commit” button. They create a pull request and send to Tim for review.

Tim gives the LGTM, and hr-employee merges the pull request. This is successful because the branch permission allows changes to main via dolt_merge. We can now see these changes on the main branch.

Conclusion#

Hosted Dolt Workbench is a great tool for collaborating with your team on your database, and branch permissions give you even more oversight and control over what makes it into your production database. We take our customer asks seriously, so please contact us with questions or feature requests by filing an issue or reaching out on Discord.

Saying goodbye to the LD1 storage format

Zach Musgrave — Tue, 03 Mar 2026 00:00:00 GMT

We’re building Dolt, the world’s first version-controlled SQL database. Dolt hit 1.0 in 2023, which meant, among other criteria, that we promised forwards storage compatibility:

Dolt 1.0 will be backwards compatible with all further 1.X versions.

Now it’s 2026 and we’re on the verge of releasing Dolt 2.0. In preparation for this release, we’re pursuing some work we’ve long put off: finally removing support for the pre-1.0 format, which we referred to internally and in binary logs as LD1 in honor of our original company name.

Read on for details of why we took this step and how we accomplished it.

The challenge#

In 2022, we first landed Dolt’s current storage format in alpha release. The new storage format diverged radically from what came before, partially summarized here with a before and after view of how tuple values in rows are stored:

Before:

+--------+----------+---------+--------+----------+---------+-----+--------+----------+---------+
| Type 0 | Length 0 | Value 0 | Type 1 | Length 1 | Value 1 | ... | Type k | Length k | Value K |
+--------+----------+---------+--------+----------+---------+-----+--------+----------+---------+

After:

+---------+---------+-----+---------+----------+----------+-----+----------+-------+
| Value 0 | Value 1 | ... | Value K | Offset 1 | Offset 2 | ... | Offset K | Count |
+---------+---------+-----+---------+----------+----------+-----+----------+-------+

Storing tuples in the new format was part of a series of changes to how values are serialized to disk that collectively resulted in over a 5x speedup in our internal benchmarks. We pursued these changes primarily for performance reasons, and it worked: Dolt is now as fast as MySQL on sysbench.

But these changes came at a cost. Because the old and new storage formats were incompatible with one another, and existing paying customers were running their production databases on the old format, we needed to support both storage formats in parallel. We did this the typical way in many programming languages, by introducing interfaces that abstracted away the differences between the two implementations. For example, here’s how we define a table’s storage:

type Table interface {
	HashOf() (hash.Hash, error)
	GetSchemaHash(ctx context.Context) (hash.Hash, error)
	GetSchema(ctx context.Context) (schema.Schema, error)
	SetSchema(ctx context.Context, sch schema.Schema) (Table, error)
	GetTableRows(ctx context.Context) (Index, error)
	GetTableRowsWithDescriptors(ctx context.Context, kd, vd *val.TupleDesc) (Index, error)
	SetTableRows(ctx context.Context, rows Index) (Table, error)
	GetIndexes(ctx context.Context) (IndexSet, error)
	SetIndexes(ctx context.Context, indexes IndexSet) (Table, error)
	GetArtifacts(ctx context.Context) (ArtifactIndex, error)
	SetArtifacts(ctx context.Context, artifacts ArtifactIndex) (Table, error)
	GetAutoIncrement(ctx context.Context) (uint64, error)
	SetAutoIncrement(ctx context.Context, val uint64) (Table, error)
    DebugString(ctx context.Context, ns tree.NodeStore) string
}

Then, under the hood, we had two different implementations of a table: NomsTable for the old storage format, and DoltTable for the new one. The same pattern was repeated for all the other objects needed to materialize data to disk: schemas, indexes, foreign keys, commits, etc.

This all sounds fine so far, except that due to limitations on the time and effort we were willing to expend on this “temporary” state of affairs, these abstractions didn’t fully capture all the necessary differences between the two implementations. This is regrettable but understandable: various database operations tend to be tightly coupled to their on-disk representations for reasons of performance. This meant that, in practice, there were many places in library code where we switched on the storage type of a database. It looked like this:

		if types.IsFormat_DOLT(tm.vrw.Format()) {
			tbl, stats, err = mergeProllyTable(ctx, tm, mergeSch, mergeInfo, diffInfo)
		} else {
			tbl, stats, err = mergeNomsTable(ctx, tm, mergeSch, rm.vrw, opts)
		}

This situation made the “temporary” dual-state of two supported storage formats much harder to unwind. It wasn’t a simple matter of deleting the defunct interface implementations. Rather, we had to carefully disentangle hundreds of different library functions, most of which were not so helpfully named as in the above example, to determine which of them were still used by actual production code in the new storage format. And there were additional difficulties:

Hundreds of tests declared in the old storage format
Functionality spread across five different repositories
Thousands of databases shared publicly on DoltHub, including many of our own, using the old storage format. They would need to be migrated to the new format before we could remove support for it.

In short, removing support for the LD1 format was a daunting prospect. So why do it?

Why bother?#

Removing old code paths and deleting defunct code is a lot of work. It’s just sitting there, not hurting anyone, maybe making your binary slightly larger. Why bother?

Software engineers love clean code and they hate “tech debt”. But at DoltHub, we don’t work for ourselves; we work for our customers. Customers don’t see code, and they couldn’t care less about “tech debt.” They just want a product that works well and their features shipped on time. So if you propose to spend time “paying down tech debt” rather than delivering new features, fixing bugs, or improving performance, you need to justify it with a business reason.

In our case, the business reason was that the dual code paths made it very difficult to reason about what functionality was actually in use, which in turn made it very difficult to change and therefore build new features on top of them. This was especially true deep in the stack, such as where we serialize data to disk.

In particular: for the Dolt 2.0 release, I am adding support for adaptive encoding, which we implemented for the Postgres-compatible version of the database, Doltgres. But Dolt should have it too, because it makes the storage and retrieval of TEXT and BLOB data much faster in a majority of use cases. Customers have been continually surprised that TEXT types have a performance penalty relative to VARCHAR, but they do. Adaptive encoding eliminates that penalty for many customers, so I want to add it.

But doing so in a way that works for existing customers requires the ability to change the encoding of a column independent of its declared SQL type. My first day digging around in the schema-encoding layer in pursuit of these changes left me with more questions than answers, and after a few more days of study I realized that a majority of the complexity and the code in this layer was in service of the old storage format. Even worse, I couldn’t change it without hunting down and eliminating the many, many places those interfaces were used. What started as a limited, targeted pruning of a single interface to make my alternate schema serialization scheme possible quickly spiralled into changes that would result in a panic if it encountered an LD1 format database.

When I saw just how far-reaching the changes required to accomplish my feature were, I became convinced it was time to bite the bullet and unwind the “temporary” dual code paths that had been in place for four years. Our 2.0 release was our last window to stop supporting the pre-1.0 storage format, which meant the time was now.

Making the changes#

Most of these changes were done the old-fashioned way: using an IDE and command line tools like grep to hunt down references to functions, then making changes by hand. There’s not really an automated way to do this kind of change at scale. Coding agents are happy to try, but because of the widespread and delicate nature of the change, you end up spending a lot of time closely examining their work, which for this kind of task can often be slower than simply using the functions of your IDE. But there were a couple exceptions where tool use sped me up:

Hundreds of test cases had been effectively defunct for several years, since they were running on a storage format that wasn’t used in production anywhere. They were testing… something. But not what we wanted. Coding agents were able to convert many of these tests for me in the background while I did other work. Because these tests weren’t doing anything useful in the first place, errors or omissions in their conversion didn’t bother me much, making this an ideal task for an LLM.
The deadcode command was useful throughout the project for finding functions and methods that were unused by any main program.
To migrate the few thousand old-format databases still on DoltHub, I wrote a bunch of scripts that called an admin-only endpoint to migrate them automatically. Where this failed due to size or other unreliability, I migrated them on my local machine with similar scripts.
Once the top-level usages of the old storage format had been safely removed, it became much more tractable to instruct coding agents to begin pruning the now-unused parts of the storage layer. Because the code base was structured in such a way to restrict this part of the code to its own packages, it was relatively quick work to see that the agent hadn’t made any inappropriate changes that could impact a production database simply by reviewing the file paths changed.

After being impressed with Claude’s result in migrating some tests to the new format, I told it to reward itself with a poem, which likewise impressed me enough to share here:

The final result: since last month, Dolt has shed around 100k lines of code, or around 20% of the repo.

% git diff --shortstat v1.81.6
   736 files changed, 22856 insertions(+), 114385 deletions(-)
% sloc .

---------- Result ------------

            Physical :  425520
              Source :  330333
             Comment :  48633
 Single-line comment :  47115
       Block comment :  1521
               Mixed :  2461
 Empty block comment :  81
               Empty :  49096
               To Do :  536

Number of files read :  1500

This makes our binary a bit smaller, which is always nice. But more importantly, it makes it much simpler to reason about various library functions and therefore to add new features. Overall I’ve spent well over a month in pursuit of this goal, which means I must be pretty certain I had a good reason for doing it. It’s satisfying work in its own right, but hard to justify unless coupled with an important business goal.

Conclusion#

The moral of this story: “temporary” changes are permanent and hard to unroll. Oftentimes, the best way to deal with them is to not deal with them at all, just live with the consequences of the past. It’s only when the weight of those past decisions becomes impossible to bear that you should take action this drastic. And even then, you should have a really important reason for doing so.

Want to learn more about Dolt, the world’s first version-controlled SQL database? Visit us on the DoltHub Discord, where our engineering team hangs out all day. Hope to see you there.

Improving Index Selection For Join Queries

Nick Tobey — Fri, 27 Feb 2026 00:00:00 GMT

We take user issues very seriously at DoltHub. We have a pledge to fix bugs in under 24 hours. This pledge is possible because a version-controlled database inherently lends itself to easy reproducibility. And once we can reproduce an issue and attach a debugger, most issues are easy to fix.

But sometimes the issue runs deeper than it seems, and what looked like a short diversion can become an entire journey.

This is the story of one of those times.

The Slow Query#

Back in September, a customer came to use with an innocuous performance issue: their SQL query was taking several minutes to run on Dolt while the same query ran in under a second on MySQL. We immediately clocked this as an issue with Dolt’s execution planner: most likely we were doing a full table scan instead of an index. Dolt has great tooling for understanding execution plans, so we said we’d take a look.

They showed us the query: a straightforward join of five tables. It looked like this:

SELECT
  COUNT(DISTINCT t1.id1) AS id1_count
FROM table_one AS t1
WHERE EXISTS (
  SELECT 1 FROM table_two AS t2 WHERE t2.id1 = t1.id1 AND EXISTS (
    SELECT 1 FROM table_three AS t3 WHERE t3.id2 = t2.id2 AND EXISTS (
      SELECT 1 FROM table_four AS t4 WHERE t4.id3 = t3.id3 AND EXISTS (
        SELECT 1 FROM table_five AS t5 WHERE t5.id4 = t4.id4 AND LOWER(t5.name) LIKE '%foo%'))));"

This is a pretty conventional query. While it contains several correlated subqueries (subqueries that reference their outer scopes), it does so in a very standard way. Any SQL engine worth its salt would transform this into a single tree of table joins. Provided that each table has an index that matches the filter expressions, each join will get implemented as a table lookup.

A join of many tables can be intimidating because of the potential for an exponential explosion in runtime. But for the vast majority of simple queries, even a join of many tables can get optimized to require only a single table scan, regardless of how many tables are being joined.

So given all that, we were surprised that Dolt wasn’t optimizing this query, especially if MySQL was. Dolt is on average faster than MySQL, and when it comes to multi-table joins, Dolt is typically better than MySQL at identifying optimal execution plans.

Whatever the cause, we figured that dolt debug would quickly reveal it and that it would be a simple fix we could knock out in less than a day.

The fact that we’re writing this article now and not back in September should tell you how wrong we were. We had no idea the scope of the rabbit hole we were about to stumble into.

As soon as we began our investigation, we learned that innocuous-looking query was hiding something just underneath the surface. The five tables being joined weren’t actually tables but views. Views are predefined expressions that can be treated like tables in queries and are only executed when the query that references them is executed. And each of these views was itself a multi-table join with nineteen tables each.

So in total, the query wasn’t joining five tables but ninety-five tables.

I won’t reproduce the view definitions here because they’re not that interesting to look at, just a giant soup of INNER JOINs and LEFT JOINs wrapped in a SELECT that extracted and renamed a dozen columns. I’m sure you can picture it.

When it comes to joining nearly a hundred tables, there’s a lot more than can go wrong:

Joining tables is a binary operation: when joining more than two tables, the engine needs to join them a pair at a time. The most efficient order to join tables is not always the same order that they appear in the query, so a good engine should reorder the tables to achieve the best results.
However, not every reordering will produce the same results. If some of the joins are outer joins (typically identified via the LEFT JOIN or FULL OUTER JOIN syntax, which were indeed present in the view definitions), then reordering the tables may change the output of the query. A good engine should not pick an ordering that produce incorrect results.
Additionally, finding the optimal join order is an NP-hard problem. This means that while you can use heuristics to find the best order for specific cases, solving the general case will always scale exponentially with the number of tables, and essentially requires trying every possible combination.

The fact that MySQL could execute this query quickly meant that it was using a heuristic to find the best join plan, or at least a join plan that was good enough. But Dolt was failing to do the same.

Let’s Focus on Indexes#

There’s a lot to dig into regarding how Dolt determines join ordering. But for now, we’ll focus on a single important but easily-understood concept: a plan that uses indexes is typically better than a plan that doesn’t use indexes.

This means that in order to pick the best join order, Dolt needs to identify which indexes will actually speed up the query, and which join orders will leverage those indexes. The logic for this is straightforward in concept, but implementation details vary based on the exact nature of the query. SQL has a lot of language features for writing increasingly sophisticated queries, which various implications that Dolt needs to understand in order to optimize queries correctly.

During the investigation, we realized that we looking at not one but several issues in the join planner, situations where because of some rarely used SQL feature, Dolt was failing to correctly identify when an index would improve a query, or when a specific join would allow an index to be used.

In some ways, this meant the query was an excellent stress test for Dolt’s analyzer. While it appears simple on the surface, it actually makes use of a number of different less-common SQL language features, such as:

Table aliases
Column aliases
Outer joins
Correlated subqueries
Views

It uses all of these features together, with multiple levels of nesting. And the join it’s attempting to optimize is large enough that failing to pick the correct plan results in a noticeable performance degradation.

If there was a query out there that would expose bugs or limitations in the execution planner, it would be this one. Investigating this query helped us uncover and fix many issues in our SQL engine.

Slaying the Hydra#

I started calling this query “The Hydra”. In Greek mythology, the hydra was a beast with many heads, and cutting off one head would cause it to grow two more. Our hydra was a join with many tables, and fixing one blocker would reveal two more in its place.

Each time we wrote a fix, we created a minimal reproduction test and verified that Dolt was now generating an optimal plan for that test case. But each time, the original query resisted our attempts to tame it. Let’s look at some of the issues that we fixed in our quest to slay the beast. This is just the issues that had to do with index selection. There’s even more work that we did beyond this, but we’ll save that for a future blog post.

PR 3380: Generate index lookups for filters that appear in lateral joins #

SQL is a declarative language: queries don’t tell the engine what to do, only what the expected output should be. This means that there’s no way to tell a SQL engine to use an index. Instead, the engine needs to be able to recognize when an index can be used.

In the simplest case, if a filter restricts a column to a constant value, the engine can use an index on that column to get only the matching rows:

-- This can be optimized into an index lookup if |name| is indexed.
DESCRIBE PLAN SELECT * FROM test_table WHERE name = "Tim";

But if the value isn’t constant, an index might not help:

-- Fetch all rows where name is in all caps
-- An index won't help here
DESCRIBE PLAN SELECT * FROM test_table WHERE name = UPPER(name);

Previously, when identifying indexes, Dolt would only use filters that compared a column to a constant, and would ignore filters that compared a constant to a non-constant value. But this was overly cautious, because in the case of subqueries, some non-constant values can still be used in index lookups.

This is because when a query contains subqueries, the subquery may get evaluated multiple times. If the subquery contains references to columns or expressions in the outer query, those values might not be constant for the full duration of the main query. But as long as the value stays the same within each subquery evaluation, it’s okay if it changes between subquery evaluations.

Lateral joins are a language feature that allows expressions on one side of a join to reference columns from the other half of the join. Previously, Dolt would not use filters to guide index selection if the filter appeared in a lateral join subquery but contained references to the outer query:

-- Dolt v1.75.0
DESCRIBE PLAN SELECT * FROM t1 JOIN LATERAL (SELECT * FROM t2 WHERE t1.id = t2.id) query_alias;
+--------------------------------+
| plan                           |
+--------------------------------+
| LateralCrossJoin               |
|  ├─ Table                      |
|  │   └─ name: t1               |
|  └─ SubqueryAlias              |
|      ├─ name: query_alias      |
|      └─ Filter                 |
|          ├─ (t1.id = t2.id)    |
|          └─ Table              |
|              ├─ name: t2       |
|              └─ columns: [id]  |
+--------------------------------+

Dolt now correctly treats these references as effectively constant and optimizes them:

-- Dolt v1.82.6
DESCRIBE PLAN SELECT * FROM t1 JOIN LATERAL (SELECT * FROM t2 WHERE t1.id = t2.id) query_alias;

+--------------------------------+
| plan                           |
+--------------------------------+
| LateralCrossJoin               |
|  ├─ Table                      |
|  │   └─ name: t1               |
|  └─ SubqueryAlias              |
|      ├─ name: query_alias      |
|      └─ IndexedTableAccess(t2) |
|          ├─ index: [t2.id]     |
|          ├─ columns: [id]      |
|          └─ keys: t1.id        |
+--------------------------------+

Users don’t often write lateral joins, but the engine will transform certain subquery expressions into lateral joins, so optimizing lateral joins helps us optimize those subqueries too.

PR 3386: Push filters that contain references to outer scopes.#

The above example showed a query where a filter appears immediately next to the table it references. But sometimes, the filter expression and the table are separated by a join, a view, or a subquery.

In situations like these, we want to rewrite the query to move the filter closer to the table. Often this allows Dolt to use an index it otherwise couldn’t. Even if we don’t end up being able to use an index, applying the filter deeper in the plan means that we reduce the number of intermediate rows by eliminating non-matching rows early.

Just like the above example, Dolt wasn’t pushing filters if they appeared in subqueries and referenced the outer query, because it couldn’t determine that this was safe to do. This resulted in plans with filters that were evaluated later than they could have been, inflating the size of intermediate result sets:

-- Dolt v1.75.0
DESCRIBE PLAN SELECT * FROM t1 JOIN LATERAL
  (SELECT * FROM t2 JOIN LATERAL
    (SELECT * FROM t3) AS t3_alias
  WHERE t3_alias.id = t1.id) AS t2_alias;
+------------------------------------+
| plan                               |
+------------------------------------+
| LateralCrossJoin                   |
|  ├─ Table                          |
|  │   └─ name: t1                   |
|  └─ SubqueryAlias                  |
|      ├─ name: t2_alias             |
|      └─ LateralCrossJoin           |
|          ├─ (t3_alias.id = t1.id)  |
|          ├─ Table                  |
|          │   ├─ name: t2           |
|          │   └─ columns: [id]      |
|          └─ TableAlias(t3_alias)   |
|              └─ Table              |
|                  ├─ name: t3       |
|                  └─ columns: [id]  |
+------------------------------------+

Dolt now correctly rewrites these queries to move the filter directly above the correct subquery table, which can then get transformed into an index lookup:

-- Dolt v1.82.6
DESCRIBE PLAN SELECT * FROM t1 JOIN LATERAL
  (SELECT * FROM t2 JOIN LATERAL
    (SELECT * FROM t3) AS t3_alias
  WHERE t3_alias.id = t1.id) AS t2_alias;
+----------------------------------------+
| plan                                   |
+----------------------------------------+
| LateralCrossJoin                       |
|  ├─ Table                              |
|  │   └─ name: t1                       |
|  └─ SubqueryAlias                      |
|      ├─ name: t2_alias                 |
|      └─ LateralCrossJoin               |
|          ├─ Table                      |
|          │   ├─ name: t2               |
|          │   └─ columns: [id]          |
|          └─ TableAlias(t3_alias)       |
|              └─ IndexedTableAccess(t3) |
|                  ├─ index: [t3.id]     |
|                  ├─ columns: [id]      |
|                  └─ keys: t1.id        |
+----------------------------------------+

PR 3379: Allow introspection into Views #

Views are essentially templates for subqueries. The following two queries should be equivalent, but in older versions of Dolt they produced different plans:

-- Dolt v1.75.0
-- Query without view
DESCRIBE PLAN SELECT * FROM (SELECT * FROM example_table) query_alias WHERE col = 5;
+---------------------------------------+
| plan                                  |
+---------------------------------------+
| TableAlias(query_alias)               |
|  └─ IndexedTableAccess(example_table) |
|      ├─ index: [example_table.col]    |
|      ├─ filters: [{[5, 5]}]           |
|      └─ columns: [col]                |
+---------------------------------------+

-- Query with view
CREATE VIEW query_alias AS SELECT col FROM example_table;
DESCRIBE PLAN SELECT * FROM query_alias WHERE col = 5;
+---------------------------------+
| plan                            |
+---------------------------------+
| Filter                          |
|  ├─ (query_alias.col = 5)       |
|  └─ SubqueryAlias               |
|      ├─ name: query_alias       |
|      └─ Table                   |
|          ├─ name: example_table |
|          └─ columns: [col]      |
+---------------------------------+

When parsing queries, Dolt creates data structures that help it match references in the outer query to the underlying tables in the inner query. However, as a result of the way we were parsing and evaluating views, these data structures were getting discarded, and the analyzer was forced to treat views as opaque objects. This meant that we weren’t able to match filters outside of the view to tables inside the view.

Now, both queries use an index:

-- Dolt v1.82.6
-- Query with view
CREATE VIEW query_alias AS SELECT * FROM example_table;
DESCRIBE PLAN SELECT * FROM query_alias WHERE col = 5;

+---------------------------------------+
| plan                                  |
+---------------------------------------+
| SubqueryAlias                         |
|  ├─ name: query_alias                 |
|  └─ IndexedTableAccess(example_table) |
|      ├─ index: [example_table.col]    |
|      ├─ filters: [{[5, 5]}]           |
|      └─ columns: [col]                |
+---------------------------------------+

PR 3383: When applying indexes from outer scopes, resolve references to table aliases #

Sometimes the filter uses a different name for the table than where the table is used in the query. But Dolt wasn’t always considering table aliases when trying to match indexes to their tables. We added an additional analysis step to consider table aliases when attempting to match a filter in an outer scope to a table in an inner scope:

-- Dolt v1.75.0
DESCRIBE PLAN SELECT * FROM t1 AS t1_alias JOIN LATERAL (SELECT * FROM t2 WHERE t1_alias.id = t2.id) AS inner_query;
+-----------------------------------+
| plan                              |
+-----------------------------------+
| LateralCrossJoin                  |
|  ├─ TableAlias(t1_alias)          |
|  │   └─ Table                     |
|  │       └─ name: t1              |
|  └─ SubqueryAlias                 |
|      ├─ name: inner_query         |
|      ├─ outerVisibility: false    |
|      ├─ isLateral: true           |
|      ├─ cacheable: false          |
|      └─ Filter                    |
|          ├─ (t1_alias.id = t2.id) |
|          └─ Table                 |
|              ├─ name: t2          |
|              └─ columns: [id]     |
+-----------------------------------+

-- Dolt v1.82.6
DESCRIBE PLAN SELECT * FROM t1 AS t1_alias JOIN LATERAL (SELECT * FROM t2 WHERE t1_alias.id = t2.id) AS inner_query;
+------------------------------------+
| plan                               |
+------------------------------------+
| LateralCrossJoin                   |
|  ├─ TableAlias(t1_alias)           |
|  │   └─ Table                      |
|  │       └─ name: t1               |
|  └─ SubqueryAlias                  |
|      ├─ name: inner_query          |
|      └─ Filter                     |
|          ├─ (t1_alias.id = t2.id)  |
|          └─ IndexedTableAccess(t2) |
|              ├─ index: [t2.id]     |
|              ├─ columns: [id]      |
|              └─ keys: t1_alias.id  |
+------------------------------------+

PR 3400: Push Filters inside Projections #

Other times, a subquery renames an expression from the inner SELECT. When Dolt encountered a filter on an aliased expression, it wasn’t unwrapping the alias to see if it referred to an indexed column. This meant that we were missing opportunities to push filters indexes on those tables.

-- Dolt v1.75.0
DESCRIBE PLAN SELECT * FROM
  (SELECT pk AS pk_alias FROM example_table) AS example_alias
WHERE pk_alias = 1;
+-----------------------------------------------------+
| plan                                                |
+-----------------------------------------------------+
| SubqueryAlias                                       |
|  ├─ name: example_alias                             |
|  └─ Filter                                          |
|      ├─ (pk_alias = 1)                              |
|      └─ Project                                     |
|          ├─ columns: [example_table.pk as pk_alias] |
|          └─ Table                                   |
|              ├─ name: example_table                 |
|              └─ columns: [pk]                       |
+-----------------------------------------------------+

Now, Dolt can move the filter into the subquery by rewriting the filter, replacing the alias name with the original expression. This allows Dolt to identify indexes when it couldn’t before:

-- Dolt v1.82.6
DESCRIBE PLAN SELECT * FROM
  (SELECT pk AS pk_alias FROM example_table) AS example_alias
WHERE pk_alias = 1;
+-------------------------------------------------+
| plan                                            |
+-------------------------------------------------+
| SubqueryAlias                                   |
|  ├─ name: example_alias                         |
|  └─ Project                                     |
|      ├─ columns: [example_table.pk as pk_alias] |
|      └─ IndexedTableAccess(example_table)       |
|          ├─ index: [example_table.pk]           |
|          ├─ filters: [{[1, 1]}]                 |
|          └─ columns: [pk]                       |
+-------------------------------------------------+

And More!#

Some of the other fixes are complicated enough to warrant their own blog posts. We’ll save those for another day.

Until then, I hope this provided some valuable insight into how SQL engines work to optimize queries, and how Dolt in specific does join planning. If you want to learn more about how a version-controlled database can help manage your data, you can always join our Discord and drop us a line.

How to Write a System Prompt

Eric Richardson — Mon, 23 Feb 2026 00:00:00 GMT

We recently launched agent mode in the Dolt Workbench. It works a lot like Cursor, but for SQL workbenches instead of IDEs.

If you’re interested in trying it out, the workbench is available for download here or on the Mac and Windows app stores.

Like all agentic applications, agent mode in the workbench relies on a carefully constructed system prompt that defines the agent’s role and capabilities. In this article, we’ll discuss the dangers of the system prompt and what it took to arrive at the one we’re using today. As we’ll see, most of the hard problems were solved not by writing better instructions but rather by shifting responsibility outside of the system prompt entirely.

The Prompt#

Here’s the system prompt we landed on for the workbench:

You are a helpful assistant for a database workbench application. You have access to tools that allow you to interact with Dolt, MySQL, and Postgres databases.

If interacting with a Dolt database, use Dolt MCP tools. For MySQL and Postgres, use ‘mysql’ and ‘psql’ CLI tools in Bash.

You are currently connected to the database: ”${database}”. ${typeInfo}

When users ask questions about their database, use the available tools to:

List tables and their schemas

Execute SQL queries to retrieve data

Explore database structure and relationships

Help users understand their data

If the user asks you to create or modify the README.md, LICENSE.md, or AGENT.md, use the ‘dolt_docs’ system table.

Always be helpful and explain what you’re doing. Do not use emojis in your responses.

When presenting query results, format them in a readable way. For large result sets, summarize the key findings.

Let’s break down each section individually:

You are a helpful assistant for a database workbench application. You have access to tools that allow you to interact with Dolt, MySQL, and Postgres databases.

If interacting with a Dolt database, use Dolt MCP tools. For MySQL and Postgres, use ‘mysql’ and ‘psql’ CLI tools in Bash.

The most important thing you have to do in a system prompt is tell the agent what it is and what tools it should use to accomplish its goals. This does not need to be long or complicated.

You are currently connected to the database: ”${database}”. ${typeInfo}

This is the only bit of dynamic context being injected into the system prompt. It tells the agent the name of the database and the type (i.e. Dolt, MySQL, or Postgres). This exists so the agent immediately knows how to interact with the database. Without it, the agent would initially flounder a bit trying to figure out what type of database it’s operating on and which tools it should use.

When users ask questions about their database, use the available tools to:

List tables and their schemas

Execute SQL queries to retrieve data

Explore database structure and relationships

Help users understand their data

This section is intentionally vague. It doesn’t attempt to prescribe a workflow. It simply orients the agent towards the types of actions users are likely to request.

If the user asks you to create or modify the README.md, LICENSE.md, or AGENT.md, use the ‘dolt_docs’ system table.

This is an example of an “agent bug fix”. You should try to keep these to a minimum. In this case, we don’t yet have MCP tools for the dolt_docs table, so the agent struggles to understand how it should work without this line. If you must include something like this in a system prompt, it should be phrased similarly (i.e. “if the user asks you to…, then do…”).

Always be helpful and explain what you’re doing. Do not use emojis in your responses.

When presenting query results, format them in a readable way. For large result sets, summarize the key findings.

The final section governs tone and presentation. These instructions are relatively safe to keep in the system prompt because they don’t attempt to enforce any sort of behavioral invariant. This helps improve the user experience. Admittedly, I’m breaking a rule I’ll discuss later on by telling the agent not to use emojis. In this case, however, there is no risk to system integrity if the model ignores that instruction. At worse, it responds with a few annoying emojis.

This is overall a fairly lean prompt. It’s also not a particularly complicated one. You may be surprised to learn that it went through well over a hundred iterations before arriving at its current state. Most of those iterations were not attempts at finding the “perfect wording” or fleshing out the most accurate “agent persona” for a SQL workbench application. Instead, they were attempts at patching flaws in the agent’s behavior. We’ll discuss at length why this is a poor strategy later on.

With long-running agentic systems, context engineering is vastly more important than prompt engineering. The goal when building these systems is to ensure that the agent’s context window contains the minimum amount of correct information necessary to accomplish any given task. The system prompt is just another piece of context. It’s a piece of context that, at least in my experience, has the potential to hurt you a lot more than help.

Offloading Context#

In my testing, I found that the more bloated the system prompt, the more likely the agent would be to outright forget things you put in there, especially for longer sessions. If at all possible, you should offload context away from the system prompt. Here’s what I mean by that.

In the early versions, agent mode did not make use of the Dolt MCP server and instead simply invoked the dolt CLI. As a result, the quality of the agent’s output depended largely on 1) its prior knowledge of Dolt and 2) its ability to use web search tools to fill in the gaps. This caused a lot of flakiness.

For instance, the agent would struggle with operating on multiple branches, often getting confused about which branch it was making changes on versus the branch that the user was connected to in the workbench. The natural solution to a problem such as this is to include explicit instructions in the system prompt about how to juggle branches. The issue then becomes that the agent starts hard overcorrecting to the instructions in the system prompt and doing things like creating a branch for every change that it makes, or refusing to make changes directly on main. Now, the issues start propagating. If the agent is making changes on multiple branches with the intention of merging all back into main, you start getting merge conflicts. There’s no clear way to solve a problem like this outside of stuffing more instructions in the system prompt. I found myself with a long checklist of items like “Don’t make changes on new branches unless the user tells you to do so” and “Don’t create new branches unnecessarily” and “There should never be merge conflicts when merging branches you’ve just created”. This basically had the opposite effect of what I intended and introduced more issues. Telling the agent NOT to do something is rarely an effective strategy.

I solved this by trimming the system prompt substantially and simply telling the agent to use the Dolt MCP server for Dolt-related operations. The MCP server comes with 40+ tools, all of which are well-documented, have defined arguments, and are queryable at any moment. These tools alone capture the overwhelming majority of Dolt’s functionality. Instead of relying on SQL queries for everything, the agent could now check its tool list for granular operations like list_dolt_diff_changes_working_set or stage_all_tables_for_dolt_commit.

Avoid adding things like this to the system prompt:

`You are currently on branch ${branchName}.`;

Instead, give the agent access to a tool like select_active_branch, which allows the agent to query for the current branch at any moment. Not only does this minimize bloat in the system prompt, it also prevents you from becoming a victim of context compaction. The agent can always make a tool call to re-query for any lost context.

Make Good Tools#

The architecture of the tools you give an agent access to plays an important role here as well. For a SQL workbench application, you could theoretically achieve the exact same functionality with just a single tool (i.e. a simple query tool that accepts arbitrary SQL). This, however, defeats the purpose. Tools are not just functional, they also act like structured bits of context.

Every tool you expose carries assumptions about how the system is meant to be used. Let’s take the create_dolt_branch tool as an example. The simple fact that this tool exists tells the agent that:

Branches are first-class concepts in Dolt
Branch creation is an intentional action
There’s a structured way to do it

Encoding system constraints in tools is a far more effective method of communicating expected behavior than encoding them in prose. Separating the behavior of your system into a robust set of tools allows for persistent “context refills” that keep your agent on course. This offloading of system context into tools resulted in a massive quality improvement in the workbench and ties into more recent developments we’ve been seeing in agentic memory. For a reference on how we split out Dolt’s functionality into tools, check out the Dolt MCP server documentation.

Don’t Say No#

I alluded to this earlier, but it’s worth discussing in greater depth because I think it’s an incredibly easy trap to fall into when writing a system prompt. This was my workflow when I was iterating on the earlier prototypes of agent mode in the workbench:

Ask the agent to do something nontrivial
Watch as the agent does something stupid
Add “Don’t do that stupid thing” to the system prompt
Go to (1)

If you don’t want an agent to perform a particular action, the most reliable solution is to make that action impossible in the first place. Of course, this is easier said than done. Since there will always be an element of nondeterminism when working with these things, there are virtually an infinite number of edge cases, and overly rigid constraints can blunt the agent’s capabilities or block legitimate workflows. The goal here isn’t to eliminate flexibility but rather to constrain the action space such that invalid states become unreachable. Here’s an example of a problem I ran into and how I solved it at the application layer rather than by adding more rules to the system prompt.

Early on, the agent would automatically decide to make Dolt commits after every write operation. This made it so the user could no longer review the agent’s changes prior to commit. I fixed this initially by adding “Don’t make commits unless the user asks you to” to the system prompt. For the most part, this worked. The agent would stop right before it would normally commit, then wait for the user to explicitly give it permission to do so. In longer sessions, it would forget and make commits anyways. It also started adding awkward things to its responses like “I won’t commit these changes because you haven’t asked me yet!” or would stop mid-response to ask for confirmation. This is clearly not ideal, but the deeper issue is that you can never make the guarantee that the agent won’t commit its changes automatically. You can reduce the probability that it happens, but you can’t eliminate it. This is a big deal for agentic applications. The more critical the system your agent is operating on (your production OLTP database, for instance), the more necessary it becomes to be able to make definitive claims about agent behavior.

I solved the problem by implementing a tool call approval workflow and putting the create_dolt_commit tool behind it.

This made it impossible for the agent to make commits without the user pressing “Confirm” first. It does not, however, block the agent from deciding to make a commit. That distinction is important. There is nothing in the agent’s system context that influences its behavior around commits. The model is still free to reason about when a commit makes sense, but it cannot unilaterally execute that decision. The final authority now lives outside the model.

Avoiding negative instructions in the system prompt is something that I predict will become a “best practice” as agentic applications become more and more common, and the most reliable way to achieve that is by separating intent from execution.

Conclusion#

In summary, prompting is difficult. If you can simplify your system prompt without hindering the agent’s access to necessary information, the quality of your agent will almost certainly improve. Offloading system context into tools and building behavioral restrictions into the application layer are the two most effective ways of doing this. If you have opinions on this, or if you just want to chat about agentic applications in general, join our Discord and give us your thoughts.

Your Time is All Messed Up: Time Implementations in Go

Angela Xie — Fri, 20 Feb 2026 00:00:00 GMT

Here at DoltHub, one of our projects is go-mysql-server, a MySQL-compatible database engine that’s written in Go and powers Dolt, the world’s first version-controlled database. In go-mysql-server, we often rely on Go standard libraries, but sometimes, we have to work around them to get the same behavior as MySQL. Previously, I blogged about updating our value of zero time to be more aligned with MySQL. In this blog, I’ll explain why we had to move away from using Go’s func (time.Time) Sub and the considerations we had to make for Go’s implementations of time in the time.Time struct when implementing our own time difference function.

The Bug#

TIMESTAMPDIFF is a function in MySQL that takes three arguments (a time unit and two datetime expressions) and calculates the difference in the specified unit between the two datetime expressions. I had noticed that Dolt and go-mysql-server’s TIMESTAMPDIFF function was not returning the correct values for times that were sufficiently far apart and that it would return the same incorrect value for a given unit argument.

Our implementation of TIMESTAMPDIFF would convert the datetime expression arguments into two time.Time structs (time1 and time2), get the difference between the two times by calling time2.Sub(time1), and convert the difference to the correct unit. The root of the bug was the call to func (time.Time) Sub.

The Problem with `func (time.Time) Sub`#

The function signature for func (time.Time) Sub looks like this:

func (t Time) Sub(u Time) Duration

The function calculates the difference between Time t and Time u as a Duration. A Duration is an int64 representing nanoseconds. As an int64, its largest value is 9,223,372,036,854,775,807 nanoseconds, or approximately 292 years. This explained why the result of TIMESTAMPDIFF seemed to be stuck at the same value for a given unit.

Because TIMESTAMPDIFF needed to work for any time arguments between 0000-01-01 00:00:00 and 9999-12-31 23:59:59.999999, we could no longer rely on func (time.Time) Sub to calculate time differences.

Calculating the Difference in Microseconds#

Thankfully, MySQL doesn’t care about nanoseconds – the smallest time unit that MySQL handles is microseconds. The largest time difference value we needed to handle was between 0000-01-01 00:00:00 and 9999-12-31 23:59:59.999999, which is 315,569,433,599,999,999 microseconds, a number small enough to fit inside an int64. So integer overflow was no longer something we needed to consider.

We calculate the difference between two times in microseconds by converting them to microseconds since Unix epoch using func (Time) UnixMicro and then taking the difference.

func microsecondsDiff(time1, time2 time.Time) int64 {
	return time2.UnixMicro() - time1.UnixMicro()
}

We’ve recently been very invested in Dolt’s performance compared to MySQL’s, and converting the times to microseconds since Unix epoch didn’t seem like the most performant solution. Why couldn’t we just calculate the times in microseconds directly, without the conversion? Why the extra step? Well, this comes down to Go’s implementation of time.Time.

A Tale of Two (and Sometimes Three) Epochs#

In order to calculate the difference between two times, they need to be normalized to the same epoch. An epoch is a fixed time reference point, and times in computing are typically stored as numbers representing some unit of time elapsed since an epoch. If two times do not have the same epoch, you’re not going to get the correct difference simply by subtracting them. It’s just math (the proof is left as an exercise to the reader).

In the time.Time struct, Go uses two different epochs depending on whether a time is monotonic or not: January 1, 1885 for monotonic time and January 1, 0001 for other time. January 1, 1885 seems to be a reference to Back to the Future II.

Two epochs! What a mess!

Because of these two different epochs, Go doesn’t have exported public functions that expose time values directly.

When calculating time differences using func (Time) Sub, Go uses func (Time) sec to normalize times to seconds since the January 1, 0001 epoch. func (Time) sec, combined with func (Time) Nanosecond to calculate microseconds, is what we want to use to be the most performant, but it’s an unexported private function that can’t be used outside of the time package. It seems like Go wants to keep their underlying epochs secret. Instead, we have to rely on the limited exported public functions, and func (Time) UnixMicro is our best option, despite its runtime – it first converts times using func (Time) sec before converting them again to time since the Unix epoch.

Conclusion#

In the end, we were able to fix our TIMESTAMPDIFF implementation to return the correct values, even if Go had to do some extra time conversions under the hood. If you’re interested in learning more about the time package, you can read the documentation or dig into the source code.

Found a bug in Dolt or go-mysql-server? File an issue, or join our Discord server!

Cursor for SQL

Eric Richardson — Mon, 09 Feb 2026 00:00:00 GMT

At DoltHub, we’ve been writing extensively about why version-controlled data is a prerequisite for truly agentic applications. We believe tools like Cursor won’t stay confined to code for long. Recently, we wrote a blog exploring what this might look like for a SQL workbench application. Specifically, we ran a Claude Code instance alongside the Dolt Workbench, used it to read from and write to a database, then leveraged Dolt’s built-in version control features to create an experience analogous to writing code with Cursor.

Today, we’re excited to officially introduce our entry into the SQL workbench space: agent mode in the Dolt Workbench, a Cursor-like agentic chat interface that allows you to safely interact with Dolt, MySQL, and Postgres databases. In this article, we’ll show off the new feature with a simple example using MySQL and Dolt databases.

Agent Mode - MySQL#

For this demo, we’ll use the popular stocks database on DoltHub. I’ll start by cloning the database, creating a SQL dump to convert it to MySQL, then starting up a MySQL server on my local machine:

dolt clone post-no-preference/stocks
dolt dump
mysql -h 127.0.0.1 -P 3300 -u root < doltdump.sql

Now, I’ll connect to the database from the workbench:

In the top right corner, you’ll notice an orange robot icon. This button pulls up the agent chat panel. If it’s your first time using agent mode, you’ll be prompted to put in your Anthropic API key:

After doing this, the main chat window will open on the right. The chat interface is accessible from anywhere in the workbench:

Let’s start with something simple. I’ll ask the agent to tell me about the database I’m connected to.

After deciding that it needs to gather information about the database, you’ll notice several “Bash” blocks in the agent’s response. These blocks represent tool calls. Each of these are expandable, allowing you to see exactly what actions were taken by the agent. For example:

In this case, the agent is using the mysql CLI inside a Bash shell to query the database. After making several queries, the agent presents a summary of its findings:

This is already pretty useful, but it’s not really agent mode if it can’t make writes. Let’s ask it to do something more interesting.

The agent begins confidently inserting data into the database. Again, to see the actual queries it runs, you can expand the tool call blocks. Once finished, it gives a summary of its actions:

Great, the agent did what I asked. However, there’s a somewhat large caveat here: there’s no mechanism in place to see or verify the agent’s changes. I asked it to make some changes, it executed a bunch of insert statements, then told me everything went swimmingly. The state of the workbench is unchanged.

If I want to examine the changes, the best I can do is run some SQL queries that explicitly query for the new data. Something like this, for instance:

This is not just a lackluster user experience for an application that uses AI to make writes to your database, it’s also dangerous. There was no way for me to verify the changes made by the agent before they happened. We can always hope that the agent won’t go off the rails and nuke your entire database or insert a bunch of faulty data, but that’s the best we can do: hope. This is the reason applications like this don’t exist yet. Version control solves this problem. To show what I mean, let’s run this same experiment using a Dolt database instead of MySQL.

Agent Mode - Dolt#

We’ll give the agent the exact same instructions as previously. Let’s start simple:

You’ll notice that the tool call blocks are a fair bit more informative here. This is thanks to the Dolt MCP Server, which the agent uses for all Dolt-related operations.

As we’ll see later, this separation of tool calls enables some important features related to permissions and approvals. After making several queries, the agent presents another helpful summary of the data and schema. Now, let’s have it insert some data:

As the agent makes changes, you’ll immediately notice visual changes in the workbench. The table names in the left panel are highlighted in yellow to indicate that their data has been modified. Additionally, above the main table view, you’ll see the option to “Show Changed Rows Only” as well as a button for “Uncommitted changes”:

Let’s check the box to show changed rows only.

This filters the table by rows in your working set. For a more complete breakdown of all changes made, you can click the “Uncommitted changes” button.

Let’s look at the agent’s response:

Since we can now preview changes before they’re actually committed, the agent will hold off on making a Dolt commit until the user grants explicit confirmation. This makes it impossible for the agent to break your database. Let’s hit confirm and check the commit log to make sure everything succeeded.

Perfect, we were able to use the agent to make a write to the database, view the diff, then allow the agent to commit its changes. Even if we accidentally committed some unwanted changes, Dolt allows you to immediately reset to any prior commit. Just for fun, let’s have the agent do this:

After confirming, my database is back to its original state.

Conclusion#

We’re super excited about applications that use agentic AI the way we’re using it here, and we think version control is necessary to make that happen. We encourage you to try out agent mode in the Dolt Workbench, which you can download directly here or from the Mac and Windows app stores. If you have any ideas for improvements, feature requests, or bug reports, come by our Discord and let us know.

Connect Agents to your Hosted Dolt Instance using MCP

Brian Hendriks — Tue, 03 Feb 2026 00:00:00 GMT

It has been our thesis that Dolt is the ideal database for agentic workloads. Agents need a database that is version controlled. The ability to branch, and diff allow agentic workflows to work in isolation, and be audited before merging changes back to mainline. Dolt’s git-like collaboration model also allows multiple agents to work concurrently on the same database without stepping on each other’s toes. In August of 2025 we launched Dolt MCP, which is a server that implements Anthropic’s MCP protocol to allow agents to connect to Dolt databases. Today we are excited to announce that you can now enable Dolt MCP on your Hosted Dolt instances to connect them to your agentic workloads.

Enabling Dolt MCP on Hosted Dolt#

Enabling Dolt MCP on your Hosted Dolt instance is easy.
On the settings tab for your Hosted Dolt deployment, you will find a new section called “Enable Dolt MCP server” In this section, you can enable Dolt MCP for your instance, by clicking the “Expose MCP Server” check box. Once enabled Dolt MCP will be installed on your instance and started in a matter of minutes.

After enabling Dolt MCP, the section will update to show the details necessary to connect your MCP compatible agent to your Hosted Dolt instance.

Connecting to Hosted Dolt MCP#

Dolt MCP server runs on port 8675, and uses steaming HTTP as the transport mechanism. The server requires clients to authenticate using a token. The token is generally passed as a bearer token by client’s that support that authentication mechanism. Dolt MCP also supports passing the token as a query parameter (jwt), for clients that do not support bearer token authentication.

dolt-mcp Database User#

Dolt MCP server connects to your Hosted Dolt database using a special database user named mcp_user. By default this user does not have any privileges on your database. You will need to grant the necessary privileges to this user in order for Dolt MCP to function correctly. The privileges you grant will depend on the operations you want your agent to be able to perform. At a minimum, you will want to grant the mcp_user read privileges on one or more database tables. Here is an example of granting read privileges on a table called tasks within the database my_database:

GRANT SELECT ON my_database.tasks TO 'mcp_user'@'%';

Configuring your MCP Compatible Agent#

The steps necessary to configure your MCP compatible agent are dependent on the agent you are using. Please refer to the documentation for your agent to learn how to configure it to connect to an MCP server running over https.

An example using Claude#

After creating a Hosted Dolt deployment, I enabled the Dolt MCP server by clicking the checkbox on the settings tab. Next, I go back to the main page of the deployment and copy the mysql command line to connect to my database server and run:

>mysql -h"mcp-test.dbs.hosted.doltdb.com" -u"lop887ig4wkov575" -p"LxuVijXyXiC2ZEi5qvvRiBXSi32MbWIi"
mysql: [Warning] Using a password on the command line interface can be insecure.
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 2
Server version: 8.0.33 Dolt

Copyright (c) 2000, 2025, Oracle and/or its affiliates.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> GRANT SHOW DATABASES ON *.* TO 'mcp_user'@'%';
Query OK, 0 rows affected (0.032 sec)

mysql> CREATE DATABASE test;
Query OK, 1 row affected (0.107 sec)

Now that we have enabled the Dolt MCP server and granted the necessary privileges to the mcp_user to show databases we will configure Claude to be able to use our MCP server. The claude command line allows us to add a new MCP server like so:

>claude mcp add --transport http dolt-mcp https://mcp-test.dbs.hosted.doltdb.com:8675/mcp \
 --header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjRjZTI1Y2FjLTFkNjEtNGI3My1hMTAwLTRjMDU3MTJhZTIxYSIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiZGVwbG95bWVudE93bmVycy9kb2x0aHViL2RlcGxveW1lbnRzL21jcC10ZXN0Il0sImV4cCI6MTgwMTY4NzcwMCwiaWF0IjoxNzcwMTUxNzAwLCJpc3MiOiJob3N0ZWQuZG9sdGRiLmNvbSIsImp0aSI6ImExMmE5NWQ1LTYxMTctNGNhMy04MmYzLWViN2E4YTUyYmYzOCIsIm9uX2JlaGFsZl9vZiI6ImJoZW5pIiwic3ViIjoiZG9sdC1tY3AifQ.ULqrWUSunAvk-tsgmr1gP4fJG2Hxj9v9ygiZ7lgXAkZ_HxxXxdAkklsYhW6ie4Y2H9nvZs3Ux1tBWajsZHHeeIzUqReNdNve--Ghm3vCNJqn0m67WFdqbeBhDaUuohCkJvBYi7pXspS087VF8s1eKBQnBBJCo-fe1TGycC_00_pilTWww2o9HJjkLLXl73AOR2zTCm3_80Qq_TasrtHtH7c60zLYBQ4Pr1VZSjb8bdjb_euacwgPR_yJlUhZ6lU7kySg1c2Odk-LO1yqiUmGUKTFMxU1gM2zzDyhk-viuF3a8JMxXt5FDVfAzqTqg5Am6tHs8OugVhinWXWpB_nkwA"
 
Added HTTP MCP server dolt-mcp with URL: https://mcp-test.dbs.hosted.doltdb.com:8675/mcp to local config
Headers: {
  "Authorization": "Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjRjZTI1Y2FjLTFkNjEtNGI3My1hMTAwLTRjMDU3MTJhZTIxYSIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiZGVwbG95bWVudE93bmVycy9kb2x0aHViL2RlcGxveW1lbnRzL21jcC10ZXN0Il0sImV4cCI6MTgwMTY4NzcwMCwiaWF0IjoxNzcwMTUxNzAwLCJpc3MiOiJob3N0ZWQuZG9sdGRiLmNvbSIsImp0aSI6ImExMmE5NWQ1LTYxMTctNGNhMy04MmYzLWViN2E4YTUyYmYzOCIsIm9uX2JlaGFsZl9vZiI6ImJoZW5pIiwic3ViIjoiZG9sdC1tY3AifQ.ULqrWUSunAvk-tsgmr1gP4fJG2Hxj9v9ygiZ7lgXAkZ_HxxXxdAkklsYhW6ie4Y2H9nvZs3Ux1tBWajsZHHeeIzUqReNdNve--Ghm3vCNJqn0m67WFdqbeBhDaUuohCkJvBYi7pXspS087VF8s1eKBQnBBJCo-fe1TGycC_00_pilTWww2o9HJjkLLXl73AOR2zTCm3_80Qq_TasrtHtH7c60zLYBQ4Pr1VZSjb8bdjb_euacwgPR_yJlUhZ6lU7kySg1c2Odk-LO1yqiUmGUKTFMxU1gM2zzDyhk-viuF3a8JMxXt5FDVfAzqTqg5Am6tHs8OugVhinWXWpB_nkwA"
}
File modified: /Users/brian/.claude.json [project: /Users/brian/dev/claude-test]

We can verify its configuration using claude mcp get:

>claude mcp get dolt-mcp
dolt-mcp:
  Scope: Local config (private to you in this project)
  Status: ✓ Connected
  Type: http
  URL: https://mcp-test.dbs.hosted.doltdb.com:8675/mcp
  Headers:
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjRjZTI1Y2FjLTFkNjEtNGI3My1hMTAwLTRjMDU3MTJhZTIxYSIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiZGVwbG95bWVudE93bmVycy9kb2x0aHViL2RlcGxveW1lbnRzL21jcC10ZXN0Il0sImV4cCI6MTgwMTY4NzcwMCwiaWF0IjoxNzcwMTUxNzAwLCJpc3MiOiJob3N0ZWQuZG9sdGRiLmNvbSIsImp0aSI6ImExMmE5NWQ1LTYxMTctNGNhMy04MmYzLWViN2E4YTUyYmYzOCIsIm9uX2JlaGFsZl9vZiI6ImJoZW5pIiwic3ViIjoiZG9sdC1tY3AifQ.ULqrWUSunAvk-tsgmr1gP4fJG2Hxj9v9ygiZ7lgXAkZ_HxxXxdAkklsYhW6ie4Y2H9nvZs3Ux1tBWajsZHHeeIzUqReNdNve--Ghm3vCNJqn0m67WFdqbeBhDaUuohCkJvBYi7pXspS087VF8s1eKBQnBBJCo-fe1TGycC_00_pilTWww2o9HJjkLLXl73AOR2zTCm3_80Qq_TasrtHtH7c60zLYBQ4Pr1VZSjb8bdjb_euacwgPR_yJlUhZ6lU7kySg1c2Odk-LO1yqiUmGUKTFMxU1gM2zzDyhk-viuF3a8JMxXt5FDVfAzqTqg5Am6tHs8OugVhinWXWpB_nkwA

Now that we have configured Claude to connect to our Hosted Dolt deployment’s MCP server, we can start using it to interact with our database.

>claude

╭─── Claude Code v2.1.30 ──────────────────────────────────────────────────────╮
│                                                  │ Tips for getting started  │
│                   Welcome back!                  │ Ask Claude to create a n… │
│                                                  │ ───────────────────────── │
│                                                  │ Recent activity           │
│                      ▐▛███▜▌                     │ No recent activity        │
│                     ▝▜█████▛▘                    │                           │
│                       ▘▘ ▝▝                      │                           │
│   Sonnet 4.5 · API Usage Billing · DoltHub Inc   │                           │
│                ~/dev/claude-test                 │                           │
╰──────────────────────────────────────────────────────────────────────────────╯

❯ can you list databases?

⏺ I'll list the databases available in the Dolt server.

────────────────────────────────────────────────────────────────────────────────
 Tool use

   dolt-mcp - list_databases() (MCP)
   Lists all databases in the Dolt server.

 Do you want to proceed?
 ❯ 1. Yes
   2. Yes, and don't ask again for dolt-mcp - list_databases commands in /Users/brian/dev/claude-test
   3. No

⏺ I'll list the databases available in the Dolt server.
  ⎿  Database
     ---
     test
     information_schema
     mysql

⏺ The Dolt server has the following databases:

  - test - A user-created database
  - information_schema - System database containing metadata about the database server
  - mysql - System database for MySQL compatibility

  These are system databases. There are currently no user-created databases in
  the Dolt server. Would you like to create a new database?

This small example demonstrates just a single interaction with the Dolt MCP server with just one of many agentic platforms that support MCP. The Dolt MCP server provides the full range of Dolt functionality (Just make sure your mcp_user has the necessary privileges).

Conclusion#

We are excited to bring Dolt MCP to Hosted Dolt users. We believe that Dolt is the ideal database for agentic workloads, and we are committed to making it easy for developers to use Dolt in their agentic applications. We look forward to seeing the innovative applications that developers will build using Hosted Dolt and Dolt MCP. We’d love to hear your feedback. Please reach out to us on our Discord.

DoltHub Blog - Latest Posts

How Dolt Represents and Evaluates Queries: A Case Study

Scopes#

Scopes at Analysis Time#

Scopes at Runtime#

Vibe-Coded Agents for Vibe-Coded Issues

The Problem: Pre-Baked Containers Don’t Scale#

How grunt Works#

Per-Repo Config#

Adding a New Agent Type#

Conclusion#

Branch Permissions in the Hosted Dolt Workbench

Background and implementation details#

How it works#

Conclusion#

Saying goodbye to the LD1 storage format

The challenge#

Why bother?#

Making the changes#

Conclusion#

Improving Index Selection For Join Queries

The Slow Query#

Let’s Focus on Indexes#

Slaying the Hydra#

PR 3380: Generate index lookups for filters that appear in lateral joins#

PR 3386: Push filters that contain references to outer scopes.#

PR 3379: Allow introspection into Views#

PR 3383: When applying indexes from outer scopes, resolve references to table aliases#

PR 3400: Push Filters inside Projections#

And More!#

How to Write a System Prompt

The Prompt#

Offloading Context#

Make Good Tools#

Don’t Say No#

Conclusion#

Your Time is All Messed Up: Time Implementations in Go

The Bug#

The Problem with func (time.Time) Sub#

Calculating the Difference in Microseconds#

A Tale of Two (and Sometimes Three) Epochs#

Conclusion#

Cursor for SQL

Agent Mode - MySQL#

Agent Mode - Dolt#

Conclusion#

Connect Agents to your Hosted Dolt Instance using MCP

Enabling Dolt MCP on Hosted Dolt#

Connecting to Hosted Dolt MCP#

dolt-mcp Database User#

Configuring your MCP Compatible Agent#

An example using Claude#

Conclusion#

PR 3380: Generate index lookups for filters that appear in lateral joins #

PR 3379: Allow introspection into Views #

PR 3383: When applying indexes from outer scopes, resolve references to table aliases #

PR 3400: Push Filters inside Projections #

The Problem with `func (time.Time) Sub`#