DoltHub Blog - Latest Posts

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.

Writing a Go SQL driver

Zach Musgrave — Fri, 23 Jan 2026 00:00:00 GMT

We’re building Dolt, the world’s first version-controlled SQL database. Most of our customers run Dolt as a server in Docker and connect to it over the network like any other database server. But for programs written in Go, you can also connect to a Dolt database without a separate server process, similar to SQLite. We call this the embedded use case, and it has suddenly become a lot more relevant with Gas Town migrating its agentic memory storage to use Dolt as its backend. Since Gas Town is a Go process, it can use the embedded Dolt driver to communicate with an embedded Dolt database.

So, because Dolt’s embedded driver is about to get a lot more action than it’s used to, we thought this would be a good time to give a tour of how it works. This pattern is possible through the magic of Go’s database/sql/driver package, which lets you define a database connection that any Go program can use to talk to your SQL backend with a single import statement.

In this tour, we’ll look at how Go’s SQL drivers work under the hood and show you how Dolt implements one to provide access to an embedded Dolt database. Let’s take a look.

What’s the driver package?#

Go’s SQL driver package is an abstraction that lets other software libraries vend their own SQL connection logic through a common set of interfaces. Application developers use a common interface to connect to any SQL database (MySQL, Postgres, MariaDB, SQL Server, Dolt, etc.) without worrying about the specifics of the wire protocol for that particular database.

This is best illustrated with an example. Here’s how you connect to MySQL and read some rows.

package main

import (
	"database/sql"
	"fmt"
	"log"

	_ "github.com/go-sql-driver/mysql"
)

func main() {
	dsn := "user:password@tcp(127.0.0.1:3306)/testdb"

	db, err := sql.Open("mysql", dsn)
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	rows, err := db.Query("SELECT id, name FROM users")
	if err != nil {
		log.Fatal(err)
	}
	defer rows.Close()

	for rows.Next() {
		var id int
		var name string
		if err := rows.Scan(&id, &name); err != nil {
			log.Fatal(err)
		}
		fmt.Println(id, name)
	}
}

Let’s go over this example line by line and see what it does.

import (
	_ "github.com/go-sql-driver/mysql"
)

This line is kind of magic and weird: the _ tells Go that you’re not using any symbols from this package, you’re importing it just for its side-effects. In this case, those side effects are registering a driver called "mysql" with database/sql package.

	dsn := "user:password@tcp(127.0.0.1:3306)/testdb"

	db, err := sql.Open("mysql", dsn)

A DSN is a data source name, almost always resembling a URL but often with some extra bits. Each database vendor has their own format for these DSNs, but they all look pretty similar. You usually embed the user name and password and some other metadata, like which database you want to connect to, in this string.

To open a connection, you just call sql.Open with the name of the driver and its matching DSN. Easy!

	rows, err := db.Query("SELECT id, name FROM users")

Query() on a connection takes a query string and returns the resulting rows.

	for rows.Next() {
		var id int
		var name string
		if err := rows.Scan(&id, &name); err != nil {
			log.Fatal(err)
		}
		fmt.Println(id, name)
	}

rows.Scan() puts the result of the query into normal Go datatypes, like int or string.

There are more complicated access patterns, and we haven’t touched on things like INSERT statements, but those are the basics.

Let’s see how a Driver is implemented by examining the Dolt driver.

The Dolt driver#

Dolt’s embedded database driver is defined very simply.

var _ driver.Driver = (*doltDriver)(nil)

func init() {
	sql.Register(DoltDriverName, &doltDriver{})
}

// doltDriver is a driver.Driver implementation which provides access to a
// dolt database on the local filesystem
type doltDriver struct {}

The init() function is the special magic that requires you to use the _ import on the database driver of your choice. At program execution time, this code calls sql.Register() to tell the database/sql package there’s a driver.Driver implementation named “dolt”.

Next we need a way to get a connection to the embedded database, which we do with the Open() method. In the sample below, I’ve removed most of the error handling for brevity. You can read the full source here.

func (d *doltDriver) Open(dataSource string) (driver.Conn, error) {
	ctx := context.Background()
	var fs filesys.Filesys = filesys.LocalFS

	ds, err := ParseDataSource(dataSource)

    exists, isDir := fs.Exists(ds.Directory)
	fs, err = fs.WithWorkingDir(ds.Directory)

    name := ds.Params[CommitNameParam]
	email := ds.Params[CommitEmailParam]

	cfg := config.NewMapConfig(map[string]string{
		config.UserNameKey:  name[0],
		config.UserEmailKey: email[0],
	})

	mrEnv, err := LoadMultiEnvFromDir(ctx, cfg, fs, ds.Directory, "0.40.17")

    seCfg := &engine.SqlEngineConfig{
		IsReadOnly: false,
		ServerUser: "root",
		Autocommit: true,
	}

	se, err := engine.NewSqlEngine(ctx, mrEnv, seCfg)
	gmsCtx, err := se.NewLocalContext(ctx)
	if database, ok := ds.Params[DatabaseParam]; ok && len(database) == 1 {
		gmsCtx.SetCurrentDatabase(database[0])
	}

	return &DoltConn{
		DataSource: ds,
		se:         se,
		gmsCtx:     gmsCtx,
	}, nil
}

Dolt’s DSN format is basically a file URL with some extra query params. It looks something like this:

file:///User/brian/driver/example/path?commitname=Billy%20Bob&commitemail=bb@gmail.com&database=dbname

We parse this URL and extract the relevant query params out of it, then use those to create our internal SQL engine representation, which is what Dolt uses to execute queries internally.

This gives us a DoltConn with an engine it can use to execute queries. Let’s look at that next.

Dolt’s `driver.Connection`#

Unlike the driver itself, the DoltConn type has some state. But it’s still very simple. Its main job is to pass information down the line, from a call to Prepare to a driver.Stmt type.

type DoltConn struct {
	se         *engine.SqlEngine
	gmsCtx     *gms.Context
	DataSource *DoltDataSource
}

