{"record":{"id":"785fde311974bfaa","repo":"gastownhall/beads","slug":"restore-from-backup-s-w","errorCode":null,"errorMessage":"restore from backup %s: %w","messagePattern":"restore from backup (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/storage/versioncontrolops/backup.go","lineNumber":40,"sourceCode":"\t}\n\treturn nil\n}\n\n// BackupRemove removes a configured Dolt backup destination.\nfunc BackupRemove(ctx context.Context, db DBConn, name string) error {\n\tif _, err := db.ExecContext(ctx, \"CALL DOLT_BACKUP('rm', ?)\", name); err != nil {\n\t\treturn fmt.Errorf(\"remove backup %s: %w\", name, err)\n\t}\n\treturn nil\n}\n\n// BackupRestore restores a database from a backup at the given URL into\n// the named database. When force is true, an existing database with the\n// same name is overwritten. Mirrors the CLI: dolt backup restore [--force] <url> <db_name>\nfunc BackupRestore(ctx context.Context, db DBConn, url, dbName string, force bool) error {\n\tif force {\n\t\tif _, err := db.ExecContext(ctx, \"CALL DOLT_BACKUP('restore', '--force', ?, ?)\", url, dbName); err != nil {\n\t\t\treturn fmt.Errorf(\"restore from backup %s: %w\", url, err)\n\t\t}\n\t} else {\n\t\tif _, err := db.ExecContext(ctx, \"CALL DOLT_BACKUP('restore', ?, ?)\", url, dbName); err != nil {\n\t\t\treturn fmt.Errorf(\"restore from backup %s: %w\", url, err)\n\t\t}\n\t}\n\treturn nil\n}\n\n// DirToFileURL resolves dir to an absolute path and returns a file:// URL.\nfunc DirToFileURL(dir string) (string, error) {\n\tabs, err := filepath.Abs(dir)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"resolve absolute path: %w\", err)\n\t}\n\treturn \"file://\" + abs, nil\n}\n","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/versioncontrolops/backup.go#L22-L58","documentation":"BackupRestore's forced branch runs `CALL DOLT_BACKUP('restore', '--force', ?, ?)` to overwrite an existing database from a backup, wrapping failures as \"restore from backup <url>: <cause>\". It throws when the forced restore fails — bad URL, unreadable backup, or driver error. Because force overwrites data, failures here deserve careful inspection of the cause.","triggerScenarios":"BackupRestore(ctx, db, url, dbName, true) when db.ExecContext fails: backup URL does not exist or is unreadable, dbName collides with a live database the server refuses to clobber, or connection error.","commonSituations":"Pointing at a file:// URL whose directory was moved or deleted; restoring over a database with open connections; URL built without DirToFileURL producing an invalid scheme.","solutions":["Verify the backup URL exists and is readable before restoring (os.Stat for file:// paths)","Resolve local dirs through DirToFileURL to get a correct file:// URL","Ensure no clients hold the target database open during forced restore","Inspect the wrapped cause for the exact Dolt rejection"],"exampleFix":"// before\nvcops.BackupRestore(ctx, db, \"/backups/db\", \"mydb\", true)\n// after\nu, err := vcops.DirToFileURL(\"/backups/db\")\nif err != nil { return err }\nif err := vcops.BackupRestore(ctx, db, u, \"mydb\", true); err != nil {\n\treturn fmt.Errorf(\"forced restore: %w\", err)\n}","handlingStrategy":"validation","validationCode":"func backupExists(u string) error {\n\tpath := strings.TrimPrefix(u, \"file://\")\n\tif path != u {\n\t\tif _, err := os.Stat(path); err != nil { return fmt.Errorf(\"backup missing: %w\", err) }\n\t}\n\treturn nil\n}\n// call before BackupRestore(..., force=true)","typeGuard":null,"tryCatchPattern":"if err := vcops.BackupRestore(ctx, db, url, dbName, true); err != nil {\n\treturn fmt.Errorf(\"forced restore of %s failed; target db state unknown: %w\", dbName, err)\n}","preventionTips":["Snapshot/verify the target database before any forced restore","Resolve paths with DirToFileURL and os.Stat the backup first","Quiesce writers to the target database during restore"],"tags":["dolt","backup","restore","data-loss"],"backgroundTag":"dolt-backup-operation-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}