feat(migrate): add --force flag as CLI twin of BD_ALLOW_REMOTE_MIGRATE (#4654)

* feat(migrate): add --force flag as CLI twin of BD_ALLOW_REMOTE_MIGRATE

The remote-migrate gate (#4259) refuses to auto-apply pending schema
migrations to a remote-backed database because two clones migrating
independently fork the schema unrecoverably. Until now the only unlock
was the env var BD_ALLOW_REMOTE_MIGRATE=1, which is awkward at the CLI
and can leak into child processes (git hooks, dolt subprocesses). The
--force flag is the natural CLI form of the designated-migrator escape
hatch: it is set before both autoMigrateOnVersionBump and the main store
open in the root PersistentPreRunE via a package-level bool, so it never
leaks out of the process. The env var remains supported for scripted/CI
use and is documented as a parenthetical alongside the new primary form.

Agent-Signature: claude-sonnet-4-6-high on behalf of matt wilkie

* fix(embeddeddolt): point lenient-gate guidance at bd migrate --force

The soft-fail (warn-and-continue) gate warning for read-only and
working-set-reconcile opens still named the env-var escape hatch; align
it with the new primary form introduced for the strict gate.

Agent-Signature: claude-fable-5-high on behalf of matt wilkie

* fix(migrate): reject --force with preview flags; harden override lifecycle

Review findings on the --force flag (cross-vendor: codex gpt-5.5 + claude
opus):

- --force combined with --dry-run/--inspect must fail before the store
  opens: with the gate overridden, the open itself applies pending
  migrations, so the preview flag would be honored only after the
  destructive work it exists to prevent (codex P2).
- Set-or-clear the override unconditionally so it is self-clearing under
  any future in-process root-command reuse (reviewer nit).
- Lock the agent-safety contract against the new flag form: AgentDirective
  must not embed 'bd migrate --force' any more than the env form (nit).

Agent-Signature: claude-fable-5-high on behalf of matt wilkie
This commit is contained in:
matt wilkie 2026-07-07 15:58:18 -07:00 • committed by GitHub
commit ef3ffd45b3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
15 changed files with 213 additions and 17 deletions

View file

@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
- `bd migrate --force` (and `bd migrate schema --force`): CLI flag twin of
`BD_ALLOW_REMOTE_MIGRATE=1` for bypassing the remote-migrate gate (#4259)
as the single designated migrator; process-local so it cannot leak into
child processes (git hooks, dolt subprocesses).
### Changed
- **Remote-ahead adopts fast-forward automatically when it is provably

View file

@ -711,7 +711,7 @@ func printBootstrapRemoteBehindGuidance(w io.Writer, e *schema.RemoteMigrateGate
" Re-running `"+rerunCmd+"` will NOT fix this — the remote itself is behind.\n"+
" Choose one:\n"+
" • This machine is the designated migrator (exactly ONE machine should be):\n"+
" "+schema.AllowRemoteMigrateEnv+"=1 bd migrate\n"+
" bd migrate --force\n"+
" bd dolt push\n"+
" then other machines re-run `bd bootstrap` to adopt the migrated database.\n"+
" • Another machine is the designated migrator: wait for it to push, then\n"+

View file

@ -131,7 +131,7 @@ func TestPrintBootstrapRemoteBehindGuidance(t *testing.T) {
for _, want := range []string{
"needs 1 schema migration (v49 -> v50)",
"Re-running `bd bootstrap` will NOT fix this",
schema.AllowRemoteMigrateEnv + "=1",
"bd migrate --force",
"bd dolt push",
} {
if !strings.Contains(out, want) {

View file

@ -1024,7 +1024,7 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
if bootstrappedFromRemote {
// Leave the workspace in the same finalized state the
// bd bootstrap sync path produces (GH#3201) so
// `BD_ALLOW_REMOTE_MIGRATE=1 bd migrate` and
// `bd migrate --force` (or BD_ALLOW_REMOTE_MIGRATE=1) and
// `bd dolt push` can open the cloned database.
fcfg := initTimeCloneConfig(initServerMode, serverHost, serverPort, serverSocket, serverUser, dbName)
if ferr := finalizeSyncedBootstrap(beadsDir, syncURL, fcfg, dbName); ferr != nil {

View file

@ -763,7 +763,7 @@ func TestEmbeddedInit(t *testing.T) {
}
for _, want := range []string{
"Re-running `bd init` will NOT fix this",
schema.AllowRemoteMigrateEnv + "=1",
"bd migrate --force",
"bd dolt push",
} {
if !strings.Contains(string(out), want) {

View file

@ -166,6 +166,35 @@ func isWorkingSetReconcileCommand(cmd *cobra.Command) bool {
return parent.Name() == "dolt" || parent.Name() == "vc"
}
// isForcedMigrate reports whether cmd is `bd migrate` or `bd migrate schema`
// invoked with --force: the operator confirming they are the single designated
// migrator, so the remote-migrate gate (#4259) must not block this run's store
// opens. Consulted in the root PersistentPreRunE because the gate fires during
// store open (and during autoMigrateOnVersionBump), long before the migrate
// command's own RunE.
func isForcedMigrate(cmd *cobra.Command) bool {
if cmd != migrateCmd && cmd != migrateSchemaCmd {
return false
}
force, _ := cmd.Flags().GetBool("force")
return force
}
// forcedMigratePreviewFlag returns the name of a preview flag (--dry-run,
// --inspect) that conflicts with --force on a forced migrate invocation, or ""
// when there is no conflict. The combination must be rejected BEFORE the store
// opens: with the gate override set, the open itself applies pending schema
// migrations, so the preview flag would be honored only after the destructive
// work it exists to prevent had already happened.
func forcedMigratePreviewFlag(cmd *cobra.Command) string {
for _, name := range []string{"dry-run", "inspect"} {
if v, err := cmd.Flags().GetBool(name); err == nil && v {
return name
}
}
return ""
}
// loadBeadsEnvFile loads .beads/.env into process environment for per-project
// Dolt credentials (GH#2520). Uses gotenv.Load which is non-overriding —
// existing shell env vars always take precedence.
@ -1032,6 +1061,20 @@ var rootCmd = &cobra.Command{
// the database (which breaks file watchers).
useReadOnly := isReadOnlyCommand(cmd.Name())
// If the operator passed --force on `bd migrate` or `bd migrate schema`,
// set the programmatic gate override before both autoMigrateOnVersionBump
// and the main store open — both open their own store connections and the
// gate fires on each.
forcedMigrate := isForcedMigrate(cmd)
if forcedMigrate {
if name := forcedMigratePreviewFlag(cmd); name != "" {
return HandleError("--force cannot be combined with --%s: opening the store with the gate overridden applies pending migrations before the preview runs", name)
}
}
// Unconditional set-or-clear keeps the override self-clearing should the
// root command ever be re-run in-process (tests, a future server mode).
schema.SetForceAllowRemoteMigrate(forcedMigrate)
// Auto-migrate database on version bump (bd-jgxi).
// Runs for ALL commands (including read-only ones) because the migration
// opens its own store connection, writes the version metadata, commits it,

View file

@ -29,6 +29,13 @@ Subcommands:
issues Move issues between repositories
schema Apply pending schema migrations (idempotent)
sync Set up sync.branch workflow for multi-clone setups
On a remote-backed database with pending schema migrations bd refuses to
migrate in place (#4259): migrating two clones independently forks the schema
so bd dolt pull can no longer merge — the break is silent and unrecoverable.
Use --force to confirm you are the single designated migrator, after which you
should publish the migrated schema with 'bd dolt push'. The env-var equivalent
BD_ALLOW_REMOTE_MIGRATE=1 remains supported for scripted/CI use.
`,
SilenceUsage: true,
SilenceErrors: true,
@ -777,6 +784,9 @@ func init() {
migrateCmd.Flags().Bool("update-repo-id", false, "Update repository ID (use after changing git remote)")
migrateCmd.Flags().Bool("inspect", false, "Show migration plan and database state for AI agent analysis")
migrateCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output migration statistics in JSON format")
// --force bypasses the remote-migrate gate (#4259) as the single designated
// migrator. No -f shorthand: deliberate typing for a fork-risk bypass.
migrateCmd.Flags().Bool("force", false, "Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1)")
migrateSyncCmd.Flags().Bool("dry-run", false, "Show what would be done without making changes")
migrateSyncCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output in JSON format")
@ -789,6 +799,9 @@ func init() {
migrateCmd.AddCommand(migrateHooksCmd)
migrateSchemaCmd.Flags().BoolVar(&jsonOutput, "json", false, "Output in JSON format")
// --force on migrate schema mirrors the parent command's flag; both trip the
// same isForcedMigrate check in main.go's PersistentPreRunE.
migrateSchemaCmd.Flags().Bool("force", false, "Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1)")
migrateCmd.AddCommand(migrateSchemaCmd)
rootCmd.AddCommand(migrateCmd)

View file

@ -0,0 +1,57 @@
package main
import "testing"
// TestIsForcedMigrate covers the root-PersistentPreRunE helpers behind
// `bd migrate --force`: only the migrate and migrate-schema commands report
// forced, and --force conflicts with the preview flags (--dry-run/--inspect)
// because the gate-overridden store open would apply pending migrations
// before the preview ever ran.
func TestIsForcedMigrate(t *testing.T) {
t.Cleanup(func() {
_ = migrateCmd.Flags().Set("force", "false")
_ = migrateCmd.Flags().Set("dry-run", "false")
_ = migrateCmd.Flags().Set("inspect", "false")
_ = migrateSchemaCmd.Flags().Set("force", "false")
})
set := func(name, v string) {
t.Helper()
if err := migrateCmd.Flags().Set(name, v); err != nil {
t.Fatalf("set --%s=%s: %v", name, v, err)
}
}
if isForcedMigrate(migrateCmd) {
t.Error("force unset: want false")
}
set("force", "true")
if !isForcedMigrate(migrateCmd) {
t.Error("force set on migrate: want true")
}
if isForcedMigrate(rootCmd) {
t.Error("non-migrate command: want false even while migrate's flag is set")
}
if got := forcedMigratePreviewFlag(migrateCmd); got != "" {
t.Errorf("no preview flags set: want \"\", got %q", got)
}
set("dry-run", "true")
if got := forcedMigratePreviewFlag(migrateCmd); got != "dry-run" {
t.Errorf("dry-run set: want \"dry-run\", got %q", got)
}
set("dry-run", "false")
set("inspect", "true")
if got := forcedMigratePreviewFlag(migrateCmd); got != "inspect" {
t.Errorf("inspect set: want \"inspect\", got %q", got)
}
if err := migrateSchemaCmd.Flags().Set("force", "true"); err != nil {
t.Fatalf("set migrate schema --force: %v", err)
}
if !isForcedMigrate(migrateSchemaCmd) {
t.Error("force set on migrate schema: want true")
}
if got := forcedMigratePreviewFlag(migrateSchemaCmd); got != "" {
t.Errorf("migrate schema has no preview flags: want \"\", got %q", got)
}
}

View file

@ -4174,6 +4174,13 @@ Subcommands:
schema Apply pending schema migrations (idempotent)
sync Set up sync.branch workflow for multi-clone setups
On a remote-backed database with pending schema migrations bd refuses to
migrate in place (#4259): migrating two clones independently forks the schema
so bd dolt pull can no longer merge — the break is silent and unrecoverable.
Use --force to confirm you are the single designated migrator, after which you
should publish the migrated schema with 'bd dolt push'. The env-var equivalent
BD_ALLOW_REMOTE_MIGRATE=1 remains supported for scripted/CI use.
```
bd migrate [flags]
@ -4183,6 +4190,7 @@ bd migrate [flags]
```
--dry-run Show what would be done without making changes
--force Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1)
--inspect Show migration plan and database state for AI agent analysis
--json Output migration statistics in JSON format
--update-repo-id Update repository ID (use after changing git remote)
@ -4279,7 +4287,8 @@ bd migrate schema [flags]
**Flags:**
```
--json Output in JSON format
--force Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1)
--json Output in JSON format
```
#### bd migrate sync

View file

@ -217,9 +217,10 @@ bd doctor # sanity-check before publishing
bd dolt push --force # make the remote authoritative
```
(`bd`'s migration gate may ask for `BD_ALLOW_REMOTE_MIGRATE=1` — on the
canonical clone, that is exactly the designated-migrator case the gate is
asking about.)
(`bd`'s migration gate may block here; run `bd migrate --force` on the
canonical clone — that is exactly the designated-migrator case the gate is
asking about. `BD_ALLOW_REMOTE_MIGRATE=1` is the env-var equivalent for
scripted use.)
### 3. On EVERY other clone: save local-only work, re-clone, re-apply

View file

@ -352,7 +352,7 @@ func (s *EmbeddedDoltStore) initSchema(ctx context.Context) error {
" coordination decision, not an auto-fix - do NOT run a migration unless\n" +
" you are the single designated migrator (only ONE clone may migrate a\n" +
" shared remote, else the schema forks; #4259):\n" +
" • designated migrator (only ONE machine): %[3]s=1 bd migrate && bd dolt push\n" +
" • designated migrator (only ONE machine): bd migrate --force && bd dolt push\n" +
" • every other clone (another already migrated): bd bootstrap\n" +
" • several machines: only ONE migrates; sync each other clone and run\n" +
" bd dolt pull after the migrator pushes, before upgrading it\n"
@ -363,13 +363,13 @@ func (s *EmbeddedDoltStore) initSchema(ctx context.Context) error {
" Working-set reconcile command: continuing on schema v%[2]d without\n"+
" migrating; the commit applies to the working set at the current\n"+
" schema."+sharedGuidance,
gateErr, gateErr.CurrentVersion, schema.AllowRemoteMigrateEnv)
gateErr, gateErr.CurrentVersion)
default: // openReadOnlyCommand
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."+sharedGuidance,
gateErr, gateErr.CurrentVersion, schema.AllowRemoteMigrateEnv)
gateErr, gateErr.CurrentVersion)
}
return nil
}

View file

@ -15,8 +15,23 @@ import (
// the designated migrator apply pending schema migrations to a remote-backed
// database despite the gate below. It is consulted only when the gate would
// otherwise fire, so exporting it permanently does not warn on every store open.
// The CLI-flag twin `bd migrate --force` is the preferred interactive form;
// this env var remains supported for scripted/CI use.
const AllowRemoteMigrateEnv = "BD_ALLOW_REMOTE_MIGRATE"
// forceAllowRemoteMigrate is the programmatic (in-process) twin of
// AllowRemoteMigrateEnv. Set by SetForceAllowRemoteMigrate before the store
// opens; unlike os.Setenv(AllowRemoteMigrateEnv), it cannot leak into child
// processes (git hooks, dolt subprocesses).
var forceAllowRemoteMigrate bool
// SetForceAllowRemoteMigrate sets (or clears) the programmatic override that
// allows a pending schema migration on a remote-backed database. It is called
// by `bd migrate --force` / `bd migrate schema --force` in the root
// PersistentPreRunE, before both autoMigrateOnVersionBump and the main store
// open. External test packages may reset it to false after each test case.
func SetForceAllowRemoteMigrate(v bool) { forceAllowRemoteMigrate = v }
// RemoteMigrateGateError is returned when bd is about to auto-apply pending
// schema migrations to an existing database that has a remote configured.
//
@ -204,7 +219,8 @@ func (e *RemoteMigrateGateError) userBody() string {
" Choose one:\n" +
" • You are the designated migrator (only ONE machine should be): migrate,\n" +
" then publish the migrated database to the remote:\n" +
" " + AllowRemoteMigrateEnv + "=1 bd migrate\n" +
" bd migrate --force\n" +
" (or " + AllowRemoteMigrateEnv + "=1 bd migrate in scripted/CI use)\n" +
" bd dolt push\n" +
" • Another machine has already migrated: adopt its database instead of\n" +
" migrating here — re-clone from the remote so you receive the migrated\n" +
@ -223,7 +239,7 @@ func (e *RemoteMigrateGateError) userBody() string {
// EscapeHint returns the escape-hatch string for JSON error output.
func (e *RemoteMigrateGateError) EscapeHint() string {
return AllowRemoteMigrateEnv + "=1 bd migrate"
return "bd migrate --force"
}
// AgentDirective is the non-runnable instruction surfaced to agents in place of
@ -307,7 +323,7 @@ func (e *RemoteMigrateGateError) Options() []GateOption {
{
ID: "migrate",
When: "you are the single designated migrator (only ONE machine, confirmed with the operator) and no other clone has migrated yet",
Commands: []string{AllowRemoteMigrateEnv + "=1 bd migrate", "bd dolt push"},
Commands: []string{"bd migrate --force", "bd dolt push"},
Risk: "if another clone also migrates independently, the schema forks unrecoverably (#4259)",
},
adopt,
@ -413,6 +429,19 @@ func checkRemoteMigrateGate(ctx context.Context, db DBConn, remoteName string, e
return nil // no remote — no cross-clone fork risk
}
// Programmatic override — set by `bd migrate --force` / `bd migrate schema
// --force` in the root PersistentPreRunE before both
// autoMigrateOnVersionBump and the main store open. Process-local by
// design: unlike os.Setenv(AllowRemoteMigrateEnv), it cannot leak into
// child processes (git hooks, dolt subprocesses). Consulted here — only
// once the gate would otherwise fire — so normal opens produce no noise.
if forceAllowRemoteMigrate {
fmt.Fprintf(os.Stderr,
"Warning: applying %d pending schema migration(s) to a remote-backed database (bd migrate --force); only one clone should migrate, then `bd dolt push`\n",
len(pending))
return nil
}
// Escape hatch — consulted only once the gate would actually fire, so an
// operator who exports it in a shell profile is not warned on every store
// open with nothing pending or no remote (bd-6dnrw.34). Any boolean true

View file

@ -33,6 +33,24 @@ func TestCheckRemoteMigrateGate(t *testing.T) {
WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(1))
}
t.Run("programmatic override (SetForceAllowRemoteMigrate) bypasses gate", func(t *testing.T) {
t.Setenv(AllowRemoteMigrateEnv, "0") // env-var escape hatch disabled
SetForceAllowRemoteMigrate(true)
defer SetForceAllowRemoteMigrate(false) // reset so subsequent tests are unaffected
db, mock, err := sqlmock.New()
if err != nil {
t.Fatalf("sqlmock.New: %v", err)
}
expectFiringGate(mock)
if err := CheckRemoteMigrateGate(context.Background(), db); err != nil {
t.Fatalf("SetForceAllowRemoteMigrate(true): expected nil, got %v", err)
}
if err := mock.ExpectationsWereMet(); err != nil {
t.Fatalf("SetForceAllowRemoteMigrate: unmet expectations: %v", err)
}
db.Close()
})
t.Run("escape hatch allows migration when the gate would fire", func(t *testing.T) {
for _, v := range []string{"1", "true", "TRUE"} {
t.Setenv(AllowRemoteMigrateEnv, v)
@ -269,6 +287,9 @@ func TestRemoteMigrateGateAgentSafety(t *testing.T) {
if strings.Contains(e.AgentDirective(), AllowRemoteMigrateEnv+"=1 bd migrate") {
t.Errorf("AgentDirective must not embed the runnable migrate command: %q", e.AgentDirective())
}
if strings.Contains(e.AgentDirective(), "bd migrate --force") {
t.Errorf("AgentDirective must not embed the runnable --force migrate command: %q", e.AgentDirective())
}
opts := e.Options()
if len(opts) != 2 {
@ -323,6 +344,9 @@ func TestRemoteMigrateGateAdoptFastForward(t *testing.T) {
if strings.Contains(e.AgentDirective(), AllowRemoteMigrateEnv+"=1 bd migrate") {
t.Errorf("AgentDirective must not embed the runnable migrate command: %q", e.AgentDirective())
}
if strings.Contains(e.AgentDirective(), "bd migrate --force") {
t.Errorf("AgentDirective must not embed the runnable --force migrate command: %q", e.AgentDirective())
}
opts := e.Options()
if len(opts) != 1 {

View file

@ -20,6 +20,13 @@ Subcommands:
schema Apply pending schema migrations (idempotent)
sync Set up sync.branch workflow for multi-clone setups
On a remote-backed database with pending schema migrations bd refuses to
migrate in place (#4259): migrating two clones independently forks the schema
so bd dolt pull can no longer merge — the break is silent and unrecoverable.
Use --force to confirm you are the single designated migrator, after which you
should publish the migrated schema with 'bd dolt push'. The env-var equivalent
BD_ALLOW_REMOTE_MIGRATE=1 remains supported for scripted/CI use.
```
bd migrate [flags]
@ -29,6 +36,7 @@ bd migrate [flags]
```
--dry-run Show what would be done without making changes
--force Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1)
--inspect Show migration plan and database state for AI agent analysis
--json Output migration statistics in JSON format
--update-repo-id Update repository ID (use after changing git remote)
@ -125,7 +133,8 @@ bd migrate schema [flags]
**Flags:**
```
--json Output in JSON format
--force Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1)
--json Output in JSON format
```
### bd migrate sync

View file

@ -176,11 +176,15 @@ also copy the `.beads` directory (or `dolt backup` in server mode) while no
bd dolt push # 1. CURRENT binary: publish all local work
bd export --all -o .beads/backup/pre-migrate.jsonl # 2. backup (see above)
# 3. install the new binary (see Upgrading above)
BD_ALLOW_REMOTE_MIGRATE=1 bd migrate # 4. migrate as the designated migrator
bd migrate --force # 4. migrate as the designated migrator
bd dolt push # 5. publish the migrated schema
bd version # 6. confirm the new version is active
```
`--force` confirms you are the single designated migrator so this run may
migrate the remote-backed database. For scripted or CI use,
`BD_ALLOW_REMOTE_MIGRATE=1 bd migrate` is the env-var equivalent.
**Multiple clones sharing one remote:**
```bash
@ -192,7 +196,7 @@ bd dolt pull
# 2. Designated migrator ONLY: back up, install the new binary, then migrate
# and publish.
bd export --all -o .beads/backup/pre-migrate.jsonl
BD_ALLOW_REMOTE_MIGRATE=1 bd migrate
bd migrate --force
bd dolt push
# 3. Every OTHER clone: install the new binary, then ADOPT the migrated database.