var _ driver.Conn = (*DoltConn)(nil)

// Prepare packages up |query| as a *doltStmt so it can be executed. If multistatements mode
// has been enabled, then a *doltMultiStmt will be returned, capable of executing multiple statements.
func (d *DoltConn) Prepare(query string) (driver.Stmt, error) {
	// Reuse the same ctx instance, but update the QueryTime to the current time.
	// Statements are executed serially on a connection, so it's safe to reuse
	// the same ctx instance and update the time.
	d.gmsCtx.SetQueryTime(time.Now())

	if d.DataSource.ParamIsTrue(MultiStatementsParam) {
		return d.prepareMultiStatement(query)
	} else {
		return d.prepareSingleStatement(query)
	}
}

// prepareSingleStatement creates a doltStmt from |query|.
func (d *DoltConn) prepareSingleStatement(query string) (*doltStmt, error) {
	return &doltStmt{
		query:  query,
		se:     d.se,
		gmsCtx: d.gmsCtx,
	}, nil
}

The driver.Stmt implementation is where real work begins to happen, in the Query() method.

// Query executes a query that may return rows, such as a SELECT
func (stmt *doltStmt) Query(args []driver.Value) (driver.Rows, error) {
	var sch gms.Schema
	var rowIter gms.RowIter
	var err error

	if len(args) != 0 {
		sch, rowIter, err = stmt.execWithArgs(args)
	} else {
		sch, rowIter, _, err = stmt.se.Query(stmt.gmsCtx, stmt.query)
	}
	if err != nil {
		return nil, translateError(err)
	}

	// Wrap the result iterator in a peekableRowIter and call Peek() to read the first row from the result iterator.
	// This is necessary for insert operations, since the insert happens inside the result iterator logic.
	peekIter := peekableRowIter{iter: rowIter}
	row, _ := peekIter.Peek(stmt.gmsCtx)

	return &doltRows{
		sch:              sch,
		rowIter:          &peekIter,
		gmsCtx:           stmt.gmsCtx,
		isQueryResultSet: isQueryResultSet(row),
	}, nil
}

func (stmt *doltStmt) execWithArgs(args []driver.Value) (gms.Schema, gms.RowIter, error) {
	bindings, err := argsToBindings(args)
	if err != nil {
		return nil, nil, err
	}

	sch, itr, _, err := stmt.se.GetUnderlyingEngine().QueryWithBindings(stmt.gmsCtx, stmt.query, nil, bindings, nil)
	if err != nil {
		return nil, nil, err
	}
	return sch, itr, nil
}

Here you can see that the statement’s real work is nearly all delegated to the SQL engine we created in the initial call to Open(). The rest of its functionality is just to translate between the results that Dolt’s SQL engine provides and what the database/sql interfaces expect. For that, we have the doltRows type.

type doltRows struct {
	sch     gms.Schema
	rowIter gms.RowIter
	gmsCtx  *gms.Context
	columns []string
}

var _ driver.Rows = (*doltRows)(nil)

// Columns returns the names of the columns. The number of columns of the result is inferred from the length of the
// slice. If a particular column name isn't known, an empty string should be returned for that entry.
func (rows *doltRows) Columns() []string {
	if rows.columns == nil {
		rows.columns = make([]string, len(rows.sch))
		for i, col := range rows.sch {
			rows.columns[i] = col.Name
		}
	}

	return rows.columns
}

// Next is called to populate the next row of data into the provided slice.
// The provided slice will be the same size as the Columns() are wide.
// Next returns io.EOF when there are no more rows.
func (rows *doltRows) Next(dest []driver.Value) error {
	nextRow, err := rows.rowIter.Next(rows.gmsCtx)
	if err != nil {
		if err == io.EOF {
			return io.EOF
		}
		return translateError(err)
	}

	if len(dest) != len(nextRow) {
		return errors.New("mismatch between expected column count and actual column count")
	}


	for i := range nextRow {
        // Some types like enums need special handling here, but mostly the types returned
        // by the Dolt SQL engine are already the Go types that the database/sql interfaces require
        if (...) {
            // special type handling code
		} else {
			dest[i] = nextRow[i]
		}
	}

	return nil
}

And that’s it! The job of these interfaces is really to act as a translation layer between the wire protocol the database uses and the types that database/sql expects. In the case of the Dolt embedded driver, there’s no wire protocol: we’re accessing the SQL engine that queries the database on disk directly and using the data structures it returns natively.

Using a driver with Gorm#

A lot of developers prefer to use an ORM tool when interacting with their database, and in the Go world, the most popular ORM library is Gorm. Gorm usually manages your DB connection for you automatically, but in the case of Dolt embedded we want something slightly different: we want it to use its MySQL dialect and logic but connect to an embedded Dolt database connection. This is pretty easy to do.

package main

import (
	"fmt"
	"log"

	"gorm.io/gorm"

    _ "github.com/go-sql-driver/mysql"
    _ "github.com/dolthub/driver/embedded"
)

type User struct {
	ID   uint
	Name string
}

func main() {
	dbName := "server_db"
	dsn := fmt.Sprintf("file://%v?commitname=%v&commitemail=%v&database=%v", dir, "Gorm Tester", "gorm@dolthub.com", dbName)
	sqlDB, err := sql.Open("dolt", dsn)

    db, err := gorm.Open(mysql.New(mysql.Config{Conn: sqlDB}), &gorm.Config{SkipDefaultTransaction: true, PrepareStmt: true})
	if err != nil {
		log.Fatal(err)
	}

	var users []User
	if err := db.Find(&users).Error; err != nil {
		log.Fatal(err)
	}

	for _, u := range users {
		fmt.Println(u.ID, u.Name)
	}
}

Note that we need to import both the MySQL driver and the Dolt driver for this to work. But otherwise, it’s a standard Gorm setup.

Conclusion#

Go’s database drivers are a simple way for database application developers to connect to any of the many different SQL databases you can run in production with a common interface. Standardizing these interfaces made it easier for libraries like Gorm to offer support for a larger variety of different database vendors, since the details of the wire protocols and other tricky bits are hidden by the abstraction for most uses. And it’s pretty simple to write your own driver if you have a SQL data source you want other people to connect to.

