feat: Add database migrations for smooth version upgrades (#344)

## Summary

Implements a comprehensive database migration system to ensure smooth
CLI version upgrades without breaking existing databases.

### Key Features

- ✅ Automatic migration on database initialization
- ✅ Version tracking with `schema_migrations` table
- ✅ Transaction-based migrations (atomic all-or-nothing)
- ✅ Support for SQLite and PostgreSQL
- ✅ `infer migrate` command with status checking
- ✅ Integration with `infer init --overwrite`
- ✅ Comprehensive tests and documentation

## Changes

- Created migration infrastructure in
`internal/infra/storage/migrations/`
- Added `infer migrate` command for manual migration control
- Integrated automatic migrations into storage initialization
- Added complete documentation in `docs/database-migrations.md`
- Created initial migrations for SQLite and PostgreSQL

## Testing

- All existing tests pass
- 6 new migration tests added and passing
- Manual testing completed successfully

Fixes #340

---

🤖 Generated with [Claude Code](https://claude.ai/code)

---------

Signed-off-by: Eden Reich <[email protected]>
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Co-authored-by: Eden Reich <[email protected]>

Author: edenreich

.infer/.gitignore

@@ -2,7 +2,7 @@
 logs/*.log
 history
 chat_export_*
-conversations.db
+conversations.db*
 conversations
 bin/
 tmp/

cmd/init.go

@@ -30,12 +30,14 @@ This is the recommended command to start working with Inference Gateway CLI in a
 func init() {
 	initCmd.Flags().Bool("overwrite", false, "Overwrite existing files if they already exist")
 	initCmd.Flags().Bool("userspace", false, "Initialize configuration in user home directory (~/.infer/)")
+	initCmd.Flags().Bool("skip-migrations", false, "Skip running database migrations")
 	rootCmd.AddCommand(initCmd)
 }
 
 func initializeProject(cmd *cobra.Command) error {
 	overwrite, _ := cmd.Flags().GetBool("overwrite")
 	userspace, _ := cmd.Flags().GetBool("userspace")
+	skipMigrations, _ := cmd.Flags().GetBool("skip-migrations")
 
 	var configPath, gitignorePath, scmShortcutsPath, gitShortcutsPath, mcpShortcutsPath, shellsShortcutsPath, exportShortcutsPath, a2aShortcutsPath, mcpPath string
 
@@ -79,7 +81,7 @@ func initializeProject(cmd *cobra.Command) error {
 logs/*.log
 history
 chat_export_*
-conversations.db
+conversations.db*
 conversations
 bin/
 tmp/
@@ -148,6 +150,17 @@ tmp/
 	fmt.Println("")
 	fmt.Println("Tip: Use /init in chat mode to generate an AGENTS.md file interactively")
 
+	if !skipMigrations {
+		fmt.Println("")
+		fmt.Println("Running database migrations...")
+		if err := runMigrations(); err != nil {
+			fmt.Printf("%s Warning: Failed to run migrations: %v\n", icons.CrossMarkStyle.Render(icons.CrossMark), err)
+			fmt.Println("   You can run migrations manually with: infer migrate")
+		} else {
+			fmt.Printf("%s Database migrations completed successfully\n", icons.CheckMarkStyle.Render(icons.CheckMark))
+		}
+	}
+
 	return nil
 }
 

cmd/init_test.go

@@ -20,8 +20,9 @@ func TestInitializeProject(t *testing.T) {
 		{
 			name: "basic project initialization",
 			flags: map[string]any{
-				"overwrite": false,
-				"userspace": false,
+				"overwrite":       false,
+				"userspace":       false,
+				"skip-migrations": true,
 			},
 			wantFiles:   []string{".infer/config.yaml", ".infer/.gitignore"},
 			wantNoFiles: []string{"AGENTS.md"},
@@ -30,8 +31,9 @@ func TestInitializeProject(t *testing.T) {
 		{
 			name: "userspace initialization",
 			flags: map[string]any{
-				"overwrite": true,
-				"userspace": true,
+				"overwrite":       true,
+				"userspace":       true,
+				"skip-migrations": true,
 			},
 			wantFiles:   []string{},
 			wantNoFiles: []string{".infer/config.yaml", ".infer/.gitignore", "AGENTS.md"},

cmd/migrate.go

@@ -0,0 +1,176 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	container "github.com/inference-gateway/cli/internal/container"
+	storage "github.com/inference-gateway/cli/internal/infra/storage"
+	migrations "github.com/inference-gateway/cli/internal/infra/storage/migrations"
+	icons "github.com/inference-gateway/cli/internal/ui/styles/icons"
+	cobra "github.com/spf13/cobra"
+)
+
+var migrateCmd = &cobra.Command{
+	Use:   "migrate",
+	Short: "Run database migrations",
+	Long: `Run database migrations to update the schema to the latest version.
+
+This command applies any pending migrations to your database. Migrations are tracked
+in the schema_migrations table to ensure they are only applied once.
+
+The command automatically detects your database backend (SQLite, PostgreSQL, JSONL, Redis, Memory)
+and applies the appropriate migrations. Note that JSONL, Redis, and Memory storage backends
+do not require migrations as they do not use a relational schema.`,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		status, _ := cmd.Flags().GetBool("status")
+		if status {
+			return showMigrationStatus()
+		}
+		return runMigrations()
+	},
+}
+
+func init() {
+	migrateCmd.Flags().Bool("status", false, "Show migration status without applying migrations")
+	rootCmd.AddCommand(migrateCmd)
+}
+
+// runMigrations executes pending database migrations
+func runMigrations() error {
+	cfg, err := getConfigFromViper()
+	if err != nil {
+		return fmt.Errorf("failed to get config: %w", err)
+	}
+
+	serviceContainer := container.NewServiceContainer(cfg, V)
+
+	conversationStorage := serviceContainer.GetStorage()
+
+	defer func() {
+		if err := conversationStorage.Close(); err != nil {
+			fmt.Fprintf(os.Stderr, "Warning: failed to close storage: %v\n", err)
+		}
+	}()
+
+	switch conversationStorage.(type) {
+	case *storage.SQLiteStorage:
+		fmt.Printf("%s SQLite database migrations are up to date\n", icons.CheckMarkStyle.Render(icons.CheckMark))
+		fmt.Println("   All migrations have been applied automatically")
+		return nil
+	case *storage.PostgresStorage:
+		fmt.Printf("%s PostgreSQL database migrations are up to date\n", icons.CheckMarkStyle.Render(icons.CheckMark))
+		fmt.Println("   All migrations have been applied automatically")
+		return nil
+	case *storage.JsonlStorage:
+		fmt.Println("JSONL storage does not require migrations")
+		return nil
+	case *storage.MemoryStorage:
+		fmt.Println("Memory storage does not require migrations")
+		return nil
+	case *storage.RedisStorage:
+		fmt.Println("Redis storage does not require migrations")
+		return nil
+	default:
+		return fmt.Errorf("unsupported storage backend: %T", conversationStorage)
+	}
+}
+
+// showMigrationStatus displays the current migration status
+func showMigrationStatus() error {
+	cfg, err := getConfigFromViper()
+	if err != nil {
+		return fmt.Errorf("failed to get config: %w", err)
+	}
+
+	serviceContainer := container.NewServiceContainer(cfg, V)
+
+	conversationStorage := serviceContainer.GetStorage()
+
+	defer func() {
+		if err := conversationStorage.Close(); err != nil {
+			fmt.Fprintf(os.Stderr, "Warning: failed to close storage: %v\n", err)
+		}
+	}()
+
+	switch s := conversationStorage.(type) {
+	case *storage.SQLiteStorage:
+		return showSQLiteMigrationStatus(s)
+	case *storage.PostgresStorage:
+		return showPostgresMigrationStatus(s)
+	case *storage.JsonlStorage:
+		fmt.Println("JSONL storage does not require migrations")
+		return nil
+	case *storage.MemoryStorage:
+		fmt.Println("Memory storage does not require migrations")
+		return nil
+	case *storage.RedisStorage:
+		fmt.Println("Redis storage does not require migrations")
+		return nil
+	default:
+		return fmt.Errorf("unsupported storage backend: %T", s)
+	}
+}
+
+// showSQLiteMigrationStatus shows migration status for SQLite
+func showSQLiteMigrationStatus(s *storage.SQLiteStorage) error {
+	ctx := context.Background()
+	db := s.DB()
+	if db == nil {
+		return fmt.Errorf("database connection is nil")
+	}
+
+	runner := migrations.NewMigrationRunner(db, "sqlite")
+	allMigrations := migrations.GetSQLiteMigrations()
+
+	status, err := runner.GetMigrationStatus(ctx, allMigrations)
+	if err != nil {
+		return fmt.Errorf("failed to get migration status: %w", err)
+	}
+
+	fmt.Println("SQLite Migration Status:")
+	fmt.Println()
+	for _, s := range status {
+		statusIcon := icons.StyledCrossMark()
+		statusText := "Pending"
+		if s.Applied {
+			statusIcon = icons.StyledCheckMark()
+			statusText = "Applied"
+		}
+		fmt.Printf("  %s Version %s: %s (%s)\n", statusIcon, s.Version, s.Description, statusText)
+	}
+
+	return nil
+}
+
+// showPostgresMigrationStatus shows migration status for PostgreSQL
+func showPostgresMigrationStatus(s *storage.PostgresStorage) error {
+	ctx := context.Background()
+	db := s.DB()
+	if db == nil {
+		return fmt.Errorf("database connection is nil")
+	}
+
+	runner := migrations.NewMigrationRunner(db, "postgres")
+	allMigrations := migrations.GetPostgresMigrations()
+
+	status, err := runner.GetMigrationStatus(ctx, allMigrations)
+	if err != nil {
+		return fmt.Errorf("failed to get migration status: %w", err)
+	}
+
+	fmt.Println("PostgreSQL Migration Status:")
+	fmt.Println()
+	for _, s := range status {
+		statusIcon := icons.StyledCrossMark()
+		statusText := "Pending"
+		if s.Applied {
+			statusIcon = icons.StyledCheckMark()
+			statusText = "Applied"
+		}
+		fmt.Printf("  %s Version %s: %s (%s)\n", statusIcon, s.Version, s.Description, statusText)
+	}
+
+	return nil
+}