fix: auto-sanitize hyphenated dolt_database on embedded-mode upgrade (#3231) (#3232)

Auto-sanitize hyphenated `dolt_database` names on embedded-mode upgrade. Projects initialized before #2142 retain hyphenated names in `metadata.json`; after the 1.0.0 embedded-mode default flip, those names are rejected by the embedded Dolt engine. This change detects legacy names on store open, renames the database directory, persists the fix to `metadata.json`, and adds a doctor check + init guard for future prevention.

Closes #3231. Related: #2142, #2160, #3128, #3129.

Thanks @kevglynn for the thorough fix, migration safety (collision detection, crash-safe ordering), and test coverage.
This commit is contained in:
Kevin Glynn 2026-04-20 16:17:26 -04:00 • committed by GitHub
commit dbf793fdb6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 412 additions and 6 deletions

View file

@ -351,6 +351,21 @@ func checkMetadataConfigValues(repoPath string) []string {
}
}
// Validate dolt_database for embedded-mode compatibility (GH#3231).
// Hyphens and dots are allowed by server mode but rejected by the
// embedded Dolt engine because database names are interpolated into
// system variable identifiers (@@<db>_head_ref) where only
// [a-zA-Z_][a-zA-Z0-9_]* is valid.
if cfg.DoltDatabase != "" && !cfg.IsDoltServerMode() {
sanitized := strings.ReplaceAll(cfg.DoltDatabase, "-", "_")
sanitized = strings.ReplaceAll(sanitized, ".", "_")
if sanitized != cfg.DoltDatabase {
issues = append(issues, fmt.Sprintf(
"metadata.json dolt_database: %q contains characters invalid in embedded mode — "+
"replace with %q or set dolt_mode to \"server\" (GH#3231)", cfg.DoltDatabase, sanitized))
}
}
// Validate deletions_retention_days
if cfg.DeletionsRetentionDays < 0 {
issues = append(issues, fmt.Sprintf("metadata.json deletions_retention_days: %d is invalid (must be >= 0)", cfg.DeletionsRetentionDays))

View file

@ -104,6 +104,96 @@ func TestCheckMetadataConfigValues(t *testing.T) {
}
})
// GH#3231: hyphenated dolt_database in embedded mode
t.Run("hyphenated dolt_database embedded mode", func(t *testing.T) {
metadataContent := `{
"database": "dolt",
"dolt_database": "my-cool-project",
"dolt_mode": "embedded"
}`
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), []byte(metadataContent), 0644); err != nil {
t.Fatalf("failed to write metadata.json: %v", err)
}
issues := checkMetadataConfigValues(tmpDir)
found := false
for _, issue := range issues {
if contains(issue, "invalid in embedded") {
found = true
break
}
}
if !found {
t.Errorf("expected invalid-chars warning for embedded mode, got: %v", issues)
}
})
// GH#3231: dotted dolt_database in embedded mode
t.Run("dotted dolt_database embedded mode", func(t *testing.T) {
metadataContent := `{
"database": "dolt",
"dolt_database": "my.project",
"dolt_mode": "embedded"
}`
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), []byte(metadataContent), 0644); err != nil {
t.Fatalf("failed to write metadata.json: %v", err)
}
issues := checkMetadataConfigValues(tmpDir)
found := false
for _, issue := range issues {
if contains(issue, "invalid in embedded") {
found = true
break
}
}
if !found {
t.Errorf("expected invalid-chars warning for dotted name in embedded mode, got: %v", issues)
}
})
// GH#3231: hyphenated dolt_database is OK in server mode
t.Run("hyphenated dolt_database server mode", func(t *testing.T) {
metadataContent := `{
"database": "dolt",
"dolt_database": "my-cool-project",
"dolt_mode": "server"
}`
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), []byte(metadataContent), 0644); err != nil {
t.Fatalf("failed to write metadata.json: %v", err)
}
issues := checkMetadataConfigValues(tmpDir)
for _, issue := range issues {
if contains(issue, "invalid in embedded") {
t.Errorf("should not warn about invalid chars in server mode, got: %s", issue)
}
}
})
// GH#3231: no dolt_mode defaults to embedded, hyphens should warn
t.Run("hyphenated dolt_database default mode", func(t *testing.T) {
metadataContent := `{
"database": "dolt",
"dolt_database": "my-project"
}`
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), []byte(metadataContent), 0644); err != nil {
t.Fatalf("failed to write metadata.json: %v", err)
}
issues := checkMetadataConfigValues(tmpDir)
found := false
for _, issue := range issues {
if contains(issue, "invalid in embedded") {
found = true
break
}
}
if !found {
t.Errorf("expected invalid-chars warning when dolt_mode is unset (defaults to embedded), got: %v", issues)
}
})
t.Run("valid dolt metadata", func(t *testing.T) {
metadataContent := `{
"database": "dolt",

View file

@ -104,7 +104,7 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
FatalError("unknown backend %q: only \"dolt\" is supported", backendFlag)
}
// Validate --database early, before any side effects
// Validate --database format early, before any side effects.
if database != "" {
if err := dolt.ValidateDatabaseName(database); err != nil {
FatalError("invalid database name %q: %v", database, err)
@ -164,6 +164,14 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
_ = os.Setenv("BEADS_DOLT_SHARED_SERVER", "1")
}
// Reject hyphens in --database for embedded mode. Must run AFTER
// serverMode is set above — otherwise isEmbeddedMode() always returns
// true and incorrectly rejects server-mode names (GH#3231).
if database != "" && strings.ContainsRune(database, '-') && isEmbeddedMode() {
FatalError("database name %q contains hyphens which are invalid in embedded mode; use underscores instead (e.g. %q)",
database, sanitizeDBName(database))
}
// Initialize config (PersistentPreRun doesn't run for init command)
if err := config.Initialize(); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to initialize config: %v\n", err)

View file

@ -4,7 +4,10 @@ package main
import (
"context"
"fmt"
"os"
"path/filepath"
"strings"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/doltserver"
@ -60,6 +63,9 @@ func acquireEmbeddedLock(beadsDir string, serverMode bool) (embeddeddolt.Unlocke
// newDoltStoreFromConfig creates a storage backend from the beads directory's
// persisted metadata.json configuration. Uses embedded Dolt by default;
// connects to dolt sql-server when dolt_mode is "server".
//
// For embedded mode, legacy hyphenated database names (pre-GH#2142) are
// auto-sanitized to underscores and the fix is persisted to metadata.json.
func newDoltStoreFromConfig(ctx context.Context, beadsDir string) (storage.DoltStorage, error) {
cfg, err := configfile.Load(beadsDir)
if err == nil && cfg != nil && cfg.IsDoltServerMode() {
@ -69,16 +75,80 @@ func newDoltStoreFromConfig(ctx context.Context, beadsDir string) (storage.DoltS
if cfg != nil {
database = cfg.GetDoltDatabase()
}
if sanitized := sanitizeDBName(database); sanitized != database {
if err := migrateHyphenatedDB(beadsDir, cfg, database, sanitized); err != nil {
return nil, fmt.Errorf("auto-sanitize database name %q → %q: %w", database, sanitized, err)
}
database = sanitized
}
return embeddeddolt.New(ctx, beadsDir, database, "main")
}
// sanitizeDBName replaces hyphens and dots with underscores for
// SQL-idiomatic embedded Dolt database names (GH#2142, GH#3231).
func sanitizeDBName(name string) string {
name = strings.ReplaceAll(name, "-", "_")
name = strings.ReplaceAll(name, ".", "_")
return name
}
// migrateHyphenatedDB renames a legacy hyphenated database directory and
// persists the sanitized name to metadata.json so subsequent opens use it.
// This handles projects initialized before GH#2142 that upgrade to
// embedded-mode-default builds (GH#3231).
func migrateHyphenatedDB(beadsDir string, cfg *configfile.Config, oldName, newName string) error {
dataDir := filepath.Join(beadsDir, "embeddeddolt")
oldDir := filepath.Join(dataDir, oldName)
newDir := filepath.Join(dataDir, newName)
oldExists := false
if info, err := os.Stat(oldDir); err == nil && info.IsDir() {
oldExists = true
}
if oldExists {
_, newErr := os.Stat(newDir)
switch {
case newErr == nil:
return fmt.Errorf("cannot auto-migrate database: both %q and %q exist under %s; remove one manually and retry",
oldName, newName, dataDir)
case !os.IsNotExist(newErr):
return fmt.Errorf("checking target directory %q: %w", newDir, newErr)
default:
if err := os.Rename(oldDir, newDir); err != nil {
return fmt.Errorf("renaming database directory: %w", err)
}
fmt.Fprintf(os.Stderr, "bd: migrated database directory %q → %q (GH#3231)\n", oldName, newName)
}
}
if cfg != nil && cfg.DoltDatabase != newName {
cfg.DoltDatabase = newName
if err := cfg.Save(beadsDir); err != nil {
return fmt.Errorf("persisting sanitized database name to metadata.json: %w", err)
}
fmt.Fprintf(os.Stderr, "bd: updated metadata.json dolt_database %q → %q (GH#3231)\n", oldName, newName)
}
return nil
}
// newReadOnlyStoreFromConfig creates a read-only storage backend from the beads
// directory's persisted metadata.json configuration.
//
// For embedded mode, invalid characters (hyphens, dots) are sanitized in-memory
// only — no directory renames or metadata.json writes. This prevents cross-repo
// hydration from mutating foreign projects (GH#3231).
func newReadOnlyStoreFromConfig(ctx context.Context, beadsDir string) (storage.DoltStorage, error) {
cfg, err := configfile.Load(beadsDir)
if err == nil && cfg != nil && cfg.IsDoltServerMode() {
return dolt.NewFromConfigWithOptions(ctx, beadsDir, &dolt.Config{ReadOnly: true})
}
// Embedded dolt is single-process so read-only is not enforced at the engine level.
return newDoltStoreFromConfig(ctx, beadsDir)
database := configfile.DefaultDoltDatabase
if cfg != nil {
database = cfg.GetDoltDatabase()
}
if sanitized := sanitizeDBName(database); sanitized != database {
database = sanitized
}
return embeddeddolt.New(ctx, beadsDir, database, "main")
}

View file

@ -3,7 +3,9 @@
package main
import (
"encoding/json"
"os"
"path/filepath"
"strings"
"testing"
@ -52,3 +54,217 @@ func TestEmbeddedNew_EmptyDatabaseRejected(t *testing.T) {
t.Errorf("unexpected error: %v", err)
}
}
// TestNewDoltStoreFromConfig_HyphenatedDBName verifies that
// newDoltStoreFromConfig auto-sanitizes hyphenated database names for embedded
// mode and persists the fix to metadata.json.
// Regression test for GH#3231: pre-#2142 projects break on embedded upgrade.
func TestNewDoltStoreFromConfig_HyphenatedDBName(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt tests")
}
beadsDir := t.TempDir()
cfg := &configfile.Config{
Database: "dolt",
DoltDatabase: "my-cool-project",
DoltMode: configfile.DoltModeEmbedded,
}
if err := cfg.Save(beadsDir); err != nil {
t.Fatalf("failed to save config: %v", err)
}
store, err := newDoltStoreFromConfig(t.Context(), beadsDir)
if err != nil {
t.Fatalf("newDoltStoreFromConfig failed (should have auto-sanitized): %v", err)
}
defer store.Close()
reloaded, err := configfile.Load(beadsDir)
if err != nil {
t.Fatalf("failed to reload config: %v", err)
}
if reloaded.DoltDatabase != "my_cool_project" {
t.Errorf("expected dolt_database to be sanitized to %q, got %q", "my_cool_project", reloaded.DoltDatabase)
}
}
// TestSanitizeDBName verifies the sanitization logic for database names.
func TestSanitizeDBName(t *testing.T) {
tests := []struct {
input string
want string
}{
{"my-project", "my_project"},
{"jtbot-core", "jtbot_core"},
{"no-hyphens-here", "no_hyphens_here"},
{"dots.and-hyphens", "dots_and_hyphens"},
{"already_clean", "already_clean"},
{"beads", "beads"},
}
for _, tt := range tests {
t.Run(tt.input, func(t *testing.T) {
got := sanitizeDBName(tt.input)
if got != tt.want {
t.Errorf("sanitizeDBName(%q) = %q, want %q", tt.input, got, tt.want)
}
})
}
}
// TestMigrateHyphenatedDB_PersistsToMetadata verifies that migrateHyphenatedDB
// updates metadata.json with the sanitized database name.
func TestMigrateHyphenatedDB_PersistsToMetadata(t *testing.T) {
beadsDir := t.TempDir()
cfg := &configfile.Config{
Database: "dolt",
DoltDatabase: "my-project",
}
if err := cfg.Save(beadsDir); err != nil {
t.Fatalf("failed to save config: %v", err)
}
if err := migrateHyphenatedDB(beadsDir, cfg, "my-project", "my_project"); err != nil {
t.Fatalf("migrateHyphenatedDB failed: %v", err)
}
data, err := os.ReadFile(filepath.Join(beadsDir, "metadata.json"))
if err != nil {
t.Fatalf("failed to read metadata.json: %v", err)
}
var saved configfile.Config
if err := json.Unmarshal(data, &saved); err != nil {
t.Fatalf("failed to parse metadata.json: %v", err)
}
if saved.DoltDatabase != "my_project" {
t.Errorf("expected dolt_database %q in metadata.json, got %q", "my_project", saved.DoltDatabase)
}
}
// TestMigrateHyphenatedDB_RenamesDirectory verifies that migrateHyphenatedDB
// renames the old hyphenated database directory to the sanitized name.
func TestMigrateHyphenatedDB_RenamesDirectory(t *testing.T) {
beadsDir := t.TempDir()
dataDir := filepath.Join(beadsDir, "embeddeddolt")
oldDir := filepath.Join(dataDir, "my-project")
newDir := filepath.Join(dataDir, "my_project")
if err := os.MkdirAll(oldDir, 0o755); err != nil {
t.Fatalf("failed to create old dir: %v", err)
}
sentinel := filepath.Join(oldDir, "sentinel.txt")
if err := os.WriteFile(sentinel, []byte("test"), 0o644); err != nil {
t.Fatalf("failed to write sentinel: %v", err)
}
cfg := &configfile.Config{DoltDatabase: "my-project"}
if err := cfg.Save(beadsDir); err != nil {
t.Fatalf("failed to save config: %v", err)
}
if err := migrateHyphenatedDB(beadsDir, cfg, "my-project", "my_project"); err != nil {
t.Fatalf("migrateHyphenatedDB failed: %v", err)
}
if _, err := os.Stat(oldDir); !os.IsNotExist(err) {
t.Error("old directory should no longer exist after rename")
}
if _, err := os.Stat(filepath.Join(newDir, "sentinel.txt")); err != nil {
t.Error("sentinel file should exist in renamed directory")
}
}
// TestMigrateHyphenatedDB_CollisionError verifies that migrateHyphenatedDB
// returns an error when both old and new directories exist (GH#3231).
func TestMigrateHyphenatedDB_CollisionError(t *testing.T) {
beadsDir := t.TempDir()
dataDir := filepath.Join(beadsDir, "embeddeddolt")
oldDir := filepath.Join(dataDir, "my-project")
newDir := filepath.Join(dataDir, "my_project")
if err := os.MkdirAll(oldDir, 0o755); err != nil {
t.Fatalf("failed to create old dir: %v", err)
}
if err := os.MkdirAll(newDir, 0o755); err != nil {
t.Fatalf("failed to create new dir: %v", err)
}
cfg := &configfile.Config{DoltDatabase: "my-project"}
if err := cfg.Save(beadsDir); err != nil {
t.Fatalf("failed to save config: %v", err)
}
err := migrateHyphenatedDB(beadsDir, cfg, "my-project", "my_project")
if err == nil {
t.Fatal("expected error when both directories exist, got nil")
}
if !strings.Contains(err.Error(), "both") {
t.Errorf("expected collision error message, got: %v", err)
}
}
// TestMigrateHyphenatedDB_NoOldDir verifies that migrateHyphenatedDB still
// updates metadata.json even when the old directory doesn't exist (e.g., fresh
// project where only metadata.json has the bad name).
func TestMigrateHyphenatedDB_NoOldDir(t *testing.T) {
beadsDir := t.TempDir()
cfg := &configfile.Config{DoltDatabase: "my-project"}
if err := cfg.Save(beadsDir); err != nil {
t.Fatalf("failed to save config: %v", err)
}
if err := migrateHyphenatedDB(beadsDir, cfg, "my-project", "my_project"); err != nil {
t.Fatalf("migrateHyphenatedDB failed: %v", err)
}
data, err := os.ReadFile(filepath.Join(beadsDir, "metadata.json"))
if err != nil {
t.Fatalf("failed to read metadata.json: %v", err)
}
var saved configfile.Config
if err := json.Unmarshal(data, &saved); err != nil {
t.Fatalf("failed to parse metadata.json: %v", err)
}
if saved.DoltDatabase != "my_project" {
t.Errorf("expected %q, got %q", "my_project", saved.DoltDatabase)
}
}
// TestNewDoltStoreFromConfig_DottedDBName verifies that dots are also
// auto-sanitized, not just hyphens (GH#3231).
func TestNewDoltStoreFromConfig_DottedDBName(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt tests")
}
beadsDir := t.TempDir()
cfg := &configfile.Config{
Database: "dolt",
DoltDatabase: "my.project",
DoltMode: configfile.DoltModeEmbedded,
}
if err := cfg.Save(beadsDir); err != nil {
t.Fatalf("failed to save config: %v", err)
}
store, err := newDoltStoreFromConfig(t.Context(), beadsDir)
if err != nil {
t.Fatalf("newDoltStoreFromConfig failed (should have auto-sanitized dots): %v", err)
}
defer store.Close()
reloaded, err := configfile.Load(beadsDir)
if err != nil {
t.Fatalf("failed to reload config: %v", err)
}
if reloaded.DoltDatabase != "my_project" {
t.Errorf("expected dolt_database %q, got %q", "my_project", reloaded.DoltDatabase)
}
}

View file

@ -76,8 +76,11 @@ func OpenSQL(ctx context.Context, dir, database, branch string) (*sql.DB, func()
if strings.TrimSpace(database) != "" {
if !validIdentifier.MatchString(database) {
return nil, nil, errors.Join(
fmt.Errorf("invalid database name: %q", database), cleanup())
msg := fmt.Sprintf("invalid database name: %q", database)
if strings.ContainsRune(database, '-') {
msg += "; hyphens are not allowed in embedded mode — replace with underscores in .beads/metadata.json dolt_database field, or run 'bd doctor'"
}
return nil, nil, errors.Join(errors.New(msg), cleanup())
}
if _, err := db.ExecContext(ctx, "USE `"+database+"`"); err != nil {
return nil, nil, errors.Join(err, cleanup())

View file

@ -236,7 +236,11 @@ func (s *EmbeddedDoltStore) initSchema(ctx context.Context) error {
return s.withRootConn(ctx, true, func(tx *sql.Tx) error {
if s.database != "" {
if !validIdentifier.MatchString(s.database) {
return fmt.Errorf("embeddeddolt: invalid database name: %q", s.database)
msg := fmt.Sprintf("embeddeddolt: invalid database name: %q", s.database)
if strings.ContainsRune(s.database, '-') {
msg += "; hyphens are not allowed in embedded mode — replace with underscores in .beads/metadata.json dolt_database field, or run 'bd doctor'"
}
return errors.New(msg)
}
if _, err := tx.ExecContext(ctx, "CREATE DATABASE IF NOT EXISTS `"+s.database+"`"); err != nil {
return fmt.Errorf("embeddeddolt: creating database: %w", err)