Want to discuss Go database drivers or learn more about Dolt? Visit us on the DoltHub Discord, where our engineering team hangs out all day. Hope to see you there.

Using Dolt with ORMs

Jason Fulghum — Tue, 20 Jan 2026 00:00:00 GMT

Object-Relational Mappers (ORMs) are a cornerstone of modern application development. They provide a domain-friendly interface for working with relational databases, letting developers define models in their chosen programming language and then automatically translating those into SQL queries. By abstracting away SQL boilerplate, ORMs can increase productivity, reduce errors, and let developers focus on their higher-level application code instead of spending time writing SQL queries.

Dolt is a MySQL-compatible relational database that combines the features of MySQL with the features of Git, to give you the world’s first version-controlled, relational database. Dolt lets you branch, merge, diff, and work with your SQL tables in all the same ways that Git lets you work with files.

In this post, we’re taking a look at how to use Dolt with ORMs and highlighting some specific Dolt features that can be helpful, along with a couple of gotchas to know about.

ORM Benefits#

ORMs are popular because they take over the responsibility for database interactions in an application by creating SQL queries and unmarshalling results from the database into model objects. Beyond that, there’s a lot of variance in what ORMs provide. Some ORMs are super lightweight without providing extra functionality, while others come bundled in a full-featured framework that provides all sorts of other features such as pagination support, advanced connection pooling, and lazy/eager data loading.

Generally, you can expect most ORMs to provide:

Model-First Development: Define your entities in code. Use classes, structs, or structs with annotations, and let the ORM handle mapping to tables and columns. This removes a lot of marshalling/unmarshalling boilerplate code from your application.
Migrations & Schema Evolution: Evolve your schema safely over time, alongside your application code, using ORM migration tooling. ORMs can generate migration scripts and apply those migration scripts when deploying new versions.
Query Building: Build database queries using fluent, type-safe query construction instead of authoring raw SQL strings.

It’s worth noting that not every database application needs to use an ORM. ORMs provide a lot of helpful functionality, but there are valid reasons why a developer may prefer to keep tight control over the SQL queries and query results processing, instead of using an ORM.

Dolt Compatibility with ORMs#

Dolt is MySQL-compatible, although it doesn’t contain any MySQL code in its implementation. We wrote Dolt from the ground up so that we could use a unique data storage engine which enables extremely efficient diff computation. Because Dolt is MySQL-compatible, you can use any tool, framework, or ORM that works with MySQL to interact with Dolt. As part of our MySQL-compatibility testing, we’ve tested over a dozen ORMs in various languages to make sure they work well with Dolt. (If you’re looking for a version-controlled Postgres database, check out Doltgres, another database we’ve been building.)

At the time of writing this post, here are the ORMs we’ve tested. Each one has a link to a blog article with a walkthrough of using that ORM with Dolt, as well as sample code in a linked repository:

ASP.NET Entity Framework Core (blog) (sample code)
Diesel (blog) (sample code)
Django (blog) (sample code)
Ecto (blog) (sample code)
GORM (blog) (sample code)
Hibernate (blog) (sample code)
Knex.js (blog) (sample code)
Laravel (blog) (sample code)
Ruby on Rails (blog) (sample code)
Prisma (blog) (sample code)
SQLAlchemy (blog) (sample code)

Tricks and Tips for Using Dolt with an ORM#

ORMs are designed around certain assumptions: a single, stable schema for your tables, traditional schema migrations, and predictable introspection capabilities. Dolt expands what’s possible with data, and challenges some of those assumptions. The following sections share tips and tricks for using Dolt effectively with ORMs.

Using ORMs with Historical Schemas#

One of the primary benefits of Dolt is that you can go back in time and view your data at any point where you’ve made a Dolt commit. This is a powerful feature, but can present a challenge for ORMs that expect data to match the schema of your current model definitions. If you go back in time, specifically across schema changes, then your tables’ schemas won’t match what the ORM is expecting from your model.

Fortunately, Dolt provides a solution for this. Schema overriding allows you to pin your schema to a specific commit, then when you query historical data, it is automatically mapped to that target schema. This feature was designed explicitly to enable ORMs to more easily access historical data when the data’s schema has changed over time. By setting the session variable @@dolt_override_schema, all queries in that session will behave as if the database schema were the one specified, even if the underlying data comes from a commit with a different schema.

Using this feature is easy. Let’s take it for a spin…

First, create a new directory, initialize it as a Dolt database, and then launch a SQL shell:

mkdir dolt-schema-override-demo && cd dolt-schema-override-demo
dolt init
dolt sql

Next, let’s create some sample data and then extend the schema in the most recent commit:

-- Create the "old" schema (no Birthdate) and seed data
CREATE TABLE people (
    Id   INT NOT NULL PRIMARY KEY,
    Name TEXT NOT NULL
);

INSERT INTO people (Id, Name) VALUES
    (1, 'Frank'),
    (2, 'Columbia'),
    (3, 'Dr. Scott');

-- Stage all tables (-A) and commit 
CALL DOLT_COMMIT('-Am', 'Create people table (Id, Name) and seed data');

-- Tag this version so we can reference this point in our history later
CALL DOLT_TAG('v1.0');

-- Evolve the schema: add a new column and commit it
ALTER TABLE people ADD COLUMN Birthdate DATE NULL;
INSERT INTO people (Id, Name, Birthdate) VALUES (4, 'Magenta', '1981-02-16 06:00:00');
CALL DOLT_COMMIT('-Am', 'Add Birthdate column to people');

Now that we’ve set up our database, we’re ready to use the schema override feature. First let’s take a look at the problem. Dolt lets you query historical data in many ways. You could use a branch that has an older schema version, or you could check out a tag that points to an older commit, or you could use the AS OF syntax to reference an older commit. Those give us easy ways to look back in history and see how our data existed at previous points, but remember that our ORM is still using a static model to deserialize results and it’s expecting the schema to match that static model exactly. In the query below, the ORM’s static model knows about the Name and Birthdate fields, but the Birthdate field doesn’t exist at v1.0.

