beads/internal/storage/dolt/errors.go
lydia eae64cabcc fix: detect backup files on database-not-found and after bd init (GH#2327)
When switching git branches, the Dolt database does not travel with the
branch, causing database not found errors. Previously the error message
only mentioned server misconfiguration. Now it:

1. Checks for .beads/backup/*.jsonl files and suggests bd backup restore
2. Lists branch switching as a common cause
3. After bd init creates a fresh DB, warns if backup files exist

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-11 20:08:44 -07:00

148 lines
5.1 KiB
Go

package dolt
import (
"database/sql"
"errors"
"fmt"
"os"
"path/filepath"
"strings"
mysql "github.com/go-sql-driver/mysql"
"github.com/steveyegge/beads/internal/storage"
)
// Sentinel errors for the dolt storage layer.
// These complement the storage-level sentinels (storage.ErrNotFound, etc.)
// with dolt-specific error types.
var (
// ErrTransaction indicates a transaction begin/commit/rollback failure.
ErrTransaction = errors.New("transaction error")
// ErrQuery indicates a database query failure.
ErrQuery = errors.New("query error")
// ErrScan indicates a failure scanning database rows into Go values.
ErrScan = errors.New("scan error")
// ErrExec indicates a database exec (INSERT/UPDATE/DELETE) failure.
ErrExec = errors.New("exec error")
)
// isTableNotExistError returns true if the error indicates a MySQL/Dolt
// "table doesn't exist" error (error 1146). Used to distinguish legitimate
// fallthrough (pre-migration databases without wisps table) from real errors
// (timeouts, connection failures, corrupt data).
func isTableNotExistError(err error) bool {
var mysqlErr *mysql.MySQLError
return errors.As(err, &mysqlErr) && mysqlErr.Number == 1146
}
// isSerializationError returns true if the error is a Dolt/MySQL serialization
// failure (Error 1213). This occurs when concurrent transactions conflict at
// commit time; the caller should retry the transaction.
func isSerializationError(err error) bool {
var mysqlErr *mysql.MySQLError
return errors.As(err, &mysqlErr) && mysqlErr.Number == 1213
}
// wrapDBError wraps a database error with operation context.
// If err is sql.ErrNoRows, it is converted to storage.ErrNotFound.
// If err is nil, nil is returned.
func wrapDBError(op string, err error) error {
if err == nil {
return nil
}
if errors.Is(err, sql.ErrNoRows) {
return fmt.Errorf("%s: %w", op, storage.ErrNotFound)
}
return fmt.Errorf("%s: %w", op, err)
}
// wrapTransactionError wraps a transaction error with operation context.
func wrapTransactionError(op string, err error) error {
if err == nil {
return nil
}
return fmt.Errorf("%s: %w: %w", op, ErrTransaction, err)
}
// wrapScanError wraps a row scan error with operation context.
func wrapScanError(op string, err error) error {
if err == nil {
return nil
}
return fmt.Errorf("%s: %w: %w", op, ErrScan, err)
}
// wrapQueryError wraps a query error with operation context.
func wrapQueryError(op string, err error) error {
if err == nil {
return nil
}
return fmt.Errorf("%s: %w: %w", op, ErrQuery, err)
}
// wrapExecError wraps an exec error with operation context.
func wrapExecError(op string, err error) error {
if err == nil {
return nil
}
return fmt.Errorf("%s: %w: %w", op, ErrExec, err)
}
// databaseNotFoundError builds the "database not found" error with a config-aware
// hint about sync.git-remote and backup recovery. Extracted from openServerConnection
// for testability.
func databaseNotFoundError(cfg *Config) error {
var b strings.Builder
fmt.Fprintf(&b, "database %q not found on Dolt server at %s:%d\n\n", cfg.Database, cfg.ServerHost, cfg.ServerPort)
// Check if backup files exist — strong signal this is a branch-switch or
// fresh-clone scenario rather than a server misconfiguration (GH#2327).
if HasBackupFiles(cfg.BeadsDir) {
b.WriteString("Backup files found in .beads/backup/ — this may be a branch-switch\n")
b.WriteString("or fresh-clone scenario where the Dolt database doesn't exist yet.\n\n")
b.WriteString("To restore your issues:\n")
b.WriteString(" bd init --prefix <prefix> # Initialize the database\n")
b.WriteString(" bd backup restore # Restore issues from backup\n\n")
b.WriteString("If this is NOT a branch switch, see common causes below.\n\n")
}
b.WriteString("Common causes:\n")
b.WriteString(" - Switched git branches (the Dolt database is runtime state, not in git)\n")
b.WriteString(" - The server is serving a different data directory than expected\n")
b.WriteString(" - The server was restarted and is using a different port\n")
b.WriteString(" - Another project's Dolt server is running on this port\n\n")
b.WriteString("To diagnose:\n")
b.WriteString(" bd doctor # Check server and database health\n")
b.WriteString(" bd dolt status # Show which data directory the server is using")
if cfg.SyncGitRemote != "" {
fmt.Fprintf(&b, "\n\nTip: sync.git-remote is configured (%s).\nRun bd init to bootstrap from the remote.", cfg.SyncGitRemote)
} else {
b.WriteString("\n\nTip: To bootstrap from an existing Dolt remote, set sync.git-remote\nin .beads/config.yaml and re-run bd init.")
}
return errors.New(b.String())
}
// HasBackupFiles checks whether .beads/backup/ contains any JSONL files,
// indicating a prior backup that could be restored (GH#2327).
func HasBackupFiles(beadsDir string) bool {
if beadsDir == "" {
return false
}
backupDir := filepath.Join(beadsDir, "backup")
entries, err := os.ReadDir(backupDir)
if err != nil {
return false
}
for _, e := range entries {
if !e.IsDir() && strings.HasSuffix(e.Name(), ".jsonl") {
return true
}
}
return false
}