go-cli-migrations-path-resolution

Answer

Root cause: resolveMigrationsPath returned the cwd-relative ./migrations default unconditionally, so helios migrate up --db sqlite from any directory without ./migrations failed with "migrations directory not found".

Fix 1 — resolveMigrationsPath (explicit flag > cwd default when valid > exeDir > exeDir/..):

// migrate.go
func resolveMigrationsPath(explicit, cwd, exeDir, driver string) (string, error) {
    if explicit != "" { // --migrations always wins
        return explicit, nil
    }
    candidates := []string{
        filepath.Join(cwd, "migrations"),          // kept only if it holds the driver migrations
        filepath.Join(exeDir, "migrations"),
        filepath.Join(exeDir, "..", "migrations"),
    }
    for _, dir := range candidates {
        if holdsDriverMigrations(dir, driver) {
            return filepath.Clean(dir), nil
        }
    }
    return "", fmt.Errorf("migrations directory not found for driver %q (tried: %s)",
        driver, strings.Join(candidates, ", "))
}

// holdsDriverMigrations: driver-qualified subdir (migrations/sqlite) wins,
// else flat .sql files in the dir; empty or wrong-driver dirs are skipped.
func holdsDriverMigrations(dir, driver string) bool {
    info, err := os.Stat(dir)
    if err != nil || !info.IsDir() {
        return false
    }
    if sub := filepath.Join(dir, driver); isDirWithSQL(sub) {
        return true
    }
    return isDirWithSQL(dir)
}

Callers pass cwd from os.Getwd() and exeDir from os.Executable() (so it also works when the binary is invoked via symlink/PATH).

Fix 2 — dialect-aware startup probe logging WARN instead of silent 500s:

// probe.go
func schemaMigrationsProbe(driver string) string {
    switch driver {
    case "sqlite":
        return `SELECT 1 FROM sqlite_master WHERE type='table' AND name='schema_migrations'`
    case "postgres", "pgx":
        return `SELECT 1 FROM information_schema.tables WHERE table_schema = current_schema() AND table_name = 'schema_migrations'`
    case "mysql":
        return `SELECT 1 FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = 'schema_migrations'`
    default:
        return ""
    }
}

func startMigrationProbe(db *sql.DB, driver, dsn string) error {
    migrated, err := probeMigrationState(db, driver)
    if err != nil {
        return fmt.Errorf("startup migration probe for %q: %w", driver, err)
    }
    if !migrated {
        log.Printf("WARN: database %q (%s) has no schema_migrations table; run 'helios migrate up --db %s' before serving traffic", dsn, driver, driver)
        return nil
    }
    log.Printf("startup migration probe OK: schema_migrations present for %q", driver)
    return nil
}

Migrations are applied transactionally with a schema_migrations(version, name, applied_at) tracking table, so re-runs are idempotent (applied 0/25).