-- this column doesn't exist on olderData's schema
SELECT Name, Birthdate FROM people AS OF 'v1.0';

The query above fails, because the commit we’re referencing doesn’t contain the Birthdate field:

column "Birthdate" could not be found in any table in scope

To fix this, we just need to set the @@dolt_override_schema session variable with a commit reference that contains the schema we want to map to. In our case, we’re going to use the latest schema from main, since that’s what matches the static model our ORM is using.

-- Override schema to use the schema at the tip of the main branch. 
-- The hashof() function resolves the tag to a commit hash. 
SET @@dolt_override_schema = 'main';

-- Now the same query succeeds (Birthdate will be NULL for these historical rows)
-- Dolt maps old data to the newer schema and fills in missing columns with NULL.
SELECT Name, Birthdate FROM people AS OF 'v1.0';

With the @@dolt_override_schema session variable set, we can now execute that query without an error, because the data is mapped to the schema at the tip of main and fills in NULL values for the new Birthdate field. Notice in this example that the data we’re using here comes from v1.0 (because of the AS OF 'v1.0' clause we used), but the schema comes from the tip of main (because @@dolt_override_schema is set to main).

+-----------+-----------+
| Name      | Birthdate |
+-----------+-----------+
| Frank     | NULL      |
| Columbia  | NULL      |
| Dr. Scott | NULL      |
+-----------+-----------+
3 rows in set (0.00 sec)

Schema overriding has some limits, but it’s a handy feature to map older data into a different schema.

Using ORMs with Non-Versioned Data#

Dolt allows you to create isolated branches where you can stage changes or run experiments. These branches are isolated and don’t interfere with other branches. But what happens when you have data that needs to be accessible across all branches and shouldn’t be versioned? One example of a good candidate is a table that tracks all visits to a site. If this data was versioned, then you could run into spurious merge conflicts when merging between branches that have both updated the table. For rapidly growing data like this, it could also generate noise in diffs and history logs that could make other data changes harder to see. If your app has data like this, where there’s really no need to ever go back and see the historical versions, or audit how the data changed, then it’s a good candidate for using Dolt’s nonlocal table support.

Nonlocal tables let you configure tables to behave like global tables and be accessible from any branch, without being included in versioning. To use nonlocal tables, define a dolt_nonlocal_tables configuration that maps certain table names to a target reference (like a branch). From that point on, queries for those tables will resolve to the designated reference across all branches.

Let’s test out nonlocal tables. First, create a new directory, initialize it as a Dolt database, and launch a SQL shell:

mkdir dolt-nonlocal-demo && cd dolt-nonlocal-demo
dolt init
dolt sql

Next, create the nonlocal table. In this example, we have a table that contains global configuration, and we want that configuration data to be available to all branches and not versioned with our data. We use a global_ prefix for the table name, which isn’t required, but is a good pattern to make it more obvious that this table holds global data and is accessible from all branches.

CREATE TABLE global_app_config (
  config_key   VARCHAR(100) NOT NULL PRIMARY KEY,
  config_value VARCHAR(100) NOT NULL
);

INSERT INTO global_app_config VALUES
  ('theme', 'light'),
  ('feature_x_enabled', 'false');

Now we need to tell Dolt that the new global_app_config table should be a nonlocal table by inserting a new row into the dolt_nonlocal_tables system table. Nonlocal tables are also “ignored” by default (meaning Dolt won’t version them), but it’s good practice to also explicitly add them to the dolt_ignore system table. Note also that after we make changes to dolt_nonlocal_tables and dolt_ignore, we need to stage those changes and commit them.

INSERT INTO dolt_nonlocal_tables (table_name, target_ref, options)
    VALUES ('global_*', 'main', 'immediate');

-- Optional but recommended: ensure these tables never get staged/committed by accident
INSERT INTO dolt_ignore (pattern, ignored) VALUES ('global_*', true);

-- Commit the configuration so *new branches inherit it*
CALL DOLT_ADD('dolt_nonlocal_tables', 'dolt_ignore');
CALL DOLT_COMMIT('-m', 'Configure global_* as nonlocal tables on main (immediate), and ignore them');

We’ve got a nonlocal table configured now, so we can test out how it works. We’re going to check out a new branch, make some changes to global_app_config, then verify that those changes are visible from all branches.

CALL DOLT_CHECKOUT('-b', 'feature/ui');

UPDATE global_app_config
    SET config_value = 'true'
    WHERE config_key = 'feature_x_enabled';

Here is the updated data in our global_app_config table:

SELECT * FROM global_app_config ORDER BY config_key;
+-------------------+--------------+
| config_key        | config_value |
+-------------------+--------------+
| feature_x_enabled | true         |
| theme             | light        |
+-------------------+--------------+
2 rows in set (0.00 sec)

If we look at dolt_status, we see those changes to global_app_config are not listed as uncommitted changes, since this table isn’t included in versioning.

SELECT * FROM dolt_status;
Empty set (0.00 sec)

Finally, let’s switch to a different branch, and confirm that the data we see in global_app_config matches what we updated in the other branch:

CALL DOLT_CHECKOUT('main');

SELECT * FROM global_app_config ORDER BY config_key;
+-------------------+--------------+
| config_key        | config_value |
+-------------------+--------------+
| feature_x_enabled | true         |
| theme             | light        |
+-------------------+--------------+
2 rows in set (0.00 sec)

Connecting to Branches#

Dolt allows you to reference a specific branch in a database by using syntax of the form <db_name>/<branch_name>. This is useful in queries (e.g. you can read from a different branch by specifying this syntax: SELECT * FROM mydb/mybranch.mytable;), and is particularly useful in database connection strings. If you want all your database connections to automatically connect to a specific branch, you can use this syntax in the connection string, and then not have to worry about calling dolt_checkout(), which also saves you a round trip to the database. This also makes it easy for you to move all your app’s connections to a different branch during testing.

