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:
parent
825cd4c937
commit
9a1f086a41
5 changed files with 216 additions and 19 deletions
|
|
@ -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
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
||||
|
|
|
|||
58
test/docsync/doltpin_test.go
Normal file
58
test/docsync/doltpin_test.go
Normal 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)
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue