Move schema_migrations table creation from Go code into 000.sql

The schema_migrations table definition now lives in
internal/database/schema/000.sql instead of being hardcoded as an
inline SQL string in database.go. A bootstrap step checks
sqlite_master for the table and applies 000.sql when it is missing.
Existing databases that already have the table (created by older
inline code) get version 000 back-filled so the normal migration
loop skips the file.

Also deduplicates the migration logic: both the Database.runMigrations
method and the exported ApplyMigrations helper now delegate to a single
applyMigrations function.

Adds database_test.go with tests for fresh migration, idempotency,
bootstrap on a fresh DB, and backwards compatibility with legacy DBs.

internal/database/database.go

@@ -21,6 +21,10 @@ import (
 //go:embed schema/*.sql
 var schemaFS embed.FS
 
+// bootstrapVersion is the migration that creates the schema_migrations
+// table itself. It is applied before the normal migration loop.
+const bootstrapVersion = "000"
+
 // Params defines dependencies for Database.
 type Params struct {
 	fx.In
@@ -84,43 +88,36 @@ func (s *Database) connect(ctx context.Context) error {
 	s.db = db
 	s.log.Info("database connected")
 
-	return s.runMigrations(ctx)
+	return applyMigrations(ctx, s.db, s.log)
 }
 
-func (s *Database) runMigrations(ctx context.Context) error {
-	// Create migrations tracking table
-	_, err := s.db.ExecContext(ctx, `
-		CREATE TABLE IF NOT EXISTS schema_migrations (
-			version TEXT PRIMARY KEY,
-			applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
-		)
-	`)
-	if err != nil {
-		return fmt.Errorf("failed to create migrations table: %w", err)
+// applyMigrations bootstraps the migrations table from 000.sql and then
+// applies every remaining migration that has not been recorded yet.
+func applyMigrations(ctx context.Context, db *sql.DB, log *slog.Logger) error {
+	if err := bootstrapMigrationsTable(ctx, db, log); err != nil {
+		return err
 	}
 
-	// Get list of migration files
 	entries, err := schemaFS.ReadDir("schema")
 	if err != nil {
 		return fmt.Errorf("failed to read schema directory: %w", err)
 	}
 
-	// Sort migration files by name (001.sql, 002.sql, etc.)
 	var migrations []string
 	for _, entry := range entries {
 		if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".sql") {
 			migrations = append(migrations, entry.Name())
 		}
 	}
+
 	sort.Strings(migrations)
 
-	// Apply each migration that hasn't been applied yet
 	for _, migration := range migrations {
 		version := strings.TrimSuffix(migration, filepath.Ext(migration))
 
-		// Check if already applied
 		var count int
-		err := s.db.QueryRowContext(ctx,
+
+		err := db.QueryRowContext(ctx,
 			"SELECT COUNT(*) FROM schema_migrations WHERE version = ?",
 			version,
 		).Scan(&count)
@@ -129,26 +126,24 @@ func (s *Database) runMigrations(ctx context.Context) error {
 		}
 
 		if count > 0 {
-			s.log.Debug("migration already applied", "version", version)
+			logDebug(log, "migration already applied", "version", version)
 
 			continue
 		}
 
-		// Read and apply migration
 		content, err := schemaFS.ReadFile(filepath.Join("schema", migration))
 		if err != nil {
 			return fmt.Errorf("failed to read migration %s: %w", migration, err)
 		}
 
-		s.log.Info("applying migration", "version", version)
+		logInfo(log, "applying migration", "version", version)
 
-		_, err = s.db.ExecContext(ctx, string(content))
+		_, err = db.ExecContext(ctx, string(content))
 		if err != nil {
 			return fmt.Errorf("failed to apply migration %s: %w", migration, err)
 		}
 
-		// Record migration as applied
-		_, err = s.db.ExecContext(ctx,
+		_, err = db.ExecContext(ctx,
 			"INSERT INTO schema_migrations (version) VALUES (?)",
 			version,
 		)
@@ -156,12 +151,81 @@ func (s *Database) runMigrations(ctx context.Context) error {
 			return fmt.Errorf("failed to record migration %s: %w", migration, err)
 		}
 
-		s.log.Info("migration applied successfully", "version", version)
+		logInfo(log, "migration applied successfully", "version", version)
 	}
 
 	return nil
 }
 
+// bootstrapMigrationsTable ensures the schema_migrations table exists
+// by applying 000.sql directly. For databases that already have the
+// table (created by older code), it records version "000" for
+// consistency.
+func bootstrapMigrationsTable(ctx context.Context, db *sql.DB, log *slog.Logger) error {
+	var tableExists int
+
+	err := db.QueryRowContext(ctx,
+		"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='schema_migrations'",
+	).Scan(&tableExists)
+	if err != nil {
+		return fmt.Errorf("failed to check for migrations table: %w", err)
+	}
+
+	if tableExists > 0 {
+		// Table already exists (from older inline-SQL code or a
+		// previous run). Make sure version "000" is recorded so the
+		// normal loop skips the bootstrap file.
+		var recorded int
+
+		err := db.QueryRowContext(ctx,
+			"SELECT COUNT(*) FROM schema_migrations WHERE version = ?",
+			bootstrapVersion,
+		).Scan(&recorded)
+		if err != nil {
+			return fmt.Errorf("failed to check bootstrap migration status: %w", err)
+		}
+
+		if recorded == 0 {
+			_, err = db.ExecContext(ctx,
+				"INSERT INTO schema_migrations (version) VALUES (?)",
+				bootstrapVersion,
+			)
+			if err != nil {
+				return fmt.Errorf("failed to record bootstrap migration: %w", err)
+			}
+
+			logInfo(log, "recorded bootstrap migration for existing table", "version", bootstrapVersion)
+		}
+
+		return nil
+	}
+
+	// Table does not exist — apply 000.sql to create it.
+	content, err := schemaFS.ReadFile("schema/000.sql")
+	if err != nil {
+		return fmt.Errorf("failed to read bootstrap migration 000.sql: %w", err)
+	}
+
+	logInfo(log, "applying bootstrap migration", "version", bootstrapVersion)
+
+	_, err = db.ExecContext(ctx, string(content))
+	if err != nil {
+		return fmt.Errorf("failed to apply bootstrap migration: %w", err)
+	}
+
+	_, err = db.ExecContext(ctx,
+		"INSERT INTO schema_migrations (version) VALUES (?)",
+		bootstrapVersion,
+	)
+	if err != nil {
+		return fmt.Errorf("failed to record bootstrap migration: %w", err)
+	}
+
+	logInfo(log, "bootstrap migration applied successfully", "version", bootstrapVersion)
+
+	return nil
+}
+
 // DB returns the underlying sql.DB.
 func (s *Database) DB() *sql.DB {
 	return s.db
@@ -171,72 +235,19 @@ func (s *Database) DB() *sql.DB {
 // This is useful for testing where you want to use the real schema
 // without the full fx lifecycle.
 func ApplyMigrations(db *sql.DB) error {
-	ctx := context.Background()
-
-	// Create migrations tracking table
-	_, err := db.ExecContext(ctx, `
-		CREATE TABLE IF NOT EXISTS schema_migrations (
-			version TEXT PRIMARY KEY,
-			applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
-		)
-	`)
-	if err != nil {
-		return fmt.Errorf("failed to create migrations table: %w", err)
-	}
-
-	// Get list of migration files
-	entries, err := schemaFS.ReadDir("schema")
-	if err != nil {
-		return fmt.Errorf("failed to read schema directory: %w", err)
-	}
-
-	// Sort migration files by name (001.sql, 002.sql, etc.)
-	var migrations []string
-	for _, entry := range entries {
-		if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".sql") {
-			migrations = append(migrations, entry.Name())
-		}
-	}
-	sort.Strings(migrations)
-
-	// Apply each migration that hasn't been applied yet
-	for _, migration := range migrations {
-		version := strings.TrimSuffix(migration, filepath.Ext(migration))
-
-		// Check if already applied
-		var count int
-		err := db.QueryRowContext(ctx,
-			"SELECT COUNT(*) FROM schema_migrations WHERE version = ?",
-			version,
-		).Scan(&count)
-		if err != nil {
-			return fmt.Errorf("failed to check migration status: %w", err)
-		}
-
-		if count > 0 {
-			continue
-		}
-
-		// Read and apply migration
-		content, err := schemaFS.ReadFile(filepath.Join("schema", migration))
-		if err != nil {
-			return fmt.Errorf("failed to read migration %s: %w", migration, err)
-		}
-
-		_, err = db.ExecContext(ctx, string(content))
-		if err != nil {
-			return fmt.Errorf("failed to apply migration %s: %w", migration, err)
-		}
-
-		// Record migration as applied
-		_, err = db.ExecContext(ctx,
-			"INSERT INTO schema_migrations (version) VALUES (?)",
-			version,
-		)
-		if err != nil {
-			return fmt.Errorf("failed to record migration %s: %w", migration, err)
-		}
-	}
-
-	return nil
+	return applyMigrations(context.Background(), db, nil)
+}
+
+// logInfo logs at info level when a logger is available.
+func logInfo(log *slog.Logger, msg string, args ...any) {
+	if log != nil {
+		log.Info(msg, args...)
+	}
+}
+
+// logDebug logs at debug level when a logger is available.
+func logDebug(log *slog.Logger, msg string, args ...any) {
+	if log != nil {
+		log.Debug(msg, args...)
+	}
 }