How you specify that database connection string varies by the client you’re using. The general, MySQL-compatible form is:

user:password@tcp(localhost:3306)/mydb/mybranch

Here’s what it looks like in Python, with SQLAlchemy:

engine = create_engine(
    "mysql+pymysql://user:password@localhost:3306/mydb/mybranch"
)

And here’s an example with .NET’s Entity Framework Core:

options.UseMySql(
    "server=localhost;user=user;password=password;database=mydb/mydb",
    ServerVersion.AutoDetect(connectionString)
);

For more information about how to specify a branch-specific connection string in different ORMs, check out the blogs and sample code we provide for various ORMs.

Using Connection Pooling#

ORMs generally use a connection pool to avoid the costly overhead of repeatedly establishing new connections to your database. When a connection is released back to the pool, the pool is responsible for sending a message to the database over that connection to reset its state. This ensures that no session state leaks between threads, for example if one session assigned session variables with customer information, you wouldn’t want another thread to be able to read that other customer’s private data just because it’s reusing the same connection. Unfortunately, not all connection pools will send this reset session request. The Go MySQL driver maintainers won’t send this message when a connection is returned to a pool because they worry it will affect performance (although a concurrent process could reset the session asynchronously and make the performance impact minimal). For Dolt, this can be a bigger problem, because the branch you have checked out is also part of the session state. This means one thread could grab a connection, change its branch, then return it to the pool for another unsuspecting thread to pick up and be unaware that it’s not pointing at the branch it expects.

There are a few ways to deal with this. Some applications won’t need to switch branches, so they don’t need to worry about this concern. For applications that do need to work with multiple branches there are two approaches we recommend to customers:

Use one connection pool per branch – if your application only works with a small number of branches, then you can have a connection pool dedicated to each branch, using the branch connection approach below.
Run dolt_checkout() at the start of your logic – if your application dynamically creates branches, then your best bet may be to ensure you call dolt_checkout() at the start of your logic to ensure you’re on the expected branch. Alternatively, you can run SELECT active_branch() to sanity check what branch you’re on. Note that the behavior here is somewhat specific to the ORM you are using. Some ORMs let you have a connection and work with it over multiple queries until you explicitly release it, while other ORMs will automatically select a connection for you and may still choose a different connection in the pool for two queries that execute next to each other in your application logic.

Reflection and Working with Dolt’s System Tables#

Some ORMs rely heavily on schema reflection (sometimes called introspection) to understand the structure of a database at runtime. Reflection allows an ORM to discover tables, columns, types, and relationships dynamically, rather than requiring everything to be defined statically up front. Dolt supports schema reflection via information_schema, just like MySQL does. This means ORMs can reflect on tables in Dolt just as they would in MySQL.

In ORMs that support reflection, it can also be used to reflect on system tables, including Dolt system tables that expose version-control features and metadata (e.g. commit logs, diffs, branch metadata). The best approach to query these system tables depends on the capabilities of the ORM that you’re using.

In Python, for example, SQLAlchemy supports using reflection to dynamically construct table model definitions. Here’s an example with SQLAlchemy for querying the dolt_log system table, which shows you the commit history for your current branch. Notice that we don’t have to declare the structure of the dolt_log system table. Instead, we can specify autoload_with=engine to get SQLAlchemy to use reflection to discover the table’s schema.

    # Instantiate the dolt_log table. Using "autoload_with=engine" causes SQLAlchemy to 
    # load the column definitions from the database itself, using reflection.  
    dolt_log = Table("dolt_log", MetaData(), autoload_with=engine)
    stmt = select(dolt_log.c.commit_hash,
                  dolt_log.c.committer,
                  dolt_log.c.message
                  ).order_by(dolt_log.c.date.desc())

    with engine.connect() as conn:
        results = conn.execute(stmt)
        for row in results:
            # Process results...

Other ORMs, like .NET’s Entity Framework Core, rely on static models and less on reflection. Since the dolt_log system table has a static schema, you could define a model for it, then use the standard ORM tooling to query and process results using that model type.

Here’s a sample model for the fields our app needs from the dolt_log system table:

public class DoltCommit
{
    public string CommitHash { get; set; }
    public string Committer { get; set; }
    public string Message { get; set; }
    public DateTime CommitDate { get; set; }
}

We have to register this model with the framework so it knows it’s associated with the dolt_log table:

using Microsoft.EntityFrameworkCore;

public class AppDbContext : DbContext
{
    public DbSet<DoltCommit> DoltLog { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder
            .Entity<DoltCommit>()
            .HasNoKey()
            .ToTable("dolt_log");

        base.OnModelCreating(modelBuilder);
    }
}

From here, we can use that model to query the dolt_log system table:

using (var context = new AppDbContext())
{
    var recentCommits = context.DoltLog
        .OrderByDescending(c => c.CommitDate)
        .Take(10)
        .ToList();

    foreach (var commit in recentCommits)
    {
        Console.WriteLine($"{commit.CommitHash}: {commit.Message}");
    }
}

Finally, there’s always an escape hatch if you really need to execute raw SQL without using a model. For example, you may want to execute a stored procedure, like dolt_reset() or call a function. ORMs almost always provide a way to access a connection and execute a SQL statement directly.

For more examples and other ORMs, check out our integration documentation to find blogs and source code.

Conclusion#

ORMs can make it easier to build an application that works with a database, although they can also bring in some complexity, so understanding how they work is critical. Dolt is MySQL-compatible, so any ORM that works with MySQL will work with Dolt. We’ve personally tested over a dozen ORMs with Dolt, and documented them in blog posts and with sample code. Dolt features like schema overrides and nonlocal tables can help make it easier to use Dolt’s versioning features with ORMs.

If you want to discuss the ins and outs of ORMs, suggest another ORM for us to test out, or if you’re just curious about version-controlled, relational databases, then stop by the DoltHub Discord and say hello!

Making Featured Images: Agentic Art Direction

