pixa/internal/database/database.go

// Package database provides SQLite database access.
package database

import (
	"context"
	"database/sql"
	"errors"
	"fmt"
	"io/fs"
	"log/slog"
	"path/filepath"
	"sort"
	"strconv"
	"strings"

	"go.uber.org/fx"
	"sneak.berlin/go/pixa/internal/config"
	"sneak.berlin/go/pixa/internal/db/migrations"
	"sneak.berlin/go/pixa/internal/logger"

	_ "modernc.org/sqlite" // SQLite driver registration
)

// bootstrapVersion is the migration that creates the schema_migrations
// table itself. It is applied before the normal migration loop.
const bootstrapVersion = 0

// Params defines dependencies for Database.
type Params struct {
	fx.In

	Logger *logger.Logger
	Config *config.Config
}

// errInvalidMigrationFilename is returned when a migration filename does
// not match the "<version>[_<description>].sql" pattern.
var errInvalidMigrationFilename = errors.New("invalid migration filename")

// Database wraps the SQL database connection.
type Database struct {
	db     *sql.DB
	log    *slog.Logger
	config *config.Config
}

// ParseMigrationVersion extracts the numeric version prefix from a migration
// filename. Filenames must follow the pattern "<version>.sql" or
// "<version>_<description>.sql", where version is a zero-padded numeric
// string (e.g. "001", "002"). Returns the version as an integer and an
// error if the filename does not match the expected pattern.
func ParseMigrationVersion(filename string) (int, error) {
	name := strings.TrimSuffix(filename, filepath.Ext(filename))
	if name == "" {
		return 0, fmt.Errorf("%w %q: empty name", errInvalidMigrationFilename, filename)
	}

	// Split on underscore to separate version from description.
	// If there's no underscore, the entire stem is the version.
	versionStr, _, _ := strings.Cut(name, "_")
	if versionStr == "" {
		return 0, fmt.Errorf(
			"%w %q: empty version prefix", errInvalidMigrationFilename, filename,
		)
	}

	// Validate the version is purely numeric.
	for _, ch := range versionStr {
		if ch < '0' || ch > '9' {
			return 0, fmt.Errorf(
				"%w %q: version %q contains non-numeric character %q",
				errInvalidMigrationFilename, filename, versionStr, string(ch),
			)
		}
	}

	version, err := strconv.Atoi(versionStr)
	if err != nil {
		return 0, fmt.Errorf("%w %q: %w", errInvalidMigrationFilename, filename, err)
	}

	return version, nil
}

// New opens the database and applies the migrations, so that the parts
// fx builds after it can read the database while they are built. Its
// stop hook closes the database. fx runs stop hooks in the reverse of the
// order it built their parts in, so the stop hooks of those parts run
// before this one.
func New(lc fx.Lifecycle, params Params) (*Database, error) {
	s := &Database{
		log:    params.Logger.Get(),
		config: params.Config,
	}

	s.log.Info("Database instantiated")

	err := s.connect(context.Background())
	if err != nil {
		return nil, err
	}

	lc.Append(fx.Hook{
		OnStop: func(_ context.Context) error {
			s.log.Info("Database OnStop Hook")

			return s.db.Close()
		},
	})

	return s, nil
}

// collectMigrations reads the embedded migrations directory and returns
// migration filenames sorted lexicographically.
func collectMigrations() ([]string, error) {
	entries, err := fs.ReadDir(migrations.FS(), ".")
	if err != nil {
		return nil, fmt.Errorf("failed to read migrations directory: %w", err)
	}

	var filenames []string

	for _, entry := range entries {
		if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".sql") {
			filenames = append(filenames, entry.Name())
		}
	}

	sort.Strings(filenames)

	return filenames, nil
}

// bootstrapMigrationsTable ensures the schema_migrations table exists
// by applying 000_migration.sql if the table is missing.
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 {
		return nil
	}

	content, err := fs.ReadFile(migrations.FS(), "000_migration.sql")
	if err != nil {
		return fmt.Errorf("failed to read bootstrap migration 000_migration.sql: %w", err)
	}

	if log != nil {
		log.Info("applying bootstrap migration", "version", bootstrapVersion)
	}

	_, err = db.ExecContext(ctx, string(content))
	if err != nil {
		return fmt.Errorf("failed to apply bootstrap migration: %w", err)
	}

	return nil
}

// ApplyMigrations applies all pending migrations to db. An optional logger
// may be provided for informational output; pass nil for silent operation.
// This is exported so tests can apply the real schema without the full fx
// lifecycle.
func ApplyMigrations(ctx context.Context, db *sql.DB, log *slog.Logger) error {
	err := bootstrapMigrationsTable(ctx, db, log)
	if err != nil {
		return err
	}

	filenames, err := collectMigrations()
	if err != nil {
		return err
	}

	for _, migration := range filenames {
		version, parseErr := ParseMigrationVersion(migration)
		if parseErr != nil {
			return parseErr
		}

		// 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 {
			if log != nil {
				log.Debug("migration already applied", "version", version)
			}

			continue
		}

		// Read and apply migration.
		content, readErr := fs.ReadFile(migrations.FS(), migration)
		if readErr != nil {
			return fmt.Errorf("failed to read migration %s: %w", migration, readErr)
		}

		if log != nil {
			log.Info("applying migration", "version", version)
		}

		_, execErr := db.ExecContext(ctx, string(content))
		if execErr != nil {
			return fmt.Errorf("failed to apply migration %s: %w", migration, execErr)
		}

		// Record migration as applied.
		_, recErr := db.ExecContext(ctx,
			"INSERT INTO schema_migrations (version) VALUES (?)",
			version,
		)
		if recErr != nil {
			return fmt.Errorf("failed to record migration %s: %w", migration, recErr)
		}

		if log != nil {
			log.Info("migration applied successfully", "version", version)
		}
	}

	return nil
}

// DB returns the underlying sql.DB. It has one connection, so close any
// rows and end any transaction before running another query on it; a
// query run while they are open waits forever.
func (s *Database) DB() *sql.DB {
	return s.db
}

func (s *Database) connect(ctx context.Context) error {
	// With a busy timeout, a write that finds another program writing to
	// the same database file waits up to five seconds for it instead of
	// failing at once with "database is locked". The driver runs each
	// _pragma parameter on every connection it opens.
	separator := "?"
	if strings.Contains(s.config.DBURL, "?") {
		separator = "&"
	}

	dbURL := s.config.DBURL + separator + "_pragma=busy_timeout(5000)"

	s.log.Info("connecting to database", "url", dbURL)

	db, err := sql.Open("sqlite", dbURL)
	if err != nil {
		s.log.Error("failed to open database", "error", err)

		return err
	}

	// One connection: pixa's own reads and writes run on it one at a
	// time instead of competing for SQLite's lock, where a write that
	// keeps losing can wait past the busy timeout and be lost.
	db.SetMaxOpenConns(1)

	err = db.PingContext(ctx)
	if err != nil {
		s.log.Error("failed to ping database", "error", err)

		return err
	}

	s.db = db
	s.log.Info("database connected")

	return ApplyMigrations(ctx, s.db, s.log)
}