fix(storage): run the shared-store migration gate on the proxied open path (#5043) (#6055)

* fix(storage): run the shared-store migration gate on the proxied open path

The proxied-server / `bd serve` provider called MigrateUpWithLock with no
CheckRemoteMigrateGate variant at all, so it migrated a shared database on
every open — silently, since v1.2.2 (gastownhall/beads#5043, #5079). It now
passes the shared-store gate as a lock option, which puts it after the
converged fast path (a steady-state open still pays zero extra statements)
and after locked preparation (a fresh bootstrap reads version 0 and
passes). Because the gate reads dolt_remotes over SQL, a proxied database
that DOES have a remote now gets the full #4259 flow too.

Read commands opened with the new uow.WithReadOnly() warn and attach at the
current schema instead of failing, mirroring what embedded mode has done
for its read-only intent since bd-578h9.5 — extending the gate here without
that would newly brick every read on a workspace waiting for its operator,
which is the opposite of what the gate's own message promises. Writes still
refuse: they open without the option.

`bd migrate schema` on proxied mode flips from "not supported" to a success
report: the root pre-run's verb consent is set before the provider opens,
so the open itself performs the consented migration and RunE has nothing
left to do but say so. Gate refusals now render as the full typed block
(text and --json) on the proxied open and on `bd serve` startup, via a
renderTypedOpenError helper extracted from the store path — a daemon
refusing to start is the case with no operator watching, so its log is the
only place the remediation can appear.

One fix to the gate placement itself, found by uow's #5012 self-heal test:
skip the gate when the caller holds fresh-bootstrap heal authority. Gating
on the version alone was not enough — an init whose first migration pass
died part-way leaves a non-zero cursor, so its retry read "existing
database, migrations pending" and refused to finish migrating the database
it had just created. The capability is the durable proof of creation, so
the skip keys on it.

* fix(storage): restore the proxied claims with the code that delivers them

The migration gate's user-facing text described the proxied / `bd serve`
plane while only the sql-server store was gated, so PR #6048 stripped those
claims. This commit is where the code arrives, so the text comes back with
it: the shared-no-remote body names proxied-server mode again, as do the
decision constant, CheckSharedStoreMigrateGate's doc, and
WithMigrationGate's; upgrading.md regains a proxied subsection covering the
read-through warning and `bd serve`'s refusal to start.

This also closes the loop the review flagged on the remedy itself. The
refusal prescribes `bd migrate schema`, which this PR makes work in proxied
mode — previously it hard-refused there, so the gate's only offered remedy
was a dead end, and the root pre-run would have consumed the consent on the
open before RunE printed "not supported". With consent now scoped to that
one verb (#6048), bare `bd migrate`'s surviving proxied refusal grants
nothing on the way past. A test pins the pairing structurally: the command
the gate prescribes is the command that grants consent.

The read-through warning and the gate's own text now share one constant, so
they cannot drift apart.
This commit is contained in:
Julian Knutsen 2026-08-30 04:05:44 -07:00 • committed by GitHub
commit 94bbeab577
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
14 changed files with 650 additions and 66 deletions

View file

@ -354,6 +354,40 @@ func printGlobalDatabaseConsentHint(w io.Writer) {
schema.SharedConsentCommandGlobal)
}
// renderTypedOpenError prints the actionable block for the store-open failures
// that carry one, honoring --json, and reports whether it handled err. A false
// return means the caller should fall back to its own generic message.
//
// Every open path needs this — the Dolt store, the proxied unit-of-work
// provider, and `bd serve`'s startup. The proxied one used to render every
// failure as `%v` inside "failed to open uow provider", which turned a
// multi-line rebuild or migrate-consent guide into one truncated line.
func renderTypedOpenError(err error) bool {
// Schema skew gets dedicated UX with actionable rebuild instructions.
var skewErr *schema.SchemaSkewError
if errors.As(err, &skewErr) {
if jsonOutput {
handleSchemaSkewJSON(skewErr)
} else {
fmt.Fprint(os.Stderr, skewErr.UserMessage())
}
return true
}
// #4259 / #5920: the migrate gate blocks a silent in-place migration and
// tells the operator to migrate, adopt, or consent.
var gateErr *schema.RemoteMigrateGateError
if errors.As(err, &gateErr) {
if jsonOutput {
handleRemoteMigrateGateJSON(gateErr)
} else {
fmt.Fprint(os.Stderr, gateErr.UserMessage())
printGlobalDatabaseConsentHint(os.Stderr)
}
return true
}
return false
}
// isSchemaMigrateVerb reports whether cmd is `bd migrate schema` — the one
// invocation in which the operator asked for a schema migration by name. That
// request is the consent the shared-store gate wants for a database with no
@ -1668,8 +1702,16 @@ var rootCmd = &cobra.Command{
// root pre-run, before --dry-run/--inspect has had any effect. Proxied
// mode is where that is least visible, not where it is acceptable.
if proxiedServerMode {
p, err := newProxiedServerUOWProvider(rootCtx, beadsDir, databaseOverride, previewProviderOptions(previewMode)...)
p, err := newProxiedServerUOWProvider(rootCtx, beadsDir, databaseOverride,
rootProviderOptions(previewMode, useReadOnly)...)
if err != nil {
// Same typed rendering the store path gets below: a schema
// skew or a migration-gate refusal here carries a whole
// actionable block, and `%v` inside "failed to open uow
// provider" throws all of it away.
if rendered := renderTypedOpenError(err); rendered {
return SilentExit()
}
return HandleError("failed to open uow provider: %v", err)
}
// Fire the workspace's script hooks after commits on the
@ -1732,26 +1774,7 @@ var rootCmd = &cobra.Command{
if handleFreshCloneError(err) {
return SilentExit()
}
// Schema skew gets dedicated UX with actionable rebuild instructions.
var skewErr *schema.SchemaSkewError
if errors.As(err, &skewErr) {
if jsonOutput {
handleSchemaSkewJSON(skewErr)
} else {
fmt.Fprint(os.Stderr, skewErr.UserMessage())
}
return SilentExit()
}
// #4259: the remote-migrate gate blocks silent in-place migration of a
// remote-backed database and tells the operator to migrate-or-adopt.
var gateErr *schema.RemoteMigrateGateError
if errors.As(err, &gateErr) {
if jsonOutput {
handleRemoteMigrateGateJSON(gateErr)
} else {
fmt.Fprint(os.Stderr, gateErr.UserMessage())
printGlobalDatabaseConsentHint(os.Stderr)
}
if renderTypedOpenError(err) {
return SilentExit()
}
return HandleError("failed to open database: %v", err)

View file

@ -701,6 +701,36 @@ func stampWorkspaceVersionAfterMigrate(store storage.DoltStorage) {
}
}
// reportProxiedSchemaMigrate is `bd migrate schema`'s proxied-server arm. The
// provider open already reconciled the schema under this verb's consent, so
// there is nothing left to do but say so — and say it in the same shape the
// direct path uses, since a caller parsing --json should not have to branch on
// the workspace's storage mode.
//
// The open reports its own failures: a gate refusal or a failed migration
// aborts the command in root pre-run and never reaches RunE, so arriving here
// means the schema is reconciled. The applied count is not observable from
// here (it belongs to an open that has already returned), hence the "current"
// status rather than a count.
//
// No version stamping here, unlike the direct path: reconcileVersionProxiedServer
// already runs in the root pre-run after a successful provider open, so the
// marker the gate refusal held back is written as soon as the open succeeds.
func reportProxiedSchemaMigrate() error {
latest := schema.LatestVersion()
if jsonOutput {
return outputJSON(map[string]interface{}{
"status": "current",
"latest_version": latest,
"mode": "proxied-server",
"note": "schema reconciled during provider open",
})
}
fmt.Printf("%s\n", ui.RenderPass(fmt.Sprintf(
"✓ Schema reconciled during provider open (proxied-server mode); schema now at v%d", latest)))
return nil
}
func handleToSeparateBranch(branch string, dryRun bool) error {
b := strings.TrimSpace(branch)
if b == "" || strings.ContainsAny(b, " \t\n") {
@ -862,7 +892,12 @@ Example:
SilenceErrors: true,
RunE: func(cmd *cobra.Command, _ []string) error {
if usesProxiedServer() {
return HandleErrorRespectJSON("migrate schema is not supported in proxied-server mode")
// Proxied mode has no store-level SchemaMigrator to call: the
// provider open IS the migration, and by the time RunE runs it has
// already happened — with this verb's consent, which the root
// pre-run set before the open (schema.SetSharedMigrateConsent).
// So report, rather than refuse a verb that just did its job.
return reportProxiedSchemaMigrate()
}
CheckReadonly("migrate schema")

View file

@ -3,6 +3,8 @@ package main
import (
"bytes"
"encoding/json"
"errors"
"fmt"
"io"
"os"
"strings"
@ -304,3 +306,63 @@ func TestHandleRemoteMigrateGateJSON_SharedNoRemoteGlobal(t *testing.T) {
t.Errorf("commands = %v, want [%q]", cmds, schema.SharedConsentCommandGlobal)
}
}
// TestRenderTypedOpenError pins the rendering every store-open path depends
// on: the Dolt store open, the proxied unit-of-work provider open, and
// `bd serve`'s startup all call it, and all three must produce the whole
// actionable block rather than a one-line `%v`. A gate refusal at `bd serve`
// startup is the case with no operator watching, so the daemon's log is the
// only place the remediation can appear.
func TestRenderTypedOpenError(t *testing.T) {
capture := func(fn func() bool) (string, bool) {
origStderr := os.Stderr
r, w, pipeErr := os.Pipe()
if pipeErr != nil {
t.Fatal(pipeErr)
}
os.Stderr = w
handled := fn()
_ = w.Close()
os.Stderr = origStderr
var buf bytes.Buffer
if _, err := io.Copy(&buf, r); err != nil {
t.Fatal(err)
}
_ = r.Close()
return buf.String(), handled
}
t.Run("shared-store gate refusal renders the full block", func(t *testing.T) {
gate := &schema.RemoteMigrateGateError{
CurrentVersion: 53, LatestVersion: 66, Pending: 13,
Decision: "shared-no-remote",
}
out, handled := capture(func() bool {
return renderTypedOpenError(fmt.Errorf("uow: init schema: %w", gate))
})
if !handled {
t.Fatal("renderTypedOpenError = false, want true for a wrapped gate refusal")
}
if out != gate.UserMessage() {
t.Errorf("rendered output is not the full UserMessage:\n%s", out)
}
for _, want := range []string{"co-resident", "bd migrate schema", "Read commands keep working"} {
if !strings.Contains(out, want) {
t.Errorf("output missing %q:\n%s", want, out)
}
}
})
t.Run("an ordinary error is left to the caller", func(t *testing.T) {
out, handled := capture(func() bool {
return renderTypedOpenError(errors.New("connection refused"))
})
if handled {
t.Error("renderTypedOpenError = true, want false for an untyped error")
}
if out != "" {
t.Errorf("nothing should be printed for an untyped error, got:\n%s", out)
}
})
}

View file

@ -371,6 +371,14 @@ func runServe() error {
info.Database = topology.database
p, err := newSQLServerUOWProvider(rootCtx, info.BeadsDir, topology)
if err != nil {
// A daemon has no operator watching a prompt, so a migration-gate
// refusal here must fail startup loudly and completely: the whole
// block, in the service log, naming the one-time `bd migrate
// schema` that unblocks it. No prompt, no auto-consent, no
// half-started daemon serving a schema it refused to reconcile.
if rendered := renderTypedOpenError(err); rendered {
return SilentExit()
}
return HandleError("bd serve: %v", err)
}
defer func() {

View file

@ -137,6 +137,44 @@ func TestNoticeSharedMigrateRefusalPerDecision(t *testing.T) {
})
}
// TestSharedRefusalPrescribesAWorkingVerb closes the loop the review flagged:
// the shared-store refusal names a command, and that command must actually run
// wherever the refusal can appear. In proxied-server mode `bd migrate schema`
// used to hard-refuse, so the only remedy the gate offered there was a dead
// end — worse, the root pre-run would have consumed the consent on the open
// before RunE ever printed "not supported".
//
// The pairing is checked structurally rather than by driving a proxied
// workspace: the command the gate prescribes IS SharedConsentCommand, and the
// verb that grants consent for it is migrateSchemaCmd.
func TestSharedRefusalPrescribesAWorkingVerb(t *testing.T) {
refusal := &schema.RemoteMigrateGateError{
CurrentVersion: 65, LatestVersion: 66, Pending: 1,
Decision: "shared-no-remote", Shared: true,
}
if got := refusal.EscapeHint(); got != schema.SharedConsentCommand {
t.Fatalf("EscapeHint = %q, want %q", got, schema.SharedConsentCommand)
}
opts := refusal.Options()
if len(opts) != 1 || len(opts[0].Commands) != 1 || opts[0].Commands[0] != schema.SharedConsentCommand {
t.Fatalf("Options = %+v, want the single %q remedy", opts, schema.SharedConsentCommand)
}
if !strings.Contains(refusal.UserMessage(), schema.SharedConsentCommand) {
t.Errorf("UserMessage must name the remedy:\n%s", refusal.UserMessage())
}
// The prescribed command is `bd <path of migrateSchemaCmd>`, and that is
// exactly the command isSchemaMigrateVerb grants consent for.
wantPath := "bd " + strings.TrimPrefix(migrateSchemaCmd.CommandPath(), rootCmd.Name()+" ")
if wantPath != schema.SharedConsentCommand {
t.Fatalf("the gate prescribes %q but the consenting verb is %q", schema.SharedConsentCommand, wantPath)
}
if !isSchemaMigrateVerb(migrateSchemaCmd) {
t.Fatal("the command the gate prescribes must be the one that grants consent")
}
}
// TestPrintGlobalDatabaseConsentHint pins the one fact the gate's own block
// cannot know: which database the invocation targeted. Under --global the open
// hits `beads_global`, so the block's unflagged `bd migrate schema` would

View file

@ -137,17 +137,25 @@ type sqlServerUOWTopology struct {
rootPassword string
}
// previewProviderOptions is the CLI-side half of the preview policy: it turns
// the root pre-run's previewMode bool into the uow.ProviderOption slice the
// proxied-server provider is opened with. Extracted (rather than inlined at
// the call site) so the wiring — preview=true must produce uow.WithPreview(),
// preview=false must produce nothing — has something to unit test; the
// rootProviderOptions is the CLI-side half of the open-posture policy: it
// turns the root pre-run's two classifications into the uow.ProviderOption
// slice the proxied-server provider is opened with. Extracted (rather than
// inlined at the call site) so the wiring has something to unit test; the
// previous inline form had no test that would fail if a refactor dropped it.
func previewProviderOptions(preview bool) []uow.ProviderOption {
if !preview {
//
// The two are not exclusive but preview is stronger, and passing both would
// say two different things about an open that can only have one posture:
// preview neither creates nor migrates, while readOnly opens normally and only
// changes how a refused migration is handled. Preview wins.
func rootProviderOptions(preview, readOnly bool) []uow.ProviderOption {
switch {
case preview:
return []uow.ProviderOption{uow.WithPreview()}
case readOnly:
return []uow.ProviderOption{uow.WithReadOnly()}
default:
return nil
}
return []uow.ProviderOption{uow.WithPreview()}
}
// newProxiedServerUOWProvider opens the proxied-server provider and, in

View file

@ -11,26 +11,39 @@ import (
"github.com/stretchr/testify/require"
)
// TestPreviewProviderOptions pins the CLI-side wiring the reviewer flagged as
// untested: the root pre-run turns previewMode into providerOpts by calling
// this function, and a refactor that dropped or inverted that could not fail
// any existing test. uow.providerOptions is unexported, so this cannot poke
// inside the returned uow.ProviderOption values (see
// internal/storage/uow/preview_provider_test.go's TestApplyProviderOptions for
// the same-package introspection); it instead pins the one thing an external
// caller can observe — that preview=true yields exactly one option and
// preview=false yields none — which is what the CLI wiring is responsible for.
func TestPreviewProviderOptions(t *testing.T) {
if got := previewProviderOptions(false); got != nil {
t.Fatalf("previewProviderOptions(false) = %#v, want nil", got)
}
opts := previewProviderOptions(true)
if len(opts) != 1 {
t.Fatalf("previewProviderOptions(true) len = %d, want 1", len(opts))
}
if opts[0] == nil {
t.Fatal("previewProviderOptions(true)[0] is nil, want uow.WithPreview()")
// TestRootProviderOptions pins the CLI-side wiring the reviewer flagged as
// untested: the root pre-run turns its previewMode/useReadOnly classification
// into providerOpts by calling this function, and a refactor that dropped or
// inverted that could not fail any existing test. uow.providerOptions is
// unexported, so this cannot poke inside the returned uow.ProviderOption
// values (see internal/storage/uow/preview_provider_test.go's
// TestApplyProviderOptions for the same-package introspection); it instead
// pins what an external caller can observe — how many options each posture
// yields — which is what the CLI wiring is responsible for.
func TestRootProviderOptions(t *testing.T) {
for _, tt := range []struct {
name string
preview, readOnly bool
want int
}{
{name: "ordinary write open", want: 0},
{name: "preview", preview: true, want: 1},
{name: "read-only", readOnly: true, want: 1},
// Preview is the stronger posture and must win: it neither creates nor
// migrates, while read-only opens normally.
{name: "preview wins over read-only", preview: true, readOnly: true, want: 1},
} {
t.Run(tt.name, func(t *testing.T) {
opts := rootProviderOptions(tt.preview, tt.readOnly)
if len(opts) != tt.want {
t.Fatalf("rootProviderOptions(%t, %t) len = %d, want %d", tt.preview, tt.readOnly, len(opts), tt.want)
}
for i, o := range opts {
if o == nil {
t.Fatalf("rootProviderOptions(%t, %t)[%d] is nil", tt.preview, tt.readOnly, i)
}
}
})
}
}

View file

@ -294,6 +294,17 @@ workspace is written, so there is nothing to run `bd migrate schema` from
there: do step 2 from a client that is already set up, or join and migrate in
one step with `BD_ALLOW_REMOTE_MIGRATE=1 bd init …`.
The same rules apply in **proxied-server mode**, which is a shared server
reached through a local proxy. Two differences worth knowing:
- read commands print a warning and keep serving the current schema, rather
than the read simply not touching it;
- `bd serve` refuses to start against a database with pending migrations,
because a daemon has no operator to consent for it. Reconcile the schema
first with step 2, then start the daemon — or, for an unattended service,
put `BD_ALLOW_REMOTE_MIGRATE=1` in its environment as an explicit, auditable
standing consent.
## Cross-era Upgrades
If you're upgrading from a much older version of bd, inspect the storage layout

View file

@ -196,8 +196,9 @@ type DatabaseSelector func(ctx context.Context, conn DBConn, databaseName string
type MigrationGate func(context.Context, *sql.Conn) error
// WithMigrationGate installs a pre-migration gate for callers whose migration
// runs entirely inside MigrateUpWithLock, with no separate pre-open gate hook
// of the kind internal/storage/dolt runs in its own retry loop.
// runs entirely inside MigrateUpWithLock — the proxied/`bd serve` provider,
// which has no separate pre-open gate hook of the kind internal/storage/dolt
// runs in its own retry loop.
//
// It runs after the migration lock is acquired and after any locked
// preparation, immediately before MigrateUp. That placement is the whole
@ -304,7 +305,14 @@ func MigrateUpWithLock(ctx context.Context, conn *sql.Conn, databaseName string,
}
}
if o.migrationGate != nil {
// Fresh-bootstrap heal authority is proof that THIS logical open performed
// the exact bare CREATE DATABASE for the incarnation now being migrated —
// so creating it was consent for its schema, and the gate has nothing to
// protect. Checking the capability rather than re-reading the version is
// what makes that hold across a retry: a first pass that died part-way
// leaves a non-zero cursor behind, and a version-only test would then have
// the init refuse to finish migrating the database it just created.
if o.migrationGate != nil && o.freshBootstrapHeal == nil {
if gateErr := o.migrationGate(ctx, conn); gateErr != nil {
return 0, gateErr
}

View file

@ -976,6 +976,57 @@ func TestMigrateUpWithLockMigrationGate(t *testing.T) {
}
})
// Regression: the gate must not fire on an init that CREATED this
// database. Gating on the version alone was not enough — a first pass that
// died part-way leaves a non-zero cursor, so the retry read "existing
// database, migrations pending" and the init refused to finish migrating
// the database it had just created (caught by uow's #5012 self-heal test).
// Heal authority is the durable proof of creation, so it is what the skip
// keys on.
t.Run("fresh-bootstrap heal authority skips the gate", func(t *testing.T) {
db, mock, err := sqlmock.New()
if err != nil {
t.Fatalf("create sql mock: %v", err)
}
defer db.Close()
ctx := context.Background()
conn, err := db.Conn(ctx)
if err != nil {
t.Fatalf("pin mock connection: %v", err)
}
defer conn.Close()
lockName := MigrationLockName("testdb")
mock.ExpectQuery(regexp.QuoteMeta("SELECT GET_LOCK(?, ?)")).
WithArgs(lockName, migrationLockAcquireTimeoutSeconds).
WillReturnRows(sqlmock.NewRows([]string{"locked"}).AddRow(1))
expectOnePendingMigration(t, mock)
mock.ExpectQuery(regexp.QuoteMeta("SELECT RELEASE_LOCK(?)")).
WithArgs(lockName).
WillReturnRows(sqlmock.NewRows([]string{"released"}).AddRow(1))
gated := 0
applied, err := MigrateUpWithLock(ctx, conn, "testdb",
WithFreshBootstrapHeal(testFreshBootstrapHealCapability(), testBootstrapEndpoint),
WithMigrationGate(func(context.Context, *sql.Conn) error {
gated++
return errors.New("the gate must not run on a database this init created")
}))
if err != nil {
t.Fatalf("MigrateUpWithLock() error = %v", err)
}
if applied != 1 {
t.Fatalf("MigrateUpWithLock() applied = %d, want 1", applied)
}
if gated != 0 {
t.Fatalf("gate calls = %d, want 0 — creating a database is consent for its schema", gated)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet SQL expectations: %v", err)
}
})
t.Run("converged fast path never reaches the gate", func(t *testing.T) {
db, mock, err := sqlmock.New()
if err != nil {

View file

@ -129,11 +129,11 @@ const (
gateDecisionAdoptFastForward = "adopt-ff"
gateDecisionForkSkew = "fork-skew"
// gateDecisionSharedNoRemote (gastownhall/beads#5920): the database is
// shared with co-resident bd clients (a dolt sql-server) and has NO
// remote, so there is no fork to reason about — but migrating still
// promotes the schema cursor for every client at once and locks out each
// one still on an older binary. Unlocked by the migrate verb, --force, or
// AllowRemoteMigrateEnv.
// shared with co-resident bd clients (a dolt sql-server, directly or
// through proxied-server mode) and has NO remote, so there is no fork to
// reason about — but migrating still promotes the schema cursor for every
// client at once and locks out each one still on an older binary. Unlocked
// by the migrate verb, --force, or AllowRemoteMigrateEnv.
gateDecisionSharedNoRemote = "shared-no-remote"
)
@ -257,10 +257,10 @@ func (e *RemoteMigrateGateError) userBody() string {
" uncommitted local changes to discard.\n"
case gateDecisionSharedNoRemote:
return "\n" +
" This database is served to multiple clients (a dolt sql-server).\n" +
" Applying schema migrations promotes the schema version for EVERY\n" +
" client at once: bd clients still running an older version will refuse\n" +
" this database until they are upgraded.\n" +
" This database is served to multiple clients (dolt sql-server /\n" +
" proxied-server mode). Applying schema migrations promotes the schema\n" +
" version for EVERY client at once: bd clients still running an older\n" +
" version will refuse this database until they are upgraded.\n" +
"\n" +
" To migrate (explicit consent):\n" +
" 1. Upgrade bd on every client of this server first (or accept that\n" +
@ -498,9 +498,9 @@ func CheckRemoteMigrateGateForRemoteWithRemoteCheckAndAdopt(ctx context.Context,
}
// CheckSharedStoreMigrateGate is the gate for a database that is served to
// co-resident bd clients — today, an internal/storage/dolt sql-server store.
// It adds two refusals on top of the remote-backed #4259 flow
// (gastownhall/beads#5920):
// co-resident bd clients — an internal/storage/dolt sql-server store, or the
// proxied/`bd serve` unit-of-work provider. It adds two refusals on top of the
// remote-backed #4259 flow (gastownhall/beads#5920):
//
// - With NO remote, where the ordinary gate allows a silent in-place
// migration, it refuses unless the operator consented (the migrate verb,

View file

@ -5,6 +5,7 @@ import (
"database/sql"
"errors"
"fmt"
"os"
"strings"
"sync/atomic"
"time"
@ -44,6 +45,10 @@ type doltSQLProvider struct {
// non-mutating preview (--dry-run, --inspect). The open creates no
// database and applies no migration; see providerOptions.preview.
preview bool
// readOnly: the command that opened this provider only reads. Unlike
// preview it still bootstraps and migrates normally — it only changes what
// happens when the migration gate REFUSES; see providerOptions.readOnly.
readOnly bool
// eventsJournalEnabled activates the durable events journal for THIS
// provider instance only. See SetEventsJournalEnabled.
eventsJournalEnabled atomic.Bool
@ -105,6 +110,15 @@ type providerOptions struct {
// the same contract embeddeddolt.OpenForPreviewCommand gives the embedded
// path.
preview bool
// readOnly opens for a command that only reads (bd list, show, …). It is
// deliberately weaker than preview: the open still creates and migrates as
// usual, because a read command on a fresh or behind workspace has always
// been served by the ordinary open. It changes exactly one thing — when
// the shared-store migration gate refuses, the open warns and attaches to
// the database at its current schema instead of failing, so reads keep
// working through the upgrade window. That is the same warn-and-continue
// contract embeddeddolt gives its read-only-command intent.
readOnly bool
}
// WithPreview opens the provider for a non-mutating preview command.
@ -112,6 +126,11 @@ func WithPreview() ProviderOption {
return func(o *providerOptions) { o.preview = true }
}
// WithReadOnly opens the provider for a command that only reads.
func WithReadOnly() ProviderOption {
return func(o *providerOptions) { o.readOnly = true }
}
func applyProviderOptions(opts []ProviderOption) providerOptions {
var resolved providerOptions
for _, opt := range opts {
@ -231,12 +250,68 @@ func (p *doltSQLProvider) initSchemaAttempt(ctx context.Context, database string
}
if _, err := schema.MigrateUpWithLock(ctx, conn, database,
schema.WithDatabaseSelector(selectProbeDatabase),
schema.WithLockedPreparation(p.serverEndpoint, preparer.prepare)); err != nil {
schema.WithLockedPreparation(p.serverEndpoint, preparer.prepare),
// This provider serves a shared database by definition — an external
// or proxied sql-server, or `bd serve`'s own daemon — so the same
// refusal server mode gets applies here (gastownhall/beads#5920,
// #5043). Passing it as a lock option rather than calling the gate
// before MigrateUpWithLock is what keeps the steady-state open free:
// the converged fast path returns before the lock, and the gate, are
// ever reached. Preparation has already CREATEd and USEd the
// database by the time it runs, so a fresh bootstrap reads version 0
// and passes.
schema.WithMigrationGate(func(ctx context.Context, c *sql.Conn) error {
return schema.CheckSharedStoreMigrateGate(ctx, c, "", nil, nil)
})); err != nil {
var gateErr *schema.RemoteMigrateGateError
if errors.As(err, &gateErr) {
if p.readOnly {
return readThroughRefusedMigration(ctx, conn, database, gateErr)
}
// Explicit, though classifyInitSchemaError would reach the same
// verdict: a refusal must never be retried, because the retry
// would be an attempt to perform the migration it just refused.
return backoff.Permanent(gateErr)
}
return classifyInitSchemaError(err)
}
return nil
}
// readThroughRefusedMigration serves a read command from a database the
// migration gate refused to migrate: warn, attach at the current schema, and
// carry on. Writes remain refused (they open without WithReadOnly), so the
// database cannot be quietly written at a schema this binary believes is
// behind.
//
// This mirrors what embedded mode has done since bd-578h9.5 for its
// read-only-command intent. Without it, extending the gate to the proxied path
// would newly brick every read on a workspace waiting for its operator to
// consent — which is the opposite of the contract the gate's own message
// promises ("read commands keep working against the current schema").
// It is a free function rather than a provider method on purpose: it needs no
// provider state, and the parity test that enumerates doltSQLProvider's method
// set as the capability surface a caller can reach through a
// UnitOfWorkProvider would otherwise demand the notifying wrapper answer a
// startup helper.
func readThroughRefusedMigration(ctx context.Context, conn *sql.Conn, database string, gateErr *schema.RemoteMigrateGateError) error {
if err := db.NewDDLSQLRepository(conn).UseDatabase(ctx, database); err != nil {
if isSerializationError(err) {
return fmt.Errorf("uow: switching to database: %w", err)
}
// The gate refused AND the database cannot even be attached: report
// the refusal, which is the actionable half.
return backoff.Permanent(gateErr)
}
fmt.Fprintf(os.Stderr,
"Warning: %[1]v\n"+
" Read-only command: continuing on schema v%[2]d without migrating.\n"+
" Writes are blocked until the schema is reconciled. Run '%[3]s'\n"+
" once every client of this server is upgraded.\n",
gateErr, gateErr.CurrentVersion, schema.SharedConsentCommand)
return nil
}
// verifyTeamServerSchema is the team-server open path: the schema is owned by
// beads-team-server (bts), so bd never creates the database or migrates. It
// attaches to the existing database and verifies the schema version, then the
@ -520,6 +595,7 @@ func openAndInitSchema(ctx context.Context, ep proxy.Endpoint, database, rootUse
teamServer: teamServer,
expectedProjectID: expectedProjectID,
preview: opts.preview,
readOnly: opts.readOnly,
}
if err := initProvider.initSchema(ctx, database); err != nil {
@ -552,5 +628,6 @@ func openAndInitSchema(ctx context.Context, ep proxy.Endpoint, database, rootUse
teamServer: teamServer,
expectedProjectID: expectedProjectID,
preview: opts.preview,
readOnly: opts.readOnly,
}, nil
}

View file

@ -116,6 +116,11 @@ func TestInitSchemaAcquiresMigrationLockBeforeBootstrapDDL(t *testing.T) {
WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(1))
mock.ExpectQuery(regexp.QuoteMeta("SELECT COUNT(*) FROM dolt_status")).
WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(0))
// The shared-store migration gate, between preparation and MigrateUp. This
// init just created the database, so the cursor table does not exist yet,
// the gate reads version 0, and it allows: creating a database is consent
// for its schema.
expectCursorProbe(mock, "schema_migrations", false)
mock.ExpectExec(regexp.QuoteMeta("INSERT IGNORE INTO dolt_ignore VALUES (?, true)")).
WithArgs(sqlmock.AnyArg()).
WillReturnError(errors.New("first migration statement failed"))
@ -152,6 +157,8 @@ func TestInitSchemaAcquiresMigrationLockBeforeBootstrapDDL(t *testing.T) {
// probe correctly declines and the ordinary locked pass follows — GET_LOCK
// first, bootstrap DDL after.
func TestInitSchemaConvergenceProbeRunsWithNoSessionDatabase(t *testing.T) {
schema.SetSharedMigrateConsent(true)
defer schema.SetSharedMigrateConsent(false)
db, mock, err := sqlmock.New()
if err != nil {
t.Fatalf("create sql mock: %v", err)
@ -181,6 +188,11 @@ func TestInitSchemaConvergenceProbeRunsWithNoSessionDatabase(t *testing.T) {
WillReturnError(&mysql.MySQLError{Number: 1007, Message: "database exists"})
mock.ExpectExec(regexp.QuoteMeta("USE `beads`")).
WillReturnResult(sqlmock.NewResult(0, 0))
// The shared-store migration gate, between preparation and MigrateUp. This
// database is pre-existing and behind, so the gate would refuse — the
// consent below keeps this test about the lock/probe ordering it exists to
// pin. See TestInitSchemaSharedStoreGate for the gate's own behavior.
expectSharedGateProbe(mock, 1, 0)
mock.ExpectExec(regexp.QuoteMeta("INSERT IGNORE INTO dolt_ignore VALUES (?, true)")).
WithArgs(sqlmock.AnyArg()).
WillReturnError(errors.New("first migration statement failed"))

View file

@ -0,0 +1,238 @@
package uow
import (
"context"
"errors"
"regexp"
"strings"
"testing"
"github.com/DATA-DOG/go-sqlmock"
mysql "github.com/go-sql-driver/mysql"
"github.com/steveyegge/beads/internal/storage/schema"
)
// expectSharedGateProbe mocks the shared-store gate's read sequence on an
// existing database: CurrentVersion, PendingVersions, and the remote count.
func expectSharedGateProbe(mock sqlmock.Sqlmock, current, remotes int) {
for i := 0; i < 2; i++ { // CurrentVersion, then PendingVersions
expectCursorProbe(mock, "schema_migrations", true)
mock.ExpectQuery(regexp.QuoteMeta("SELECT COALESCE(MAX(version), 0) FROM schema_migrations")).
WillReturnRows(sqlmock.NewRows([]string{"version"}).AddRow(current))
}
mock.ExpectQuery(`SELECT COUNT\(\*\) FROM dolt_remotes`).
WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(remotes))
}
// expectBehindDatabaseThroughPreparation walks every statement of a proxied
// open against a pre-existing database that is one migration behind, up to and
// including the locked preparation — the point at which the migration gate
// runs. Returns the lock name so callers can expect its release.
func expectBehindDatabaseThroughPreparation(mock sqlmock.Sqlmock, database string, current int) string {
// Pre-lock convergence probe: the database exists, the session is put on
// it, and the cursor turns out to be behind — so the probe declines and
// the locked path runs.
expectNoSessionDatabase(mock)
expectDatabaseExistsProbe(mock, database, true)
mock.ExpectExec(regexp.QuoteMeta("USE `" + database + "`")).
WillReturnResult(sqlmock.NewResult(0, 0))
expectCursorProbe(mock, "schema_migrations", true)
mock.ExpectQuery(regexp.QuoteMeta("SELECT COALESCE(MAX(version), 0) FROM schema_migrations")).
WillReturnRows(sqlmock.NewRows([]string{"version"}).AddRow(current))
lockName := schema.MigrationLockName(database)
mock.ExpectQuery(regexp.QuoteMeta("SELECT GET_LOCK(?, ?)")).
WithArgs(lockName, 5).
WillReturnRows(sqlmock.NewRows([]string{"locked"}).AddRow(1))
// Locked preparation on a pre-existing database: the bare CREATE loses, so
// this init captures no fresh-bootstrap heal authority, and the USE is all
// it contributes.
mock.ExpectExec(regexp.QuoteMeta("CREATE DATABASE `" + database + "`")).
WillReturnError(&mysql.MySQLError{Number: 1007, Message: "database exists"})
mock.ExpectExec(regexp.QuoteMeta("USE `" + database + "`")).
WillReturnResult(sqlmock.NewResult(0, 0))
return lockName
}
func expectLockRelease(mock sqlmock.Sqlmock, lockName string) {
mock.ExpectQuery(regexp.QuoteMeta("SELECT RELEASE_LOCK(?)")).
WithArgs(lockName).
WillReturnRows(sqlmock.NewRows([]string{"released"}).AddRow(1))
}
// TestInitSchemaSharedStoreGate covers the proxied/`bd serve` open path's half
// of gastownhall/beads#5920 — and closes the gate leg of #5043, where this
// path ran MigrateUpWithLock with no CheckRemoteMigrateGate variant at all and
// so migrated a shared database on every open, silently, since v1.2.2.
func TestInitSchemaSharedStoreGate(t *testing.T) {
resetConsent := func(t *testing.T) {
t.Helper()
t.Cleanup(func() {
schema.SetSharedMigrateConsent(false)
schema.SetForceAllowRemoteMigrate(false)
})
}
t.Run("behind database is refused, permanently", func(t *testing.T) {
resetConsent(t)
t.Setenv(schema.AllowRemoteMigrateEnv, "0")
db, mock, err := sqlmock.New()
if err != nil {
t.Fatalf("create sql mock: %v", err)
}
defer db.Close()
lockName := expectBehindDatabaseThroughPreparation(mock, "beads", 1)
expectSharedGateProbe(mock, 1, 0)
// No migration statement between the gate and the release: the refusal
// must land before MigrateUp issues its first one.
expectLockRelease(mock, lockName)
p := &doltSQLProvider{defaultBranch: defaultBranch, db: db, serverEndpoint: "tcp:127.0.0.1:3306"}
err = p.initSchema(context.Background(), "beads")
var gateErr *schema.RemoteMigrateGateError
if !errors.As(err, &gateErr) {
t.Fatalf("initSchema() error = %T (%v), want *schema.RemoteMigrateGateError", err, err)
}
if gateErr.Decision != "shared-no-remote" {
t.Errorf("Decision = %q, want %q", gateErr.Decision, "shared-no-remote")
}
// The backoff budget is 60s; the mock scripts exactly one attempt.
// Reaching here at all proves the refusal was not retried — a retry
// would have hit unexpected-query errors and a different failure.
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet SQL expectations: %v", err)
}
})
t.Run("read-only open warns and serves the current schema", func(t *testing.T) {
resetConsent(t)
t.Setenv(schema.AllowRemoteMigrateEnv, "0")
db, mock, err := sqlmock.New()
if err != nil {
t.Fatalf("create sql mock: %v", err)
}
defer db.Close()
lockName := expectBehindDatabaseThroughPreparation(mock, "beads", 1)
expectSharedGateProbe(mock, 1, 0)
expectLockRelease(mock, lockName)
// The read-through: attach at the current schema and carry on. Still
// no migration statement anywhere.
mock.ExpectExec(regexp.QuoteMeta("USE `beads`")).
WillReturnResult(sqlmock.NewResult(0, 0))
p := &doltSQLProvider{defaultBranch: defaultBranch, db: db, serverEndpoint: "tcp:127.0.0.1:3306", readOnly: true}
var initErr error
stderr := captureStderr(t, func() {
initErr = p.initSchema(context.Background(), "beads")
})
if initErr != nil {
t.Fatalf("initSchema() error = %v, want nil — reads must keep working on the old schema", initErr)
}
for _, want := range []string{"Read-only command", "without migrating", "bd migrate schema"} {
if !strings.Contains(stderr, want) {
t.Errorf("warning missing %q:\n%s", want, stderr)
}
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet SQL expectations: %v", err)
}
})
t.Run("fresh database is created and migrated — creation is consent", func(t *testing.T) {
resetConsent(t)
t.Setenv(schema.AllowRemoteMigrateEnv, "0")
db, mock, err := sqlmock.New()
if err != nil {
t.Fatalf("create sql mock: %v", err)
}
defer db.Close()
lockName := schema.MigrationLockName("beads")
expectNoSessionDatabase(mock)
expectDatabaseExistsProbe(mock, "beads", false)
mock.ExpectQuery(regexp.QuoteMeta("SELECT GET_LOCK(?, ?)")).
WithArgs(lockName, 5).
WillReturnRows(sqlmock.NewRows([]string{"locked"}).AddRow(1))
mock.ExpectExec(regexp.QuoteMeta("CREATE DATABASE `beads`")).
WillReturnResult(sqlmock.NewResult(0, 0))
mock.ExpectExec(regexp.QuoteMeta("USE `beads`")).
WillReturnResult(sqlmock.NewResult(0, 0))
mock.ExpectQuery(regexp.QuoteMeta("SELECT DATABASE(), @@server_uuid, DOLT_HASHOF('HEAD')")).
WillReturnRows(sqlmock.NewRows([]string{"database", "server_uuid", "head"}).AddRow("beads", "server-uuid", "initial-head"))
mock.ExpectQuery(regexp.QuoteMeta("SELECT COUNT(*) FROM dolt_log")).
WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(1))
mock.ExpectQuery(regexp.QuoteMeta("SELECT COUNT(*) FROM dolt_status")).
WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(0))
// The gate on a database this init just created: no cursor table, so
// version 0, so allow — and MigrateUp proceeds to its first statement.
expectCursorProbe(mock, "schema_migrations", false)
mock.ExpectExec(regexp.QuoteMeta("INSERT IGNORE INTO dolt_ignore VALUES (?, true)")).
WithArgs(sqlmock.AnyArg()).
WillReturnError(errors.New("reached the first migration statement"))
expectLockRelease(mock, lockName)
p := &doltSQLProvider{defaultBranch: defaultBranch, db: db, serverEndpoint: "tcp:127.0.0.1:3306"}
err = p.initSchema(context.Background(), "beads")
if err == nil || !strings.Contains(err.Error(), "reached the first migration statement") {
t.Fatalf("initSchema() error = %v, want the fresh bootstrap to migrate", err)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet SQL expectations: %v", err)
}
})
t.Run("env consent migrates", func(t *testing.T) {
resetConsent(t)
t.Setenv(schema.AllowRemoteMigrateEnv, "1")
db, mock, err := sqlmock.New()
if err != nil {
t.Fatalf("create sql mock: %v", err)
}
defer db.Close()
lockName := expectBehindDatabaseThroughPreparation(mock, "beads", 1)
expectSharedGateProbe(mock, 1, 0)
mock.ExpectExec(regexp.QuoteMeta("INSERT IGNORE INTO dolt_ignore VALUES (?, true)")).
WithArgs(sqlmock.AnyArg()).
WillReturnError(errors.New("reached the first migration statement"))
expectLockRelease(mock, lockName)
p := &doltSQLProvider{defaultBranch: defaultBranch, db: db, serverEndpoint: "tcp:127.0.0.1:3306"}
var initErr error
_ = captureStderr(t, func() {
initErr = p.initSchema(context.Background(), "beads")
})
if initErr == nil || !strings.Contains(initErr.Error(), "reached the first migration statement") {
t.Fatalf("initSchema() error = %v, want the consented open to migrate", initErr)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet SQL expectations: %v", err)
}
})
// Preview never reaches MigrateUpWithLock at all, so it cannot reach the
// gate either — pinned so a future refactor cannot route preview through
// the migrating path and start refusing --dry-run on a behind workspace.
t.Run("preview open is unchanged", func(t *testing.T) {
resetConsent(t)
t.Setenv(schema.AllowRemoteMigrateEnv, "0")
db, mock, err := sqlmock.New()
if err != nil {
t.Fatalf("create sql mock: %v", err)
}
defer db.Close()
mock.ExpectExec(regexp.QuoteMeta("USE `beads`")).
WillReturnResult(sqlmock.NewResult(0, 0))
p := &doltSQLProvider{defaultBranch: defaultBranch, db: db, serverEndpoint: "tcp:127.0.0.1:3306", preview: true}
if err := p.initSchema(context.Background(), "beads"); err != nil {
t.Fatalf("initSchema() error = %v, want the attach-only preview open", err)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("unmet SQL expectations: %v", err)
}
})
}