James Leng — Fri, 16 Jan 2026 00:00:00 GMT

The team here at DoltHub puts out a blog post every day, and each one needs a featured image. That means I get to run a small creative process daily to make it happen.

While I’m the only marketing person here, that might sound like a challenge, but over the past few months, I’ve built a system that really works. In fact, I look forward to it now. I think of it as running a two-AI creative team from concept to final image, and it’s become one of my favorite parts of the job. This article explains my process.

What’s a Featured Image?#

Featured images are the images that show up on social networks when you share a link to an article. When someone posts our blog to LinkedIn, Twitter, or Discord, the featured image is what people see before they click.

It’s also what appears at the top of the blog post itself.

So when I’m making these images, I’m thinking about two contexts: how it looks in someone’s feed, and how it looks when you land on the article. Both need to work.

If you want the technical details on how featured images get added to our blog metadata, we wrote about that here.

My Helpers#

Claude is my creative strategist. I built a Claude project with a master prompt that includes everything about DoltHub’s visual brand, which includes our mascot (I call him Dolty in my head), luminous color palette, favorite metaphors, and style of communication. Claude helps brainstorm concepts, suggests options, tests ideas, and spots problems before they become images.

Gemini (and seldomly the less efficient ChatGPT) is my artist. But Gemini is a very talented artist who doesn’t always read the brief. It makes beautiful images that sometimes have nothing to do with what I asked for. Managing Gemini is its own skill.

I’m the creative director. I read the blogs, figure out what story the image should tell, guide the concepts, direct the art, and make the final decision on which image to prepare for copy and collaboration with whoever is writing the blog.

The Four Questions#

Each blog is different. Some celebrate wins, some dive deep into technical topics, and some are just for fun. Before I start working with my AI team, I stick to these four guiding questions to keep things consistent:

What is this blog actually saying?#

I read the blog and make sure I understand the technical details. I can’t direct a visual for something I don’t get, and I can’t expect Claude or Gemini to get it right if I haven’t figured it out myself.

What’s the tone?#

The tone, technical depth, and author’s intent help me decide which direction to take.

When we announced that Dolt matches MySQL performance after five years, we were celebrating a big achievement, like mounting a summit. When Dustin wrote about his vibe-accounting experiment that was barely holding it together, it was playful, self-deprecating, and humorous. When Jason did a technical comparison with Neon, the tone was competitive, clear, and enablement-focused.

What visual reinforces the headline?#

Another rule: the image should always reinforce the headline. The image needs to make the same point as the headline, just visually.

These questions are my way to check for consistency. They help me make sure every image, no matter the blog, author, or topic, still feels like an authentic DoltHub Blog.

The Master Prompt#

The Claude project I built is the backbone of the whole thing. There are a couple of layers to this, but the bottom line is I designed a creative strategist with specific expertise.

Here’s part of it:

You are an IMAGE CONCEPT CREATOR for DoltHub.

You generate and evaluate visual concepts for landing pages, docs,
tweets, and blog posts. You think in terms of Dolt's existing
"Agent Universe" art style, and you extend that world with new scenes.

Your priorities are: CLARITY of concept → FIT with the article/message
→ ON-BRAND VISUAL STYLE → VARIETY of tone.

The prompt includes our entire visual world: blue agents with glowing teal antennas, vivid rim lighting, Git-tree metaphors, “good vs bad” split scenes, character specs, color codes, and the patterns we use again and again.

I also added evaluation criteria like “Rate correctness from 0-10,” “Does it avoid misleading claims?” and “Propose 1-3 improvements.” So when I ask for concepts, I get ideas with built-in quality checks. Claude explains its suggestions and points out problems before I move forward. Sometimes I agree, but sometimes I don’t so I update the memory or the prompt.

The best part is that after three months, the project remembers how I work:

I follow a structured creative process, starting with concept generation,
moving through iterative visual refinement, and concluding with
platform-specific content adaptation. He typically requests multiple
options (8+ image concepts, various copy approaches), then collaborates
to refine the strongest direction through detailed feedback cycles.

Technical accuracy is paramount - James consistently requests
fact-checking and verification against source material.

I designed the system, and now it understands how I work.

Concept Development#

Here’s how a typical session goes.

I add the blog and my notes from the four questions. Using the master prompt, Claude generates several image concepts — some funny, some serious, some very literal, and some abstract.

Then, I step in as director. I focus on the concepts I like, ask for variations, and challenge ideas, asking myself:

Is this actually accurate to what Dolt does and what the blog is trying to say?

Does this metaphor hold up if the reader knows Neon?

Why is this concept better than the others for this blog?

Example: “App Builders Deserve Better Databases”#

Jason’s blog compares how Dolt and Neon handle branching. The key point: Neon lets you create branches that you can’t merge them back, leading to dead ends, but Dolt gives you the full Git workflow, allowing you to press on without fear!

I steered the concepts toward a racing metaphor. The final idea was one Dolty running on a glowing track, while another agent crashes into a brick wall labeled “no merge.”

The metaphor fits well: Neon’s branches hit a wall, but Dolt keeps you moving forward with the ability to merge. If you want more on this topic, read Tim’s blog on How to Version Control a Database.

This part is fun — bouncing ideas around, narrowing down the concept, and reaching that moment when it all clicks. Claude is a great collaborator. It challenges me when I’m off, suggests new angles, and catches technical mistakes before they show up in the visuals.

Art Direction (The Grind)#

Now comes the part that really tests my patience.

Gemini is talented but also unpredictable. Once I have a solid concept from the strategy phase, I move to image generation — and that’s when things can get strange.

AI image generators do stuff like:

Wrong style (suddenly cartoonish when I need cinematic)
Off-brand mascot (wrong antenna glow, wrong proportions)
That “AI concept art” look where everything feels like a mood board
Random details I never asked for

My job is to keep refining the image until it matches what I have in mind.

Case Study: “Understanding Dolt Directories”#

Tim’s blog explains how Dolt uses directories on your filesystem. Educational stuff. Helps people understand what happens when they run dolt init.

