fix(database): run column migrations before index creation

- Reorder Migrate() to add columns to existing tables BEFORE creating
  indexes, since CREATE TABLE IF NOT EXISTS is a no-op on existing
  databases and some indexes (e.g. finding_hash) reference migrated
  columns that would otherwise be missing
- Add explanatory comment in internal/database/database.go documenting
  why column migrations must precede index creation
- Surface a helpful CLI hint in pkg/cli/root.go pointing users to
  'osmedeus db migrate' when startup fails with 'failed to run
  migrations', so stale schemas are easier to recover from

Author: j3ssie

internal/database/database.go

@@ -202,45 +202,10 @@ func Migrate(ctx context.Context) error {
 		}
 	}
 
-	// Create indexes for Run table
-	if err := createRunIndexes(ctx); err != nil {
-		return err
-	}
-
-	// Create indexes for Asset table
-	if err := createAssetIndexes(ctx); err != nil {
-		return err
-	}
-
-	// Create indexes for EventLog table
-	if err := createEventLogIndexes(ctx); err != nil {
-		return err
-	}
-
-	// Create indexes for WorkflowMeta table
-	if err := createWorkflowMetaIndexes(ctx); err != nil {
-		return err
-	}
-
-	// Create indexes for Vulnerability table
-	if err := createVulnerabilityIndexes(ctx); err != nil {
-		return err
-	}
-
-	// Create indexes for Workspace table
-	if err := createWorkspaceIndexes(ctx); err != nil {
-		return err
-	}
-
-	// Create indexes for AssetDiffSnapshot table
-	if err := createAssetDiffIndexes(ctx); err != nil {
-		return err
-	}
-
-	// Create indexes for VulnDiffSnapshot table
-	if err := createVulnDiffIndexes(ctx); err != nil {
-		return err
-	}
+	// Add columns to existing tables BEFORE creating indexes. CREATE TABLE
+	// IF NOT EXISTS is a no-op for existing databases, so their tables retain
+	// the old schema. Some indexes below reference migrated columns (e.g.
+	// finding_hash), so the columns must exist first or index creation fails.
 
 	// Add current_pid column to runs table if it doesn't exist (for existing databases)
 	if err := addRunsPIDColumn(ctx); err != nil {
@@ -307,6 +272,46 @@ func Migrate(ctx context.Context) error {
 		return err
 	}
 
+	// Create indexes for Run table
+	if err := createRunIndexes(ctx); err != nil {
+		return err
+	}
+
+	// Create indexes for Asset table
+	if err := createAssetIndexes(ctx); err != nil {
+		return err
+	}
+
+	// Create indexes for EventLog table
+	if err := createEventLogIndexes(ctx); err != nil {
+		return err
+	}
+
+	// Create indexes for WorkflowMeta table
+	if err := createWorkflowMetaIndexes(ctx); err != nil {
+		return err
+	}
+
+	// Create indexes for Vulnerability table
+	if err := createVulnerabilityIndexes(ctx); err != nil {
+		return err
+	}
+
+	// Create indexes for Workspace table
+	if err := createWorkspaceIndexes(ctx); err != nil {
+		return err
+	}
+
+	// Create indexes for AssetDiffSnapshot table
+	if err := createAssetDiffIndexes(ctx); err != nil {
+		return err
+	}
+
+	// Create indexes for VulnDiffSnapshot table
+	if err := createVulnDiffIndexes(ctx); err != nil {
+		return err
+	}
+
 	return nil
 }
 

pkg/cli/root.go

@@ -261,6 +261,12 @@ func Execute() {
 		if !errors.As(err, &ttmErr) {
 			fmt.Fprintf(os.Stderr, "%s %s\n", terminal.Red("Error:"), err)
 		}
+		// Hint users toward the migration command when the DB schema is stale
+		// (e.g. an existing database missing a column added in a newer version).
+		if strings.Contains(err.Error(), "failed to run migrations") {
+			fmt.Fprintf(os.Stderr, "%s your database schema may be out of date. Run %s to migrate it (rebuild/reinstall the binary first if you just updated).\n",
+				terminal.Yellow("Hint:"), terminal.Cyan("osmedeus db migrate"))
+		}
 		os.Exit(1)
 	}
 }