{"record":{"id":"6a867b261663594e","repo":"gastownhall/beads","slug":"invalid-database-name-q-hyphens-are-not-allowed","errorCode":null,"errorMessage":"invalid database name: %q; hyphens are not allowed in embedded mode — replace with underscores in .beads/metadata.json dolt_database field, or run 'bd doctor'","messagePattern":"invalid database name: %q; hyphens are not allowed in embedded mode — replace with underscores in \\.beads/metadata\\.json dolt_database field, or run 'bd doctor'","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/embeddeddolt/open.go","lineNumber":83,"sourceCode":"\t\t\tdbErr = nil\n\t\t}\n\t\tif errors.Is(connErr, context.Canceled) {\n\t\t\tconnErr = nil\n\t\t}\n\t\treturn errors.Join(dbErr, connErr)\n\t}\n\n\tif err := db.PingContext(ctx); err != nil {\n\t\treturn nil, nil, errors.Join(err, cleanup())\n\t}\n\n\tif strings.TrimSpace(database) != \"\" {\n\t\tif !validIdentifier.MatchString(database) {\n\t\t\tmsg := fmt.Sprintf(\"invalid database name: %q\", database)\n\t\t\tif strings.ContainsRune(database, '-') {\n\t\t\t\tmsg += \"; hyphens are not allowed in embedded mode — replace with underscores in .beads/metadata.json dolt_database field, or run 'bd doctor'\"\n\t\t\t}\n\t\t\treturn nil, nil, errors.Join(errors.New(msg), cleanup())\n\t\t}\n\t\tif _, err := db.ExecContext(ctx, \"USE `\"+database+\"`\"); err != nil {\n\t\t\treturn nil, nil, errors.Join(err, cleanup())\n\t\t}\n\t\tif strings.TrimSpace(branch) != \"\" {\n\t\t\tif _, err := db.ExecContext(ctx, fmt.Sprintf(\"SET @@%s_head_ref = %s\", database, sqlStringLiteral(branch))); err != nil {\n\t\t\t\treturn nil, nil, errors.Join(err, cleanup())\n\t\t\t}\n\t\t}\n\t}\n\n\treturn db, cleanup, nil\n}\n\nfunc buildDSN(dir, database string) string {\n\tv := url.Values{}\n\tv.Set(doltembed.CommitNameParam, commitName)\n\tv.Set(doltembed.CommitEmailParam, commitEmail)","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/embeddeddolt/open.go#L65-L101","documentation":"OpenSQL() validates the database name against validIdentifier before switching to it; embedded Dolt cannot use hyphens in database names, so a name like 'my-db' fails to open. The error message explicitly points at .beads/metadata.json's dolt_database field and 'bd doctor' as the fix.","triggerScenarios":"Opening an embedded Dolt store whose dolt_database value in .beads/metadata.json contains hyphens (or otherwise fails the identifier regex), typically because the value was derived from a repo/directory name like 'my-project'.","commonSituations":"Cloning a project whose directory name contains hyphens; hand-editing metadata.json; older tooling that auto-derived the database name from a hyphenated folder name.","solutions":["Edit .beads/metadata.json and change dolt_database to use underscores (my-db → my_db)","Run `bd doctor` which offers to repair the database name automatically","If the DB was already created with the old name, export/re-import (bd export / bd import) into the underscore-named database"],"exampleFix":"// before (.beads/metadata.json)\n{\"dolt_database\": \"my-project-db\"}\n// after\n{\"dolt_database\": \"my_project_db\"}","handlingStrategy":"validation","validationCode":"var validIdentifier = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)\nif !validIdentifier.MatchString(cfg.DoltDatabase) {\n    return fmt.Errorf(\"dolt_database %q invalid; replace hyphens with underscores\", cfg.DoltDatabase)\n}","typeGuard":"func isValidDBName(name string) bool {\n    return strings.TrimSpace(name) != \"\" && !strings.ContainsRune(name, '-')\n}","tryCatchPattern":"db, cleanup, err := embeddeddolt.OpenSQL(ctx, dir, dbName, branch)\nif err != nil {\n    if strings.Contains(err.Error(), \"hyphens are not allowed\") {\n        return fmt.Errorf(\"fix .beads/metadata.json dolt_database (use underscores): %w\", err)\n    }\n    return err\n}","preventionTips":["Derive database names from directory names via a sanitizer that maps '-' to '_'","Validate metadata.json at startup with the identifier regex","Run `bd doctor` after cloning projects into hyphenated directories"],"tags":["go","embedded-dolt","configuration","database-name"],"backgroundTag":"invalid-database-name","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}