docs: pin the Dolt version instead of steering users to releases/latest (ga-m0dlk) (#5899)

The install instructions told users to run the upstream install.sh from
releases/latest, which today resolves to Dolt 2.3.1. Dolt 2.3.0 regressed
CALL DOLT_RESET('--hard'): a few percent of freshly created databases come
up with that procedure answering "Error 1105 (HY000): context canceled" for
the life of the server process. bd flatten and the Dolt-history compaction
in bd admin compact both finish by hard-resetting main onto a temporary
branch, and the merge-settle path behind bd dolt pull falls back to a hard
reset when it abandons a merge — so the documented happy path installed a
Dolt that breaks those operations on a database that otherwise looks fine.

Point the docs at a pinned version instead, with the measurements and the
raise criterion, and tell anyone already on 2.3.x how to check a database
and what to do about it. The pin and its rationale live in
scripts/ci/install-dolt.sh; the docs name the version once, on the Dolt
page, and everything else links there.

Also note that releases/latest resolves to the most recently created
release rather than the highest version, so it can move backwards — v1.88.2
was created after v2.2.4 and v2.3.0 — which makes "install latest" unsafe
independently of this defect.

test/docsync/doltpin_test.go keeps the documented pin, the copy-paste
install snippet and testutil.DoltDockerImage from drifting apart, which is
how the docs ended up on a broken release in the first place.

This documents the pin that gastownhall/beads#5894 applies to CI; land
after it so the reference to scripts/ci/install-dolt.sh resolves.
This commit is contained in:
Julian Knutsen 2026-08-20 22:41:24 -07:00 • committed by GitHub
commit 9a1f086a41
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 216 additions and 19 deletions

View file

@ -21,17 +21,100 @@ Embedded mode includes everything in the `bd` binary; no separate Dolt install
is needed. Install the standalone `dolt` CLI only when you want to run server
mode or work directly with the database via `dolt sql`.
Install a specific version. Do not install `releases/latest` — see
[Which Dolt version to install](#which-dolt-version-to-install) for the
version to use and why the pin exists.
```bash
# macOS
brew install dolt
DOLT_VERSION=2.2.0 # see "Which Dolt version to install" below
# Linux
curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash
os=$(uname -s | tr '[:upper:]' '[:lower:]')
arch=$(uname -m | sed -e 's/^x86_64$/amd64/' -e 's/^aarch64$/arm64/')
curl -fsSL "https://github.com/dolthub/dolt/releases/download/v${DOLT_VERSION}/dolt-${os}-${arch}.tar.gz" \
| tar -xz -C /tmp
sudo install -m 0755 "/tmp/dolt-${os}-${arch}/bin/dolt" /usr/local/bin/dolt
# Verify installation
# Verify you got the version you asked for
dolt version
```
`brew install dolt` installs whatever version the Homebrew formula currently
points at, which is not pinned. If you install that way, check `dolt version`
against the pin below.
### Which Dolt version to install
Beads pins Dolt to **2.2.0**. CI installs that same pin with
`scripts/ci/install-dolt.sh`, which records the per-version measurements and
the criterion for raising it; raise the pin here and in that script together.
This pin is about the standalone `dolt` CLI, which only server and
proxied-server mode use. Embedded mode is unaffected either way: it links the
Dolt engine into `bd` at the version in `go.mod`, currently the commit tagged
v2.2.0 upstream, no matter which `dolt` CLI is on your PATH.
Dolt 2.3.0 (released 2026-08-13) regressed `CALL DOLT_RESET('--hard')`. A few
percent of freshly created databases come up with that procedure unusable —
every call answers `Error 1105 (HY000): context canceled`, from any session
and any new connection, for the life of that server process. Nothing else
about the database looks wrong: `SELECT 1`, `CALL DOLT_CLEAN()`,
`CALL DOLT_CHECKOUT('.')`, `CALL DOLT_COMMIT()` and soft resets all work
normally, so the damage is invisible until something needs a hard reset.
Measured by creating fresh databases and immediately calling the procedure:
| Dolt version | Fresh databases with `DOLT_RESET('--hard')` broken |
|--------------|----------------------------------------------------|
| 2.1.8 | 0 / 40 |
| 2.2.0 | 0 / 60 |
| 2.3.0 | 3 / 60 |
| 2.3.1 | 3 / 100 |
Versions after 2.3.1 have not been measured. Raise the pin only once a newer
release is confirmed clean by that same measurement — not because it is
newer.
Pin rather than track `latest` for a second, independent reason: the upstream
`releases/latest` URL resolves to the most recently *created* release, not the
highest version, so it can move backwards — v1.88.2 was created on
2026-08-17, after both v2.2.4 and v2.3.0.
#### If you are already running 2.3.x
Whether a database is affected is decided per database, when it is created —
two databases on the same server can differ — so check each one you care
about, against the server that is actually serving it:
```bash
# 1. The working set must be clean first: on a dirty working set a hard
# reset discards uncommitted changes. If this returns any rows, commit
# or clean up before step 3.
dolt sql -q "SELECT * FROM dolt_status"
# 2. Control — this must succeed. If it does not, you have a different
# problem and step 3 proves nothing.
dolt sql -q "SELECT 1"
# 3. On a clean working set this is a no-op on a healthy database.
dolt sql -q "CALL DOLT_RESET('--hard')"
```
Step 2 succeeding while step 3 answers `Error 1105 (HY000): context canceled`
is the discriminating result — that database is affected. Both succeeding
means it is not.
The breakage lives in the running server process, not on disk, so restarting
`dolt sql-server` clears it — verified by re-running the check on an affected
database after a restart, with a healthy database on the same server as the
control. A restart re-rolls the dice for every database, though, so the
durable fix is to move to the pinned version.
This matters because `bd flatten` and the Dolt-history compaction in
`bd admin compact` both finish by hard-resetting `main` onto a temporary
branch, and the merge-settle path behind `bd dolt pull` / `bd sync` falls
back to a hard reset when it has to abandon a merge. See
[Maintenance](#maintenance--bd-prune-and-bd-purge).
### New Project
```bash
@ -160,6 +243,16 @@ bd prune --older-than 90d --ignore-references --force
transient. For full Dolt storage reclaim after deleting many rows, follow
with `bd flatten`.
**On Dolt 2.3.x, storage-reclaim operations can fail partway.** `bd flatten`
and the Dolt-history compaction in `bd admin compact` both build a temporary
branch and then hard-reset `main` onto it, and the merge-settle path behind
`bd dolt pull` / `bd sync` falls back to a hard reset when it abandons a
merge. On an affected database that hard reset returns
`Error 1105 (HY000): context canceled`: `bd flatten` and `bd admin compact`
stop at that step, and an abandoned merge is left without its rollback. See
[Which Dolt version to install](#which-dolt-version-to-install) for the check
and the fix.
## Migrating Between Backends
You can migrate data between embedded mode and server mode using `bd backup`.
@ -651,10 +744,13 @@ explicitly with `--config <file>`.
#### Setup with a Custom LaunchAgent
Install Dolt and initialize its data directory:
Install Dolt and initialize its data directory. Check the installed version
against [the pin](#which-dolt-version-to-install) — Homebrew's formula is not
pinned:
```bash
brew install dolt
dolt version
cd /opt/homebrew/var/dolt && dolt init
```

View file

@ -9,18 +9,28 @@ Set up beads with Dolt sync so your issues follow you across computers.
You need two tools installed on every machine:
| Tool | Minimum Version | Install |
|------|-----------------|---------|
| Tool | Version | Install |
|------|---------|---------|
| **bd** (beads CLI) | 0.59.0+ | See [Installation](/getting-started/installation) |
| **Dolt** | 2.2.0+ | `brew install dolt` or [dolt install script](https://github.com/dolthub/dolt/releases/latest/download/install.sh) |
| **Dolt** | A specific pinned version, not "latest" | See [Which Dolt version to install](/architecture/dolt#which-dolt-version-to-install) |
Verify both are installed:
```bash
bd version # must be 0.59.0+
dolt version # must be 2.2.0+
dolt version # must match the pinned version
```
Install a specific Dolt version rather than `releases/latest`. On Dolt 2.3.x a
few percent of freshly created databases come up with `CALL
DOLT_RESET('--hard')` broken for the life of the server process, which breaks
`bd flatten`, `bd admin compact` and the rollback behind `bd dolt pull`;
separately, the upstream `latest` URL can resolve to a *lower* version than
one released days earlier.
[Which Dolt version to install](/architecture/dolt#which-dolt-version-to-install)
has the measurements, the install command, and how to check a database you
already have.
## Initial Setup (First Computer)
### 1. Initialize beads

View file

@ -403,8 +403,12 @@ wrote, and dolt 1.52.1 fails at both serving and reading.
This is a warning, not a hard failure — there is deliberately no hard
version floor, so an older dolt can still be used at your own risk. To
resolve it, install a current dolt (https://docs.dolthub.com/introduction/installation)
and either update PATH or set `BEADS_DOLT_BIN` to the new binary's path.
resolve it, install the pinned dolt version — see
[Which Dolt version to install](/architecture/dolt#which-dolt-version-to-install)
— and either update PATH or set `BEADS_DOLT_BIN` to the new binary's path.
Install that specific version rather than `latest`: 2.3.x is a newer release
that satisfies this warning but carries a
[separate data-operation defect](/architecture/dolt#which-dolt-version-to-install).
The advisory repeats at most once per day, not on every command: the probe
result and the warning timestamp are cached (keyed by the binary's path,
@ -641,6 +645,35 @@ cd ~/project/component2 && bd init --prefix comp2
bd admin compact --dolt
```
If this or `bd flatten` stops with `Error 1105 (HY000): context canceled`,
see [Storage reclaim fails with "context canceled"](#storage-reclaim-fails-with-context-canceled)
below.
### Storage reclaim fails with "context canceled"
`bd flatten` and the Dolt-history compaction in `bd admin compact` finish by
hard-resetting `main` onto a temporary branch; the merge-settle path behind
`bd dolt pull` / `bd sync` falls back to a hard reset when it abandons a
merge. On Dolt 2.3.x a few percent of freshly created databases come up with
`CALL DOLT_RESET('--hard')` broken for the life of the server process, so on
an affected database those commands stop with:
```
Error 1105 (HY000): context canceled
```
Nothing else looks wrong — ordinary queries, commits, soft resets,
`CALL DOLT_CLEAN()` and `CALL DOLT_CHECKOUT('.')` all still work — so the
problem only shows up when something needs a hard reset. Confirm with the
check in
[Which Dolt version to install](/architecture/dolt#which-dolt-version-to-install),
which also covers the fix: restarting `dolt sql-server` clears it for now,
and installing the pinned Dolt version keeps it clear.
This applies to server and proxied-server mode, which use the standalone
`dolt` CLI. Embedded mode links its own Dolt engine at the version pinned in
`go.mod` and is not affected by which `dolt` CLI is on your PATH.
## Agent Issues
### Agent creates duplicate issues

View file

@ -21,14 +21,14 @@ Beads uses [Dolt](https://www.dolthub.com/) as its default storage backend. Dolt
### 1. Install Dolt
Do not install `releases/latest` — Dolt 2.3.x has a data-operation defect
that breaks `bd flatten` and `bd admin compact`. Use the pinned version and
install method in
[docs/architecture/dolt.md](../../docs/architecture/dolt.md), which carries
the measurements and the criterion for raising the pin.
```bash
# macOS
brew install dolt
# Linux
curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash
# Verify installation
# Verify you got the pinned version
dolt version
```

View file

@ -0,0 +1,58 @@
package docsync
import (
"os"
"path/filepath"
"regexp"
"testing"
)
// The pinned Dolt version appears in three places that must agree: the prose
// pin and the copy-paste install snippet in docs/architecture/dolt.md, and
// the test container tag in internal/testutil/testdoltcommon.go. Raising one
// and forgetting the others is how the docs drifted onto a Dolt release with
// a broken CALL DOLT_RESET('--hard') in the first place (see that page for
// the measurements). Read as text rather than importing testutil, which
// would pull testcontainers into the docs guard.
const (
doltPinPage = "docs/architecture/dolt.md"
doltPinImageFile = "internal/testutil/testdoltcommon.go"
)
var (
doltPinProseRE = regexp.MustCompile(`Beads pins Dolt to \*\*([0-9]+\.[0-9]+\.[0-9]+)\*\*`)
doltPinSnippetRE = regexp.MustCompile(`DOLT_VERSION=([0-9]+\.[0-9]+\.[0-9]+)`)
doltPinImageRE = regexp.MustCompile(`DoltDockerImage = "dolthub/dolt-sql-server:([0-9]+\.[0-9]+\.[0-9]+)"`)
)
func TestDoltVersionPinsAgree(t *testing.T) {
root := repoRoot()
find := func(rel string, re *regexp.Regexp, what string) string {
t.Helper()
data, err := os.ReadFile(filepath.Join(root, rel))
if err != nil {
t.Fatalf("read %s: %v", rel, err)
}
m := re.FindSubmatch(data)
if m == nil {
t.Fatalf("%s: no %s found (pattern %s). If the wording moved, update this guard "+
"rather than deleting it.", rel, what, re)
}
return string(m[1])
}
prose := find(doltPinPage, doltPinProseRE, "prose pin")
snippet := find(doltPinPage, doltPinSnippetRE, "install-snippet DOLT_VERSION")
image := find(doltPinImageFile, doltPinImageRE, "DoltDockerImage tag")
if prose != snippet {
t.Errorf("%s states the pin as %s but its install snippet uses DOLT_VERSION=%s",
doltPinPage, prose, snippet)
}
if prose != image {
t.Errorf("%s pins Dolt to %s but %s pins the test container to %s — "+
"the documented version and the version CI exercises must match",
doltPinPage, prose, doltPinImageFile, image)
}
}