diff --git a/go.mod b/go.mod index 07ef045..28083ae 100644 --- a/go.mod +++ b/go.mod @@ -1,3 +1,32 @@ module gitea.auvem.com/go-toolkit/migrate go 1.24.0 + +require ( + gitea.auvem.com/go-toolkit/app v0.0.0-20250530224140-b760b035b4d1 + gitea.auvem.com/go-toolkit/dbx v0.0.0-20250530232843-55cc3ffd8364 + github.com/pressly/goose/v3 v3.24.3 +) + +require ( + filippo.io/edwards25519 v1.1.0 // indirect + github.com/davecgh/go-spew v1.1.1 // indirect + github.com/fatih/color v1.18.0 // indirect + github.com/go-jet/jet/v2 v2.13.0 // indirect + github.com/go-sql-driver/mysql v1.9.2 // indirect + github.com/google/uuid v1.6.0 // indirect + github.com/kr/text v0.2.0 // indirect + github.com/mattn/go-colorable v0.1.13 // indirect + github.com/mattn/go-isatty v0.0.20 // indirect + github.com/mfridman/interpolate v0.0.2 // indirect + github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e // indirect + github.com/pmezard/go-difflib v1.0.0 // indirect + github.com/segmentio/ksuid v1.0.4 // indirect + github.com/sethvargo/go-retry v0.3.0 // indirect + github.com/stretchr/testify v1.10.0 // indirect + go.uber.org/multierr v1.11.0 // indirect + golang.org/x/sync v0.14.0 // indirect + golang.org/x/sys v0.33.0 // indirect + gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f // indirect + gopkg.in/yaml.v3 v3.0.1 // indirect +) diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..426c732 --- /dev/null +++ b/go.sum @@ -0,0 +1,65 @@ +filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA= +filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4= +gitea.auvem.com/go-toolkit/app v0.0.0-20250530224140-b760b035b4d1 h1:22A/8PcixfY9B+q+30aTyFUW8W4DtDIELDWP2WUdKk0= +gitea.auvem.com/go-toolkit/app v0.0.0-20250530224140-b760b035b4d1/go.mod h1:a7ENpOxndUdONE6oZ9MZAvG1ba2uq01x/LtcnDkpOj8= +gitea.auvem.com/go-toolkit/dbx v0.0.0-20250530232843-55cc3ffd8364 h1:xadjfyFYYoyy8d6AtqiNSv8OtMtav53vMpg3mVRM+10= +gitea.auvem.com/go-toolkit/dbx v0.0.0-20250530232843-55cc3ffd8364/go.mod h1:3CYeto5wVq0fcABgssDYycXGbR7ibNiN66p1HpxBdds= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY= +github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto= +github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM= +github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU= +github.com/go-jet/jet/v2 v2.13.0 h1:DcD2IJRGos+4X40IQRV6S6q9onoOfZY/GPdvU6ImZcQ= +github.com/go-jet/jet/v2 v2.13.0/go.mod h1:YhT75U1FoYAxFOObbQliHmXVYQeffkBKWT7ZilZ3zPc= +github.com/go-sql-driver/mysql v1.9.2 h1:4cNKDYQ1I84SXslGddlsrMhc8k4LeDVj6Ad6WRjiHuU= +github.com/go-sql-driver/mysql v1.9.2/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU= +github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= +github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= +github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= +github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= +github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA= +github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg= +github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM= +github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY= +github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y= +github.com/mfridman/interpolate v0.0.2 h1:pnuTK7MQIxxFz1Gr+rjSIx9u7qVjf5VOoM/u6BbAxPY= +github.com/mfridman/interpolate v0.0.2/go.mod h1:p+7uk6oE07mpE/Ik1b8EckO0O4ZXiGAfshKBWLUM9Xg= +github.com/ncruces/go-strftime v0.1.9 h1:bY0MQC28UADQmHmaF5dgpLmImcShSi2kHU9XLdhx/f4= +github.com/ncruces/go-strftime v0.1.9/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls= +github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e h1:fD57ERR4JtEqsWbfPhv4DMiApHyliiK5xCTNVSPiaAs= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/pressly/goose/v3 v3.24.3 h1:DSWWNwwggVUsYZ0X2VitiAa9sKuqtBfe+Jr9zFGwWlM= +github.com/pressly/goose/v3 v3.24.3/go.mod h1:v9zYL4xdViLHCUUJh/mhjnm6JrK7Eul8AS93IxiZM4E= +github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE= +github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo= +github.com/segmentio/ksuid v1.0.4 h1:sBo2BdShXjmcugAMwjugoGUdUV0pcxY5mW4xKRn3v4c= +github.com/segmentio/ksuid v1.0.4/go.mod h1:/XUiZBD3kVx5SmUOl55voK5yeAbBNNIed+2O73XgrPE= +github.com/sethvargo/go-retry v0.3.0 h1:EEt31A35QhrcRZtrYFDTBg91cqZVnFL2navjDrah2SE= +github.com/sethvargo/go-retry v0.3.0/go.mod h1:mNX17F0C/HguQMyMyJxcnU471gOZGxCLyYaFyAZraas= +github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= +github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= +go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0= +go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y= +golang.org/x/exp v0.0.0-20250506013437-ce4c2cf36ca6 h1:y5zboxd6LQAqYIhHnB48p0ByQ/GnQx2BE33L8BOHQkI= +golang.org/x/exp v0.0.0-20250506013437-ce4c2cf36ca6/go.mod h1:U6Lno4MTRCDY+Ba7aCcauB9T60gsv5s4ralQzP72ZoQ= +golang.org/x/sync v0.14.0 h1:woo0S4Yywslg6hp4eUFjTVOyKt0RookbpAHG4c1HmhQ= +golang.org/x/sync v0.14.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA= +golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.33.0 h1:q3i8TbbEz+JRD9ywIRlyRAQbM0qF7hu24q3teo2hbuw= +golang.org/x/sys v0.33.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f h1:BLraFXnmrev5lT+xlilqcH8XK9/i0At2xKjWk4p6zsU= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +modernc.org/libc v1.65.0 h1:e183gLDnAp9VJh6gWKdTy0CThL9Pt7MfcR/0bgb7Y1Y= +modernc.org/libc v1.65.0/go.mod h1:7m9VzGq7APssBTydds2zBcxGREwvIGpuUBaKTXdm2Qs= +modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU= +modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg= +modernc.org/memory v1.10.0 h1:fzumd51yQ1DxcOxSO+S6X7+QTuVU+n8/Aj7swYjFfC4= +modernc.org/memory v1.10.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw= +modernc.org/sqlite v1.37.0 h1:s1TMe7T3Q3ovQiK2Ouz4Jwh7dw4ZDqbebSDTlSJdfjI= +modernc.org/sqlite v1.37.0/go.mod h1:5YiWv+YviqGMuGw4V+PNplcyaJ5v+vQd7TQOgkACoJM= diff --git a/migrate.go b/migrate.go new file mode 100644 index 0000000..8cdba97 --- /dev/null +++ b/migrate.go @@ -0,0 +1,15 @@ +package migrate + +const ( + // ModuleMigrationsName is the name of the migrations module. + ModuleMigrationsName = "migrations" + + // ModuleMigrateUpName is the name of the migrate up module. + ModuleMigrateUpName = "migrate up" + + // ModuleMigrateBlankName is the name of the migrate blank module. + ModuleMigrateBlankName = "migrate down to blank" + + // ModuleAutoMigrateName is the name of the auto-migrate module. + ModuleAutoMigrateName = "auto migrate" +) diff --git a/migrations.go b/migrations.go new file mode 100644 index 0000000..69edfc4 --- /dev/null +++ b/migrations.go @@ -0,0 +1,247 @@ +package migrate + +import ( + "context" + "io/fs" + "log/slog" + "time" + + "gitea.auvem.com/go-toolkit/app" + "gitea.auvem.com/go-toolkit/dbx" + "github.com/pressly/goose/v3" +) + +// MigrationsOpts define the options for the migrations module. +type MigrationOpts struct { + // FS is the filesystem where migration files are stored. + FS fs.FS + + // BasePath is the directory path where migration files are located. + // Defaults to "." if not set. + BasePath string +} + +var ( + // Migration stores the goose migration provider. + Migration *goose.Provider + + // migrationsConfig stores the configuration for the migrations module. + migrationsConfig MigrationOpts + + // migrationsModule is the singleton module instance for the migrations subsystem. + migrationsModule *app.Module + + // ModuleMigrateUp applies any pending migrations. + ModuleMigrateUp = app.NewModule(ModuleMigrateUpName, app.ModuleOpts{ + Setup: func() error { + _, err := ApplyPendingMigrations(context.Background(), -1) + return err + }, + Depends: []string{ModuleMigrationsName}, + }) + + // ModuleMigrateBlank resets the database to a blank state, removing all data. + ModuleMigrateBlank = app.NewModule(ModuleMigrateBlankName, app.ModuleOpts{ + Setup: func() error { + _, err := MigrateToBlank() + return err + }, + Depends: []string{ModuleMigrationsName}, + }) + + // autoMigrateEnabled controls whether auto-migration is enabled. + autoMigrateEnabled bool + + // autoMigrateModule is the singleton module instance for the auto-migration subsystem. + autoMigrateModule *app.Module +) + +// MigrationsConfig returns the current configuration for the migrations module. +func MigrationsConfig() MigrationOpts { + migrationsModule.RequireLoaded() // ensure the migrations module is loaded + return migrationsConfig +} + +// ModuleMigrations returns the migrations module with the provided configuration. +func ModuleMigrations(cfg MigrationOpts) *app.Module { + if migrationsModule != nil { + panic("ModuleMigrations initialized multiple times") + } + + if cfg.BasePath == "" { + cfg.BasePath = "." // default base path if not set + } + if cfg.FS == nil { + panic("Migration filesystem (FS) must be set in the configuration") + } + + migrationsConfig = cfg // store configuration at package level + + migrationsModule = app.NewModule(ModuleMigrationsName, app.ModuleOpts{ + Setup: setupMigrations, + Depends: []string{dbx.ModuleDBName}, + }) + + return migrationsModule +} + +// ModuleAutoMigrate returns the auto-migration module with the provided configuration. +func ModuleAutoMigrate(enabled bool) *app.Module { + if autoMigrateModule != nil { + panic("ModuleAutoMigrate initialized multiple times") + } + + autoMigrateEnabled = enabled // store auto-migration state at package level + + autoMigrateModule = app.NewModule(ModuleAutoMigrateName, app.ModuleOpts{ + Setup: AutoMigrate, + Depends: []string{ModuleMigrationsName}, + }) + + return autoMigrateModule +} + +// setupMigrations initializes the goose migration provider. +func setupMigrations() error { + var err error + + if err := goose.SetDialect("mysql"); err != nil { + slog.Error("Couldn't set database dialect for goose", "err", err) + return err + } + + // Initialize the goose migration provider + Migration, err = goose.NewProvider(goose.DialectMySQL, dbx.SQLO(), migrationsConfig.FS) + if err != nil { + slog.Error("Couldn't initialize goose migration provider", "err", err) + return err + } + + return nil +} + +// ApplyPendingMigrations applies all pending migrations. Returns the number of +// migrations applied and an error if any occurred. The number of migrations that +// will be applied are specified by `pendingCount`. If `pendingCount` is 0, no migrations +// are applied. If `pendingCount` is negative, the number of pending migrations +// is fetched from the database. +func ApplyPendingMigrations(ctx context.Context, pendingCount int64) (int64, error) { + migrationsModule.RequireLoaded() // ensure the migrations module is loaded + + if pendingCount == 0 { + return 0, nil + } + + if pendingCount < 0 { + curr, target, err := Migration.GetVersions(ctx) + if err != nil { + return 0, err + } + pendingCount = target - curr + } + + var count int64 + for range pendingCount { + res, err := Migration.UpByOne(ctx) + if err := handleMigrationResults(res, err); err != nil { + return count, err + } + + if res.Error == nil { + count++ + } + } + return count, nil +} + +// MigrateToBlank resets the database to a blank state, removing all data and +// running all down migrations. Returns number of migrations applied and an error +// if any occurred. +func MigrateToBlank() (int64, error) { + migrationsModule.RequireLoaded() // ensure the migrations module is loaded + + ctx := context.Background() + current, target, err := Migration.GetVersions(ctx) + if err != nil { + return 0, err + } + slog.Info("Database versions", "current", current, "target", target) + + var count int64 + for current > 0 { + res, err := Migration.Down(ctx) + if err := handleMigrationResults(res, err); err != nil { + return count, err + } + + count++ + current-- + } + return count, nil +} + +// AutoMigrate applies any pending migrations if auto-migration is enabled. +func AutoMigrate() error { + migrationsModule.RequireLoaded() // ensure the migrations module is loaded + + // Check if there are any pending migrations + migrationCtx := context.Background() + migrationCurrent, migrationTarget, err := Migration.GetVersions(migrationCtx) + if err != nil { + slog.Error("Couldn't check for pending migrations", "err", err) + return err + } + + migrationFields := []any{ + "current", migrationCurrent, + "target", migrationTarget, + } + + if migrationCurrent >= migrationTarget { + slog.Info("No pending migrations", "version", migrationCurrent) + } else if !autoMigrateEnabled { + slog.Error( + "Pending migrations detected, but auto-migration is disabled. Please run `acrm migrate up` to apply them.", + migrationFields..., + ) + return err + } else { + slog.Info("Pending migrations detected, applying them...", migrationFields...) + now := time.Now() + count, err := ApplyPendingMigrations(migrationCtx, migrationTarget-migrationCurrent) + if err != nil { + slog.Error("Couldn't apply pending migrations", "current", migrationCurrent+count, "target", migrationTarget, "err", err) + return err + } + slog.Info("Applied pending migrations", "current", migrationTarget, "appliedCount", count, "duration", time.Since(now)) + } + + return nil +} + +// handleMigrationResults is a helper function that prints various responses +// based on a *goose.MigrationResult. +func handleMigrationResults(res *goose.MigrationResult, err error) error { + if err != nil { + return err + } + + fields := []any{ + "dir", res.Direction, + "version", res.Source.Version, + "source", res.Source.Path, + "duration", res.Duration, + } + + if res.Error != nil { + fields = append(fields, "err", res.Error) + slog.Error("Couldn't apply migration", fields...) + return res.Error + } else if res.Empty { + slog.Warn("Applied empty migration", fields...) + } else { + slog.Info("Applied migration", fields...) + } + + return nil +}