diff --git a/CHANGELOG.md b/CHANGELOG.md index 4aeb96e50..e0af9e7e2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/cmd/bd/bootstrap.go b/cmd/bd/bootstrap.go index 177a2c5d9..3d0db9667 100644 --- a/cmd/bd/bootstrap.go +++ b/cmd/bd/bootstrap.go @@ -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"+ diff --git a/cmd/bd/bootstrap_noninteractive_test.go b/cmd/bd/bootstrap_noninteractive_test.go index 80ee32298..8af908cb6 100644 --- a/cmd/bd/bootstrap_noninteractive_test.go +++ b/cmd/bd/bootstrap_noninteractive_test.go @@ -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) { diff --git a/cmd/bd/init.go b/cmd/bd/init.go index 4979db016..3b10a6046 100644 --- a/cmd/bd/init.go +++ b/cmd/bd/init.go @@ -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 { diff --git a/cmd/bd/init_embedded_test.go b/cmd/bd/init_embedded_test.go index c8d6f2f75..d846c14cc 100644 --- a/cmd/bd/init_embedded_test.go +++ b/cmd/bd/init_embedded_test.go @@ -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) { diff --git a/cmd/bd/main.go b/cmd/bd/main.go index 841f7451b..685a40e9c 100644 --- a/cmd/bd/main.go +++ b/cmd/bd/main.go @@ -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, diff --git a/cmd/bd/migrate.go b/cmd/bd/migrate.go index 1ea2e2db5..2822f0488 100644 --- a/cmd/bd/migrate.go +++ b/cmd/bd/migrate.go @@ -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) diff --git a/cmd/bd/migrate_force_test.go b/cmd/bd/migrate_force_test.go new file mode 100644 index 000000000..d393702ad --- /dev/null +++ b/cmd/bd/migrate_force_test.go @@ -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) + } +} diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index 34b47b655..cec07c9fd 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -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 diff --git a/docs/RECOVERY.md b/docs/RECOVERY.md index 0d6488a6c..fae367de0 100644 --- a/docs/RECOVERY.md +++ b/docs/RECOVERY.md @@ -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 diff --git a/internal/storage/embeddeddolt/store.go b/internal/storage/embeddeddolt/store.go index 566c8e6ba..f945094a4 100644 --- a/internal/storage/embeddeddolt/store.go +++ b/internal/storage/embeddeddolt/store.go @@ -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 } diff --git a/internal/storage/schema/remote_migrate_gate.go b/internal/storage/schema/remote_migrate_gate.go index 9329475ed..dcff8ef2a 100644 --- a/internal/storage/schema/remote_migrate_gate.go +++ b/internal/storage/schema/remote_migrate_gate.go @@ -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 diff --git a/internal/storage/schema/remote_migrate_gate_test.go b/internal/storage/schema/remote_migrate_gate_test.go index 299a303b8..ecf5e4c7f 100644 --- a/internal/storage/schema/remote_migrate_gate_test.go +++ b/internal/storage/schema/remote_migrate_gate_test.go @@ -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 { diff --git a/website/docs/cli-reference/migrate.md b/website/docs/cli-reference/migrate.md index 30a02c948..a0c731efb 100644 --- a/website/docs/cli-reference/migrate.md +++ b/website/docs/cli-reference/migrate.md @@ -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 diff --git a/website/docs/getting-started/upgrading.md b/website/docs/getting-started/upgrading.md index 2d6774fe3..9d9a8344e 100644 --- a/website/docs/getting-started/upgrading.md +++ b/website/docs/getting-started/upgrading.md @@ -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.