My concept: Dolty examining a filesystem tree, focusing on the specific folders from Tim’s examples — directories/, one_more_db/, and_a_third_db/.

It sounds simple.

Here’s what actually happened:

Round 1-2: Gemini threw in noms/, refs/, chunks/ folders. Those are internal Dolt storage details. Tim mentions them, but they’re not the point. I needed the high-level structure.

Round 3: Used ~/dolt/ as the root directory. Tim’s example uses directories/. Wrong.

Round 4: Added a floating “subdirectories” label. No idea why. Cut it.

Round 5: Put .dolt as the root directory. That’s backwards. The .dolt folder lives inside the database directory, not above it.

Round 6: Generic names like src, data, docs. Now it looked like a stock filesystem image. Lost the whole point.

Round 7: Finally. directories/ at top, .dolt, one_more_db/, and and_a_third_db/ as children. Matches Tim’s actual examples.

It took seven rounds with the same concept throughout. The strategy phase was quick, but the art direction was a real grind.

This is what AI image generation is really like. You don’t just press a button and get magic. You’re directing a fast but inconsistent artist who needs constant guidance. From what I hear from my software engineer colleagues, this matches the experience with AI-generated code.

I’ve learned to expect this. The concept might come together in ten minutes, but the final image can take an hour of back-and-forth.

Quality Control#

I check everything against my framework:

Technical accuracy. The Directories image has to show the folder structure Tim actually describes. If an engineer reads the blog and then looks at the image, they shouldn’t think “wait, that’s wrong.”

Metaphor integrity. Racing track = database workflows. Brick wall = no merge capability. Summit = milestone reached. The metaphors have to map to real things.

Brand consistency. Dolty has the right glow. The lighting is that iridescent teal palette. Cinematic feel, not clip-art.

Tone match. Dustin’s DoltCash posts are goofy, so the images can be playful. Tim’s educational posts need to be clear. Jason’s competitive pieces need to feel authoritative.

This is how I keep quality high across all these different blogs, authors, and styles. The framework keeps everything consistent.

Final Polish in Canva#

Once I have the image locked, everything comes together in Canva.

Text sizing, title length consistency, subheading spacing, fades, and any last-minute image adjustments all happen in one Canva project. I’ve set up templates that match our blog dimensions and brand guidelines, so adding copy to a new image is pretty quick.

This step is where the image becomes the actual featured graphic. Gemini gives me the visual. Canva gives me the finished product with headline, subhead, and logo in place.

Having all the final refinements in one place makes things straightforward. If I need to tweak the title or adjust spacing, it’s a quick edit rather than regenerating the whole image.

Team Sign-Off#

Before anything ships, I send it to whoever at Dolt wrote the blog.

“Does this match what you wrote? Does the headline work? Is this what you meant?”

Usually, I get a quick “looks good, ship it.” Sometimes, the author wants the focus to be more on something else. A quick Discord message exchange and a couple of fast tweaks usually solve it.

While I might be the creative director, the blog’s author has the final say on whether the image represents their work.

Why I Like This#

I actually enjoy this process a lot.

Turning a blog about database directories into a visual story, finding the right metaphor for “Neon branches are dead ends,” and working through seven rounds with Gemini until the image finally matches my vision — all of this is rewarding.

I built a system that lets one person do the work of a small team. I wrote the master prompt, created the guiding questions, run the concepting, and direct the output. The AIs are collaborators, but I make the decisions.

When the image, headline, and blog all land the same argument? That’s a good feeling. But when the team, the audience, and the people love it? That’s a great feeling.

It’s a Process, so If You Want to Try…#

Start by building your strategist. Create a master prompt that includes your brand—characters, colors, metaphors, and tone. Don’t make your AI relearn this every time.

Figure out your own questions. What keeps your content consistent? My focus is on understanding, tone, audience, and visual reinforcement. Yours might be different, so take time to define them.

Keep strategy and execution separate. Use a reasoning model for concepts and an image model for visuals. Each tool has its own strengths.

Be ready for the art direction grind. The concept might come together quickly, but the final image could take several rounds. That’s normal.

Stay in control. You’re the creative director, so you decide what works, what fits the brand, and what tells the story. Use an image editing tool for final touches.

Wrapping Up#

The featured image is the first thing people notice about your content. Before anyone reads a word, they see the image. It sets expectations, shows the tone, and either supports or weakens your message.

I built a system that handles this quickly. One person can turn around images the same day, and readers actually connect to the content. The AIs make things faster, the framework keeps things consistent, and my judgment, along with collaboration with the author, makes it all work.

If you’re building technical content and want to talk visual strategy, or you just want to see more of our little agent universe, swing by our Discord. Happy to talk about this stuff.

Fast Path for `IN` Filters#

This optimization was highlighted as a sneak peek in the previous blog. When converting filters to indexes, we create a RangeTree that sorts and removes overlaps between any two ranges. This works great for arbitrary filters, but we may be doing unnecessary work for simpler filters of a specific form. The benchmark select_random_points filters a table with a randomly generated IN query, resulting in a query highly selective and non-contiguous. Rather than building an entire RangeTree, we can just sort and de-duplicate these point-select queries.

Relevant Benchmarks:

benchmark	from_latency	to_latency	percent_change
oltp_point_select	0.28	0.27	-3.57
select_random_points	0.58	0.55	-5.17

Avoid Heap Allocations in `transform.Inspect` and `transform.InspectExpr`#

During the analysis process, certain rules traverse sql.Node and sql.Expression trees looking for specific nodes or expressions without altering the structure of the trees. This is mainly done through the transform.Inspect() and transform.InspectExpr() functions. Previously, the inspect functions would be recursively called on the result of node.Children().

func InspectExpr(expr sql.Expression, f func(sql.Expression) bool) bool {
	children := expr.Children()
	for _, child := range children {
		if InspectExpr(child, f) {
			return true
		}
    }
    if f(expr) {
        return true
    }
    return false
}

