feat(system-info): surface DB migration errors with troubleshooting links
When a startup database migration fails (e.g. issue #1319: pg_trgm not available so 000041 cannot build its trigram index), the application intentionally keeps booting so operators can reach the UI to diagnose. However, before this change the system info page silently dropped the "DB Version" row because the value was empty: - migration.go only cached the version after a successful m.Up(); the error path returned early and left migrationVersionSet=false. - system.go used CachedMigrationVersion's ok=false to skip emitting db_version, and the JSON tag was already omitempty. - SystemInfo.vue gated the entire row on v-if="systemInfo?.db_version". The end result was the most useful diagnostic surface vanishing in the exact failure mode that needs it most — Wiki ingest and KG features would silently produce nothing with no UI hint. Changes: - migration.go: replace sync.Once-based setter with an RWMutex-guarded state struct holding {version, dirty, err}. Every failure path now calls captureMigrationFailure(m, err), which best-effort reads m.Version() so the cached value still reflects the partial state. - system.go (handler): always emit db_version (falling back to "unknown" when no version could be read), append " (failed)" when an error is recorded, and add db_migration_error to the response. - swagger / client SDK: keep the API contract in sync with the new response field. - SystemInfo.vue: render the DB version row whenever either field is present, show a "Migration failed" danger tag, and add a full-width alert below the row carrying the error message plus two links: 1. View troubleshooting guide -> new docs/migration-troubleshooting.md 2. Report an issue -> github.com/Tencent/WeKnora/issues/new, prefilled with the captured error and environment metadata. - docs/migration-troubleshooting.md: new self-service guide covering the common failure modes (missing extension, dirty state, privileges, out of disk, schema drift) with concrete psql / make commands. - i18n: add the new keys to zh-CN, en-US, ko-KR, ru-RU. Refs #1319. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -16,24 +16,66 @@ import (
|
||||
)
|
||||
|
||||
var (
|
||||
migrationStateMu sync.RWMutex
|
||||
currentMigrationVersion uint
|
||||
currentMigrationDirty bool
|
||||
migrationVersionOnce sync.Once
|
||||
migrationVersionSet bool
|
||||
currentMigrationError string
|
||||
)
|
||||
|
||||
// CachedMigrationVersion returns the migration version captured at startup.
|
||||
// Returns (version, dirty, ok). ok is false if the version was never captured.
|
||||
//
|
||||
// Note: when migrations fail mid-way, the cache may still be populated via a
|
||||
// best-effort m.Version() call inside RunMigrationsWithOptions so the system
|
||||
// info endpoint can surface the partial state. Check CachedMigrationError() to
|
||||
// distinguish a clean version reading from a recorded-after-failure one.
|
||||
func CachedMigrationVersion() (uint, bool, bool) {
|
||||
migrationStateMu.RLock()
|
||||
defer migrationStateMu.RUnlock()
|
||||
return currentMigrationVersion, currentMigrationDirty, migrationVersionSet
|
||||
}
|
||||
|
||||
func setMigrationVersion(version uint, dirty bool) {
|
||||
migrationVersionOnce.Do(func() {
|
||||
// CachedMigrationError returns the error message captured when the most recent
|
||||
// migration attempt failed at startup. Empty string means migrations either
|
||||
// succeeded or were never run.
|
||||
func CachedMigrationError() string {
|
||||
migrationStateMu.RLock()
|
||||
defer migrationStateMu.RUnlock()
|
||||
return currentMigrationError
|
||||
}
|
||||
|
||||
// setMigrationState records the latest known migration state. Unlike the old
|
||||
// sync.Once-based setter, this is intentionally idempotent-overwrite so the
|
||||
// failure path (which runs after Up() errored) can replace the pre-migration
|
||||
// snapshot taken from the initial m.Version() call.
|
||||
func setMigrationState(version uint, dirty bool, errMsg string, versionKnown bool) {
|
||||
migrationStateMu.Lock()
|
||||
defer migrationStateMu.Unlock()
|
||||
if versionKnown {
|
||||
currentMigrationVersion = version
|
||||
currentMigrationDirty = dirty
|
||||
migrationVersionSet = true
|
||||
})
|
||||
}
|
||||
currentMigrationError = errMsg
|
||||
}
|
||||
|
||||
// captureMigrationFailure best-effort queries m for the current version so the
|
||||
// system info endpoint can show "N (failed)" instead of vanishing the row, and
|
||||
// stores the human-readable error message. Always returns the original error.
|
||||
func captureMigrationFailure(m *migrate.Migrate, err error) error {
|
||||
versionKnown := false
|
||||
var ver uint
|
||||
var dirty bool
|
||||
if m != nil {
|
||||
v, d, vErr := m.Version()
|
||||
if vErr == nil {
|
||||
versionKnown = true
|
||||
ver, dirty = v, d
|
||||
}
|
||||
}
|
||||
setMigrationState(ver, dirty, err.Error(), versionKnown)
|
||||
return err
|
||||
}
|
||||
|
||||
// RunMigrations executes all pending database migrations
|
||||
@@ -71,25 +113,33 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
|
||||
sqlDB, err := sql.Open("sqlite3", opts.SQLiteDBPath)
|
||||
if err != nil {
|
||||
logger.Errorf(ctx, "Failed to open sqlite db for migration: %v", err)
|
||||
return fmt.Errorf("failed to open sqlite db for migration: %w", err)
|
||||
wrapped := fmt.Errorf("failed to open sqlite db for migration: %w", err)
|
||||
setMigrationState(0, false, wrapped.Error(), false)
|
||||
return wrapped
|
||||
}
|
||||
driver, err := sqlite3migrate.WithInstance(sqlDB, &sqlite3migrate.Config{})
|
||||
if err != nil {
|
||||
sqlDB.Close()
|
||||
logger.Errorf(ctx, "Failed to create sqlite3 migrate driver: %v", err)
|
||||
return fmt.Errorf("failed to create sqlite3 migrate driver: %w", err)
|
||||
wrapped := fmt.Errorf("failed to create sqlite3 migrate driver: %w", err)
|
||||
setMigrationState(0, false, wrapped.Error(), false)
|
||||
return wrapped
|
||||
}
|
||||
m, err = migrate.NewWithDatabaseInstance(migrationsPath, "sqlite3", driver)
|
||||
if err != nil {
|
||||
logger.Errorf(ctx, "Failed to create migrate instance: %v", err)
|
||||
return fmt.Errorf("failed to create migrate instance: %w", err)
|
||||
wrapped := fmt.Errorf("failed to create migrate instance: %w", err)
|
||||
setMigrationState(0, false, wrapped.Error(), false)
|
||||
return wrapped
|
||||
}
|
||||
} else {
|
||||
var err error
|
||||
m, err = migrate.New(migrationsPath, dsn)
|
||||
if err != nil {
|
||||
logger.Errorf(ctx, "Failed to create migrate instance: %v", err)
|
||||
return fmt.Errorf("failed to create migrate instance: %w", err)
|
||||
wrapped := fmt.Errorf("failed to create migrate instance: %w", err)
|
||||
setMigrationState(0, false, wrapped.Error(), false)
|
||||
return wrapped
|
||||
}
|
||||
}
|
||||
defer m.Close()
|
||||
@@ -98,7 +148,7 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
|
||||
oldVersion, oldDirty, versionErr := m.Version()
|
||||
if versionErr != nil && versionErr != migrate.ErrNilVersion {
|
||||
logger.Errorf(ctx, "Failed to get migration version: %v", versionErr)
|
||||
return fmt.Errorf("failed to get migration version: %w", versionErr)
|
||||
return captureMigrationFailure(m, fmt.Errorf("failed to get migration version: %w", versionErr))
|
||||
}
|
||||
|
||||
if versionErr == migrate.ErrNilVersion {
|
||||
@@ -113,7 +163,7 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
|
||||
if opts.AutoRecoverDirty {
|
||||
logger.Infof(ctx, "AutoRecoverDirty is enabled, attempting recovery...")
|
||||
if err := recoverFromDirtyState(ctx, m, oldVersion); err != nil {
|
||||
return err
|
||||
return captureMigrationFailure(m, err)
|
||||
}
|
||||
// Update oldVersion after recovery
|
||||
oldVersion, _, _ = m.Version()
|
||||
@@ -123,7 +173,7 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
|
||||
if oldVersion == 0 || forceVersion < 0 {
|
||||
forceVersion = 0
|
||||
}
|
||||
return fmt.Errorf(
|
||||
return captureMigrationFailure(m, fmt.Errorf(
|
||||
"database is in dirty state at version %d. This usually means a migration failed partway through. "+
|
||||
"To fix this:\n"+
|
||||
"1. Check if the migration partially applied changes and manually fix if needed\n"+
|
||||
@@ -136,7 +186,7 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
|
||||
forceVersion,
|
||||
forceVersion,
|
||||
forceVersion,
|
||||
)
|
||||
))
|
||||
}
|
||||
}
|
||||
|
||||
@@ -152,13 +202,13 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
|
||||
logger.Infof(ctx, "Attempting to recover from dirty state...")
|
||||
// Try to recover and retry
|
||||
if recoverErr := recoverFromDirtyState(ctx, m, currentVersion); recoverErr != nil {
|
||||
return recoverErr
|
||||
return captureMigrationFailure(m, recoverErr)
|
||||
}
|
||||
// Retry migration after recovery
|
||||
logger.Infof(ctx, "Retrying migration after recovery...")
|
||||
if retryErr := m.Up(); retryErr != nil && retryErr != migrate.ErrNoChange {
|
||||
logger.Errorf(ctx, "Migration failed after recovery attempt: %v", retryErr)
|
||||
return fmt.Errorf("migration failed after recovery attempt: %w", retryErr)
|
||||
return captureMigrationFailure(m, fmt.Errorf("migration failed after recovery attempt: %w", retryErr))
|
||||
}
|
||||
} else {
|
||||
// Calculate the version to force to (usually the previous version)
|
||||
@@ -166,7 +216,7 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
|
||||
if currentVersion == 0 {
|
||||
forceVersion = 0
|
||||
}
|
||||
return fmt.Errorf(
|
||||
return captureMigrationFailure(m, fmt.Errorf(
|
||||
"migration failed and database is now in dirty state at version %d. "+
|
||||
"To fix this:\n"+
|
||||
"1. Check if the migration partially applied changes and manually fix if needed\n"+
|
||||
@@ -179,20 +229,20 @@ func RunMigrationsWithOptions(dsn string, opts MigrationOptions) error {
|
||||
forceVersion,
|
||||
forceVersion,
|
||||
forceVersion,
|
||||
)
|
||||
))
|
||||
}
|
||||
} else {
|
||||
return fmt.Errorf("failed to run migrations: %w", err)
|
||||
return captureMigrationFailure(m, fmt.Errorf("failed to run migrations: %w", err))
|
||||
}
|
||||
}
|
||||
|
||||
// Get current version after migration
|
||||
version, dirty, err := m.Version()
|
||||
if err != nil && err != migrate.ErrNilVersion {
|
||||
return fmt.Errorf("failed to get migration version: %w", err)
|
||||
return captureMigrationFailure(m, fmt.Errorf("failed to get migration version: %w", err))
|
||||
}
|
||||
|
||||
setMigrationVersion(version, dirty)
|
||||
setMigrationState(version, dirty, "", true)
|
||||
|
||||
if oldVersion != version {
|
||||
logger.Infof(ctx, "Database migrated from version %d to %d", oldVersion, version)
|
||||
|
||||
Reference in New Issue
Block a user