Since the return type of expr.Children() is []sql.Expression, the node/expressions here would escape to the heap. Fortunately, most nodes have either 1 or 2 children, so we use a type switch for UnaryNode and BinaryNode to recursively call Inspect on the children directly.

func InspectExpr(expr sql.Expression, f func(sql.Expression) bool) (stop bool) {
	// Avoid allocating []sql.Expression
	switch e := expr.(type) {
	case expression.UnaryExpression:
		if InspectExpr(e.UnaryChild(), f) {
			return true
		}
	case expression.BinaryExpression:
		if InspectExpr(e.Left(), f) {
			return true
		}
		if InspectExpr(e.Right(), f) {
			return true
		}
	default:
		children := e.Children()
		for _, child := range children {
			if InspectExpr(child, f) {
				return true
			}
		}
	}
	if f(expr) {
		return true
	}
	return false
}

Relevant Benchmarks:

benchmark	from_latency	to_latency	percent_change
oltp_point_select	0.28	0.27	-3.57
oltp_read_only	5.28	5.18	-1.89
select_random_points	0.55	0.54	-1.82
select_random_ranges	0.56	0.55	-1.79
table_scan	28.67	28.16	-1.78

PlanBuilder `convertInt()` Improvements#

During plan-building, we convert integers into the smallest integer type that can hold the value. For example, 300 would go into a int16 as 300 is too large for an int8 and uint8. We used to do this by calling strconv.ParseInt and strconv.ParseUint with increasing bitSize arguments until we got a result that didn’t error. It’s much quicker to parse once with a bitSize of 64, and use bit-masking to convert the result into the appropriate integer.

Relevant Benchmarks:

benchmark	from_latency	to_latency	percent_change
groupby_scan	12.08	11.87	-1.74
index_join	2.03	1.96	-3.45
select_random_points	0.56	0.55	-1.79
select_random_ranges	0.58	0.57	-1.72
table_scan	28.16	27.66	-1.78

Concurrent `GroupBy`#

The groupByGroupIter iterates over the childIter, calculates a grouping key, and updates the aggregation buffer. We can take advantage of concurrency here: one thread for reading off the childIter, another to calculate the groupingKey and update the aggregation buffer.

Relevant Benchmarks:

benchmark	from_latency	to_latency	percent_change
groupby_scan	12.08	10.84	-10.26

Avoid Map in `GetFieldValue`#

As part of the move from sql.Row to sql.ValueRow change, we need to map the type encodings on disk to the wire format type encodings. In an attempt to simplify the case statements, we did this through a golang map. It turns out map access is not as free as we thought, and the frequent lookups added some significant overhead to GetFieldValue(). So removing the map and assigning the mapped types yielded a nice performance boost, specifically on benchmarks that involved returning a large number of rows.

Relevant Benchmarks:

benchmark	from_latency	to_latency	percent_change
covering_index_scan	0.55	0.54	-1.82
groupby_scan	10.65	10.46	-1.78
index_join	1.96	1.93	-1.53
table_scan	28.16	23.1	-17.97
types_table_scan	65.65	68.05	3.66

There is a small performance hit to types_table_scan due to the increased number of branches in the switch statement, but it’s worth it.

Custom Date Parsing Improvement#

As part of the previous blog, we switched away from the time.Time implementation of AppendDate for our own. While that gave us a nice bump in queries involving any DATE and DATETIME types, we noticed we could do a little better. The previous implementation made separate calls to time.Year(), time.Month(), time.Day(), etc., which includes some repeated work. Switching to year, month, day = time.Date() and hours, mins, secs = time.Clock() shaved off some time.

Relevant Benchmarks:

benchmark	from_latency	to_latency	percent_change
index_join_scan	1.37	1.34	-2.19
index_scan	22.69	22.28	-1.81
table_scan	23.1	22.69	-1.77
types_table_scan	68.05	66.84	-1.7

Pointer `TupleComparator`#

The DefaultTupleComparator implementation includes a fast member variable which was defined as [][2]ByteSize. This stored the starting and ending indices for fields to quickly compare Tuple prefixes. Since this is used to compare prefixes, the indexes always start at 0 and are always sequential, so we only need to track the ending index.

Relevant Benchmarks:

benchmark	from_latency	to_latency	percent_change
groupby_scan	10.46	9.91	-5.26
index_join	1.96	1.89	-3.57

Conclusion#

Altogether, these changes brought our mean read latency multiplier down from 1.05 to 1.00. Our overall read and write multiplier is now 0.96, meaning Dolt actually outperforms MySQL on these benchmarks. Of course, improvements can always be made, so we will continue to improve Dolt’s performance. Try out Dolt yourself, and feel free to file any performance issues. If you just want to chat, feel free to join our Discord.

DoltHub Blog - Latest Posts

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#

Writing a Go SQL driver

What’s the driver package?#

The Dolt driver#

Dolt’s driver.Connection#

Using a driver with Gorm#

Conclusion#

Using Dolt with ORMs

ORM Benefits#

Dolt Compatibility with ORMs#

Tricks and Tips for Using Dolt with an ORM#

Using ORMs with Historical Schemas#

Using ORMs with Non-Versioned Data#

Connecting to Branches#

Using Connection Pooling#

Reflection and Working with Dolt’s System Tables#

Conclusion#

Making Featured Images: Agentic Art Direction

What’s a Featured Image?#

My Helpers#

The Four Questions#

What is this blog actually saying?#

What’s the tone?#

What visual reinforces the headline?#

The Master Prompt#

Concept Development#

Example: “App Builders Deserve Better Databases”#

Art Direction (The Grind)#

Case Study: “Understanding Dolt Directories”#

Quality Control#

Final Polish in Canva#

Team Sign-Off#

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

Dolt’s `driver.Connection`#

Fast Path for `IN` Filters#

Avoid Heap Allocations in `transform.Inspect` and `transform.InspectExpr`#

PlanBuilder `convertInt()` Improvements#

Concurrent `GroupBy`#

Avoid Map in `GetFieldValue`#

Pointer `TupleComparator`#