Skip to content

Modern Docker Management, Designed for Everyone

fix: allow rolling back migrations via ALLOW_DOWNGRADE env (#1966)

Kyle Mendellb2f5a19650c6
diff --git a/.env.example b/.env.example
index 9b2999bdb..447b6296e 100644
--- a/.env.example
+++ b/.env.example
@@ -32,6 +32,10 @@ JWT_SECRET=your-super-secret-jwt-key-change-this
# Database Configuration
DATABASE_URL=file:data/arcane.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(2500)&_txlock=immediate
+# Downgrades are blocked by default; enable only temporarily after taking a backup.
+ALLOW_DOWNGRADE=false
+# Optional: GitHub API token used for downgrade migration fetches to avoid rate limits.
+# GITHUB_TOKEN=ghp_your_token_here
# Docker Configuration
# DOCKER_HOST=unix:///var/run/docker.sock # Default: direct socket access
diff --git a/backend/go.mod b/backend/go.mod
index a52ca21a4..a20c73e17 100644
--- a/backend/go.mod
+++ b/backend/go.mod
@@ -114,6 +114,8 @@ require (
github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8 // indirect
github.com/golang/protobuf v1.5.4 // indirect
github.com/google/go-cmp v0.7.0 // indirect
+ github.com/google/go-github/v39 v39.2.0 // indirect
+ github.com/google/go-querystring v1.1.0 // indirect
github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.3 // indirect
github.com/hashicorp/errwrap v1.1.0 // indirect
diff --git a/backend/go.sum b/backend/go.sum
index fe9f41d48..cbacb14b2 100644
--- a/backend/go.sum
+++ b/backend/go.sum
@@ -250,14 +250,22 @@ github.com/golang-migrate/migrate/v4 v4.19.1 h1:OCyb44lFuQfYXYLx1SCxPZQGU7mcaZ7g
github.com/golang-migrate/migrate/v4 v4.19.1/go.mod h1:CTcgfjxhaUtsLipnLoQRWCrjYXycRz/g5+RWDuYgPrE=
github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8 h1:f+oWsMOmNPc8JmEHVZIycC7hBoQxHH9pNKQORJNozsQ=
github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8/go.mod h1:wcDNUvekVysuuOpQKo3191zZyTpiI6se1N1ULghS0sw=
+github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
github.com/google/certificate-transparency-go v1.3.2 h1:9ahSNZF2o7SYMaKaXhAumVEzXB2QaayzII9C8rv7v+A=
github.com/google/certificate-transparency-go v1.3.2/go.mod h1:H5FpMUaGa5Ab2+KCYsxg6sELw3Flkl7pGZzWdBoYLXs=
+github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
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/go-containerregistry v0.20.7 h1:24VGNpS0IwrOZ2ms2P1QE3Xa5X9p4phx0aUgzYzHW6I=
github.com/google/go-containerregistry v0.20.7/go.mod h1:Lx5LCZQjLH1QBaMPeGwsME9biPeo1lPx6lbGj/UmzgM=
+github.com/google/go-github/v39 v39.2.0 h1:rNNM311XtPOz5rDdsJXAp2o8F67X9FnROXTvto3aSnQ=
+github.com/google/go-github/v39 v39.2.0/go.mod h1:C1s8C5aCC9L+JXIYpJM5GYytdX52vC1bLvHEF1IhBrE=
+github.com/google/go-querystring v1.1.0 h1:AnCroh3fv4ZBgVIf1Iwtovgjaw/GiKJo8M8yD/fhyJ8=
+github.com/google/go-querystring v1.1.0/go.mod h1:Kcdr2DB4koayq7X8pmAG4sNG59So17icRSOU623lUBU=
github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83 h1:z2ogiKUYzX5Is6zr/vP9vJGqPwcdqsWjOt+V8J7+bTc=
github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
@@ -590,6 +598,7 @@ golang.org/x/arch v0.24.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/crypto v0.0.0-20210817164053-32db794688a5/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
golang.org/x/crypto v0.0.0-20220622213112-05595931fe9d/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
@@ -600,12 +609,15 @@ golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w=
golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190603091049-60506f45cf65/go.mod h1:HSz+uSET+XFnRR8LxR5pz3Of3rY3CfYBVs4xY44aLks=
golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
golang.org/x/net v0.0.0-20211112202133-69e39bad7dc2/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
+golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
@@ -635,6 +647,7 @@ golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9sn
golang.org/x/term v0.40.0 h1:36e4zGLqU4yhjlmxEaagx2KuYbJq3EwY8K943ZsHcvg=
golang.org/x/term v0.40.0/go.mod h1:w2P8uVp06p2iyKKuvXIm7N/y0UCRt3UfJTfZ7oOpglM=
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
@@ -653,6 +666,7 @@ golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8T
golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
+google.golang.org/appengine v1.6.7/go.mod h1:8WjMMxjGQR8xUklV/ARdw2HLXBOI7O7uCIDZVag1xfc=
google.golang.org/genproto/googleapis/api v0.0.0-20251202230838-ff82c1b0f217 h1:fCvbg86sFXwdrl5LgVcTEvNC+2txB5mgROGmRL5mrls=
google.golang.org/genproto/googleapis/api v0.0.0-20251202230838-ff82c1b0f217/go.mod h1:+rXWjjaukWZun3mLfjmVnQi18E1AsFbDN9QdJ5YXLto=
google.golang.org/genproto/googleapis/rpc v0.0.0-20251202230838-ff82c1b0f217 h1:gRkg/vSppuSQoDjxyiGfN4Upv/h/DQmIR10ZU8dh4Ww=
diff --git a/backend/internal/bootstrap/db_bootstrap.go b/backend/internal/bootstrap/db_bootstrap.go
index e4e34ad63..8a1206cd2 100644
--- a/backend/internal/bootstrap/db_bootstrap.go
+++ b/backend/internal/bootstrap/db_bootstrap.go
@@ -10,7 +10,9 @@ import (
)
func initializeDBAndMigrate(ctx context.Context, cfg *config.Config) (*database.DB, error) {
- db, err := database.Initialize(ctx, cfg.DatabaseURL)
+ db, err := database.Initialize(ctx, cfg.DatabaseURL, database.MigrationOptions{
+ AllowDowngrade: cfg.AllowDowngrade,
+ })
if err != nil {
return nil, fmt.Errorf("failed to initialize database: %w", err)
}
diff --git a/backend/internal/config/config.go b/backend/internal/config/config.go
index 356eccff9..b167e6cdd 100644
--- a/backend/internal/config/config.go
+++ b/backend/internal/config/config.go
@@ -29,6 +29,7 @@ const (
type Config struct {
AppUrl string `env:"APP_URL" default:"http://localhost:3552"`
DatabaseURL string `env:"DATABASE_URL" default:"file:data/arcane.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(2500)&_txlock=immediate" options:"file"`
+ AllowDowngrade bool `env:"ALLOW_DOWNGRADE" default:"false"`
Port string `env:"PORT" default:"3552"`
Listen string `env:"LISTEN" default:""`
TLSEnabled bool `env:"TLS_ENABLED" default:"false"`
diff --git a/backend/internal/config/config_test.go b/backend/internal/config/config_test.go
index a165520b4..557dde888 100644
--- a/backend/internal/config/config_test.go
+++ b/backend/internal/config/config_test.go
@@ -220,6 +220,25 @@ func TestConfig_OptionsToLower(t *testing.T) {
})
}
+func TestConfig_AllowDowngrade(t *testing.T) {
+ origAllowDowngrade := os.Getenv("ALLOW_DOWNGRADE")
+ defer restoreEnv("ALLOW_DOWNGRADE", origAllowDowngrade)
+
+ t.Run("defaults to false", func(t *testing.T) {
+ unsetEnv(t, "ALLOW_DOWNGRADE")
+
+ cfg := Load()
+ assert.False(t, cfg.AllowDowngrade)
+ })
+
+ t.Run("loads explicit true from env", func(t *testing.T) {
+ setEnv(t, "ALLOW_DOWNGRADE", "true")
+
+ cfg := Load()
+ assert.True(t, cfg.AllowDowngrade)
+ })
+}
+
func TestConfig_ListenAddr(t *testing.T) {
tests := []struct {
name string
diff --git a/backend/internal/database/database.go b/backend/internal/database/database.go
index 4486cf29b..739c69a3b 100644
--- a/backend/internal/database/database.go
+++ b/backend/internal/database/database.go
@@ -5,9 +5,11 @@ import (
"errors"
"fmt"
"log/slog"
+ "math"
"net/url"
"os"
"path/filepath"
+ "slices"
"strings"
"time"
@@ -16,11 +18,14 @@ import (
"github.com/golang-migrate/migrate/v4/database"
postgresMigrate "github.com/golang-migrate/migrate/v4/database/postgres"
sqliteMigrate "github.com/golang-migrate/migrate/v4/database/sqlite3"
+ "github.com/golang-migrate/migrate/v4/source"
+ _ "github.com/golang-migrate/migrate/v4/source/github"
"github.com/golang-migrate/migrate/v4/source/iofs"
"gorm.io/driver/postgres"
"gorm.io/gorm"
"gorm.io/gorm/logger"
+ "github.com/getarcaneapp/arcane/backend/internal/config"
"github.com/getarcaneapp/arcane/backend/resources"
)
@@ -28,13 +33,41 @@ type DB struct {
*gorm.DB
}
+type MigrationOptions struct {
+ AllowDowngrade bool
+ githubRef string
+}
+
+const (
+ migrationRepositoryOwner = "getarcaneapp"
+ migrationRepositoryName = "arcane"
+ migrationRepositoryPath = "backend/resources/migrations"
+ migrationRepositoryRefFallback = "main"
+)
+
var customGormLogger logger.Interface
func SetGormLogger(l logger.Interface) {
customGormLogger = l
}
-func Initialize(ctx context.Context, databaseURL string) (*DB, error) {
+func (o MigrationOptions) githubRefInternal() string {
+ return githubRefForRevisionInternal(o, config.Revision)
+}
+
+func githubRefForRevisionInternal(options MigrationOptions, revision string) string {
+ if ref := strings.TrimSpace(options.githubRef); ref != "" {
+ return ref
+ }
+
+ if ref := strings.TrimSpace(revision); ref != "" && ref != "unknown" {
+ return ref
+ }
+
+ return migrationRepositoryRefFallback
+}
+
+func Initialize(ctx context.Context, databaseURL string, options MigrationOptions) (*DB, error) {
db, err := connectDatabase(ctx, databaseURL)
if err != nil {
return nil, fmt.Errorf("failed to connect to database: %w", err)
@@ -76,7 +109,7 @@ func Initialize(ctx context.Context, databaseURL string) (*DB, error) {
}
// Run migrations
- if err := migrateDatabase(driver, dbProvider); err != nil {
+ if err := migrateDatabase(driver, dbProvider, options); err != nil {
slog.Error("Failed to run migrations", "error", err)
return nil, fmt.Errorf("failed to run migrations: %w", err)
}
@@ -141,36 +174,268 @@ func connectDatabase(ctx context.Context, databaseURL string) (*DB, error) {
return nil, err
}
-func migrateDatabase(driver database.Driver, dbProvider string) error {
- source, err := iofs.New(resources.FS, "migrations/"+dbProvider)
+func migrateDatabase(driver database.Driver, dbProvider string, options MigrationOptions) error {
+ requiredVersion, err := getHighestEmbeddedMigrationVersionInternal(dbProvider)
if err != nil {
- return fmt.Errorf("failed to create embedded migration source: %w", err)
+ return fmt.Errorf("failed to determine target migration version for %s: %w", dbProvider, err)
}
- m, err := migrate.NewWithInstance("iofs", source, "arcane", driver)
+ return migrateDatabaseToVersionInternal(driver, dbProvider, options, requiredVersion)
+}
+
+func migrateDatabaseToVersionInternal(driver database.Driver, dbProvider string, options MigrationOptions, requiredVersion uint) error {
+ embeddedMigrate, embeddedSource, err := newEmbeddedMigrateInstanceInternal(driver, dbProvider)
if err != nil {
- return fmt.Errorf("failed to create migration instance: %w", err)
+ return fmt.Errorf("failed to create embedded migration instance: %w", err)
}
+ defer closeMigrateSourceInternal(embeddedSource, "embedded migrate source")
- err = m.Up()
- if err != nil && !errors.Is(err, migrate.ErrNoChange) {
- return fmt.Errorf("failed to apply migrations: %w", err)
+ currentVersion, dirty, hasVersion, err := currentMigrationStateInternal(embeddedMigrate)
+ if err != nil {
+ return err
}
- if errors.Is(err, migrate.ErrNoChange) {
- version, dirty, versionErr := m.Version()
- if versionErr != nil {
- slog.Info("Database schema is up to date")
- } else {
- slog.Info("Database schema is up to date", "migrationVersion", version, "dirty", dirty)
+ logMigrationStateInternal(dbProvider, currentVersion, requiredVersion, dirty, hasVersion)
+
+ if hasVersion && dirty && currentVersion < requiredVersion {
+ if !options.AllowDowngrade {
+ return fmt.Errorf("database schema version %d is dirty (interrupted forward migration); resolve it manually or set ALLOW_DOWNGRADE=true to clear the dirty flag and re-apply the migration", currentVersion)
+ }
+
+ forceVersion, forceErr := safeUintToIntInternal(currentVersion)
+ if forceErr != nil {
+ return fmt.Errorf("failed to convert current migration version %d while clearing dirty state: %w", currentVersion, forceErr)
+ }
+
+ if err := embeddedMigrate.Force(forceVersion); err != nil {
+ return fmt.Errorf("failed to clear dirty migration state for version %d: %w", currentVersion, err)
+ }
+
+ slog.Warn("Cleared dirty migration state before re-applying forward migration", "provider", dbProvider, "version", currentVersion)
+ }
+
+ if hasVersion && dirty && currentVersion == requiredVersion {
+ if !options.AllowDowngrade {
+ return fmt.Errorf("database schema version %d is dirty; resolve it manually or set ALLOW_DOWNGRADE=true to clear the dirty flag after verifying the database state", currentVersion)
+ }
+
+ forceVersion, forceErr := safeUintToIntInternal(currentVersion)
+ if forceErr != nil {
+ return fmt.Errorf("failed to convert current migration version %d while clearing dirty state: %w", currentVersion, forceErr)
+ }
+
+ if err := embeddedMigrate.Force(forceVersion); err != nil {
+ return fmt.Errorf("failed to clear dirty migration state for version %d: %w", currentVersion, err)
}
- } else {
- slog.Info("Database migrations completed successfully")
+
+ slog.Warn("Cleared dirty migration state at current version because ALLOW_DOWNGRADE=true", "provider", dbProvider, "version", currentVersion)
+ logUpToDateStateInternal(embeddedMigrate, dbProvider)
+ return nil
+ }
+
+ if hasVersion && currentVersion > requiredVersion {
+ if !options.AllowDowngrade {
+ return fmt.Errorf("database schema version %d is newer than this Arcane binary supports (target %d for %s); downgrade requires ALLOW_DOWNGRADE=true and a database backup before startup", currentVersion, requiredVersion, dbProvider)
+ }
+
+ if err := migrateDatabaseFromGitHubInternal(driver, dbProvider, currentVersion, requiredVersion, options.githubRefInternal()); err != nil {
+ return err
+ }
+
+ return nil
+ }
+
+ upErr := embeddedMigrate.Up()
+ if upErr != nil && !errors.Is(upErr, migrate.ErrNoChange) {
+ return fmt.Errorf("failed to apply embedded migrations for %s: %w", dbProvider, upErr)
+ }
+
+ if errors.Is(upErr, migrate.ErrNoChange) {
+ logUpToDateStateInternal(embeddedMigrate, dbProvider)
+ return nil
+ }
+
+ slog.Info("Database migrations completed successfully", "provider", dbProvider, "targetVersion", requiredVersion)
+ return nil
+}
+
+func migrateDatabaseFromGitHubInternal(driver database.Driver, dbProvider string, currentVersion, requiredVersion uint, githubRef string) error {
+ slog.Warn("Database downgrade detected",
+ "provider", dbProvider,
+ "currentVersion", currentVersion,
+ "requiredVersion", requiredVersion,
+ "source", buildGitHubMigrationSourceURLInternal(dbProvider, githubRef),
+ )
+
+ githubSource, err := newGitHubMigrationSourceInternal(dbProvider, githubRef)
+ if err != nil {
+ return fmt.Errorf("failed to create GitHub migration source for %s downgrade: %w; hint: ensure outbound GitHub access is available and set GITHUB_TOKEN if the GitHub API is rate-limited", dbProvider, err)
+ }
+
+ return migrateDatabaseFromSourceInternal(driver, dbProvider, currentVersion, requiredVersion, "github", "github migrate source", githubSource)
+}
+
+func migrateDatabaseFromSourceInternal(driver database.Driver, dbProvider string, currentVersion, requiredVersion uint, sourceName, sourceLabel string, sourceDriver source.Driver) error {
+ if sourceDriver == nil {
+ return fmt.Errorf("failed to create %s migration source for provider %s: source driver is nil", sourceName, dbProvider)
+ }
+ defer closeMigrateSourceInternal(sourceDriver, sourceLabel)
+
+ migrationInstance, err := migrate.NewWithInstance(sourceName, sourceDriver, "arcane", driver)
+ if err != nil {
+ return fmt.Errorf("failed to create %s migration instance for provider %s: %w", sourceName, dbProvider, err)
+ }
+
+ forceVersion, err := safeUintToIntInternal(currentVersion)
+ if err != nil {
+ return fmt.Errorf("failed to convert current migration version %d for downgrade: %w", currentVersion, err)
+ }
+
+ if err := migrationInstance.Force(forceVersion); err != nil {
+ return fmt.Errorf("failed to normalize migration state before downgrade from %d to %d for %s: %w", currentVersion, requiredVersion, dbProvider, err)
+ }
+
+ err = migrationInstance.Migrate(requiredVersion)
+ if err != nil && !errors.Is(err, migrate.ErrNoChange) {
+ return fmt.Errorf("failed to downgrade database from version %d to %d for %s: %w", currentVersion, requiredVersion, dbProvider, err)
}
+ slog.Info("Database downgrade completed successfully", "provider", dbProvider, "fromVersion", currentVersion, "toVersion", requiredVersion)
return nil
}
+func newEmbeddedMigrationSourceInternal(dbProvider string) (source.Driver, error) {
+ sourceDriver, err := iofs.New(resources.FS, "migrations/"+dbProvider)
+ if err != nil {
+ return nil, fmt.Errorf("failed to create embedded migration source: %w", err)
+ }
+
+ return sourceDriver, nil
+}
+
+func newEmbeddedMigrateInstanceInternal(driver database.Driver, dbProvider string) (*migrate.Migrate, source.Driver, error) {
+ sourceDriver, err := newEmbeddedMigrationSourceInternal(dbProvider)
+ if err != nil {
+ return nil, nil, err
+ }
+
+ m, err := migrate.NewWithInstance("iofs", sourceDriver, "arcane", driver)
+ if err != nil {
+ if closeErr := sourceDriver.Close(); closeErr != nil {
+ slog.Warn("Failed to close embedded migration source after instance creation failure", "provider", dbProvider, "error", closeErr)
+ }
+ return nil, nil, fmt.Errorf("failed to create migration instance: %w", err)
+ }
+
+ return m, sourceDriver, nil
+}
+
+func newGitHubMigrationSourceInternal(dbProvider string, githubRef string) (source.Driver, error) {
+ sourceDriver, err := source.Open(buildGitHubMigrationSourceURLInternal(dbProvider, githubRef))
+ if err != nil {
+ return nil, fmt.Errorf("failed to create GitHub migration source for provider %s: %w", dbProvider, err)
+ }
+
+ return sourceDriver, nil
+}
+
+func buildGitHubMigrationSourceURLInternal(dbProvider, githubRef string) string {
+ return fmt.Sprintf("github://%s/%s/%s/%s#%s", migrationRepositoryOwner, migrationRepositoryName, migrationRepositoryPath, dbProvider, githubRef)
+}
+
+func safeUintToIntInternal(value uint) (int, error) {
+ if value > uint(math.MaxInt) {
+ return 0, fmt.Errorf("value %d exceeds max int", value)
+ }
+
+ return int(value), nil
+}
+
+func currentMigrationStateInternal(m *migrate.Migrate) (version uint, dirty bool, hasVersion bool, err error) {
+ version, dirty, err = m.Version()
+ if errors.Is(err, migrate.ErrNilVersion) {
+ return 0, false, false, nil
+ }
+ if err != nil {
+ return 0, false, false, fmt.Errorf("failed to determine current migration version: %w", err)
+ }
+
+ return version, dirty, true, nil
+}
+
+func logUpToDateStateInternal(m *migrate.Migrate, dbProvider string) {
+ version, versionDirty, versionErr := m.Version()
+ switch {
+ case errors.Is(versionErr, migrate.ErrNilVersion):
+ slog.Info("Database schema is up to date", "provider", dbProvider, "migrationVersion", 0, "dirty", false)
+ case versionErr != nil:
+ slog.Info("Database schema is up to date", "provider", dbProvider)
+ default:
+ slog.Info("Database schema is up to date", "provider", dbProvider, "migrationVersion", version, "dirty", versionDirty)
+ }
+}
+
+func getHighestEmbeddedMigrationVersionInternal(dbProvider string) (uint, error) {
+ versions, err := getEmbeddedMigrationVersionsInternal(dbProvider)
+ if err != nil {
+ return 0, err
+ }
+ if len(versions) == 0 {
+ return 0, fmt.Errorf("no embedded migrations found for %s", dbProvider)
+ }
+
+ return versions[len(versions)-1], nil
+}
+
+func getEmbeddedMigrationVersionsInternal(dbProvider string) ([]uint, error) {
+ entries, err := resources.FS.ReadDir("migrations/" + dbProvider)
+ if err != nil {
+ return nil, fmt.Errorf("failed to read embedded migrations for %s: %w", dbProvider, err)
+ }
+
+ versionsMap := make(map[uint]struct{})
+ for _, entry := range entries {
+ if entry.IsDir() {
+ continue
+ }
+
+ migration, parseErr := source.DefaultParse(entry.Name())
+ if parseErr != nil {
+ continue
+ }
+
+ versionsMap[migration.Version] = struct{}{}
+ }
+
+ versions := make([]uint, 0, len(versionsMap))
+ for version := range versionsMap {
+ versions = append(versions, version)
+ }
+ slices.Sort(versions)
+
+ return versions, nil
+}
+
+func logMigrationStateInternal(dbProvider string, currentVersion, requiredVersion uint, dirty, hasVersion bool) {
+ if !hasVersion {
+ slog.Info("Resolved database migration state", "provider", dbProvider, "currentVersion", 0, "requiredVersion", requiredVersion, "dirty", false)
+ return
+ }
+
+ slog.Info("Resolved database migration state", "provider", dbProvider, "currentVersion", currentVersion, "requiredVersion", requiredVersion, "dirty", dirty)
+}
+
+func closeMigrateSourceInternal(sourceDriver source.Driver, sourceName string) {
+ if sourceDriver == nil {
+ return
+ }
+
+ sourceErr := sourceDriver.Close()
+ if sourceErr != nil {
+ slog.Warn("Failed to close migration source", "source", sourceName, "error", sourceErr)
+ }
+}
+
func parseSqliteConnectionString(connString string) (string, error) {
if !strings.HasPrefix(connString, "file:") {
connString = "file:" + connString
diff --git a/backend/internal/database/database_test.go b/backend/internal/database/database_test.go
new file mode 100644
index 000000000..940b4fc88
--- /dev/null
+++ b/backend/internal/database/database_test.go
@@ -0,0 +1,189 @@
+package database
+
+import (
+ "context"
+ "path/filepath"
+ "testing"
+
+ glsqlite "github.com/glebarez/sqlite"
+ "github.com/golang-migrate/migrate/v4/database"
+ sqliteMigrate "github.com/golang-migrate/migrate/v4/database/sqlite3"
+ "gorm.io/gorm"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestGetEmbeddedMigrationVersions_ProvidersMatch(t *testing.T) {
+ sqliteVersions, err := getEmbeddedMigrationVersionsInternal("sqlite")
+ require.NoError(t, err)
+
+ postgresVersions, err := getEmbeddedMigrationVersionsInternal("postgres")
+ require.NoError(t, err)
+
+ assert.Equal(t, sqliteVersions, postgresVersions)
+ require.NotEmpty(t, sqliteVersions)
+
+ highest, err := getHighestEmbeddedMigrationVersionInternal("sqlite")
+ require.NoError(t, err)
+ assert.Equal(t, sqliteVersions[len(sqliteVersions)-1], highest)
+}
+
+func TestMigrateDatabase_BlocksDowngradeWithoutFlag(t *testing.T) {
+ dbDir := t.TempDir()
+ driver := newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db")
+ require.NoError(t, migrateDatabase(driver, "sqlite", MigrationOptions{}))
+ targetVersion := downgradeTargetVersionInternal(t)
+
+ err := migrateDatabaseToVersionInternal(newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db"), "sqlite", MigrationOptions{}, targetVersion)
+ require.Error(t, err)
+ assert.ErrorContains(t, err, "ALLOW_DOWNGRADE=true")
+ assert.ErrorContains(t, err, "newer than this Arcane binary supports")
+}
+
+func TestMigrateDatabase_DowngradesWhenAllowed(t *testing.T) {
+ dbDir := t.TempDir()
+ driver := newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db")
+ require.NoError(t, migrateDatabase(driver, "sqlite", MigrationOptions{}))
+ targetVersion := downgradeTargetVersionInternal(t)
+ highestVersion, err := getHighestEmbeddedMigrationVersionInternal("sqlite")
+ require.NoError(t, err)
+ sourceDriver, err := newEmbeddedMigrationSourceInternal("sqlite")
+ require.NoError(t, err)
+
+ require.NoError(t, migrateDatabaseFromSourceInternal(newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db"), "sqlite", highestVersion, targetVersion, "iofs", "test embedded migrate source", sourceDriver))
+
+ instance, checkSourceDriver, err := newEmbeddedMigrateInstanceInternal(newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db"), "sqlite")
+ require.NoError(t, err)
+ defer closeMigrateSourceInternal(checkSourceDriver, "test embedded migrate source")
+ currentVersion, currentDirty, versionErr := instance.Version()
+ require.NoError(t, versionErr)
+ assert.Equal(t, targetVersion, currentVersion)
+ assert.False(t, currentDirty)
+}
+
+func TestMigrateDatabase_DowngradesDirtyStateWhenAllowed(t *testing.T) {
+ dbDir := t.TempDir()
+ driver := newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db")
+ require.NoError(t, migrateDatabase(driver, "sqlite", MigrationOptions{}))
+ targetVersion := downgradeTargetVersionInternal(t)
+ highestVersion, err := getHighestEmbeddedMigrationVersionInternal("sqlite")
+ require.NoError(t, err)
+ highestVersionInt, err := safeUintToIntInternal(highestVersion)
+ require.NoError(t, err)
+ require.NoError(t, newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db").SetVersion(highestVersionInt, true))
+ sourceDriver, err := newEmbeddedMigrationSourceInternal("sqlite")
+ require.NoError(t, err)
+
+ require.NoError(t, migrateDatabaseFromSourceInternal(newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db"), "sqlite", highestVersion, targetVersion, "iofs", "test embedded migrate source", sourceDriver))
+
+ instance, checkSourceDriver, err := newEmbeddedMigrateInstanceInternal(newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db"), "sqlite")
+ require.NoError(t, err)
+ defer closeMigrateSourceInternal(checkSourceDriver, "test embedded migrate source")
+ currentVersion, dirty, versionErr := instance.Version()
+ require.NoError(t, versionErr)
+ assert.Equal(t, targetVersion, currentVersion)
+ assert.False(t, dirty)
+}
+
+func TestMigrateDatabase_DirtyCurrentVersionRequiresResolution(t *testing.T) {
+ dbDir := t.TempDir()
+ driver := newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db")
+ require.NoError(t, migrateDatabase(driver, "sqlite", MigrationOptions{}))
+ highestVersion, err := getHighestEmbeddedMigrationVersionInternal("sqlite")
+ require.NoError(t, err)
+ highestVersionInt, err := safeUintToIntInternal(highestVersion)
+ require.NoError(t, err)
+ require.NoError(t, newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db").SetVersion(highestVersionInt, true))
+
+ err = migrateDatabaseToVersionInternal(newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db"), "sqlite", MigrationOptions{}, highestVersion)
+ require.Error(t, err)
+ assert.ErrorContains(t, err, "is dirty")
+ assert.ErrorContains(t, err, "ALLOW_DOWNGRADE=true")
+
+ require.NoError(t, migrateDatabaseToVersionInternal(newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db"), "sqlite", MigrationOptions{AllowDowngrade: true}, highestVersion))
+
+ instance, sourceDriver, err := newEmbeddedMigrateInstanceInternal(newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db"), "sqlite")
+ require.NoError(t, err)
+ defer closeMigrateSourceInternal(sourceDriver, "test embedded migrate source")
+ currentVersion, dirty, versionErr := instance.Version()
+ require.NoError(t, versionErr)
+ assert.Equal(t, highestVersion, currentVersion)
+ assert.False(t, dirty)
+}
+
+func TestMigrateDatabase_DirtyOlderVersionRequiresResolution(t *testing.T) {
+ dbDir := t.TempDir()
+ driver := newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db")
+ require.NoError(t, migrateDatabase(driver, "sqlite", MigrationOptions{}))
+ targetVersion := downgradeTargetVersionInternal(t)
+ targetVersionInt, err := safeUintToIntInternal(targetVersion)
+ require.NoError(t, err)
+ require.NoError(t, newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db").SetVersion(targetVersionInt, true))
+ highestVersion, err := getHighestEmbeddedMigrationVersionInternal("sqlite")
+ require.NoError(t, err)
+
+ err = migrateDatabaseToVersionInternal(newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db"), "sqlite", MigrationOptions{}, highestVersion)
+ require.Error(t, err)
+ assert.ErrorContains(t, err, "interrupted forward migration")
+ assert.ErrorContains(t, err, "ALLOW_DOWNGRADE=true")
+
+ require.NoError(t, migrateDatabaseToVersionInternal(newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db"), "sqlite", MigrationOptions{AllowDowngrade: true}, highestVersion))
+
+ instance, sourceDriver, err := newEmbeddedMigrateInstanceInternal(newSQLiteMigrationDriverInternal(t, dbDir, "arcane-test.db"), "sqlite")
+ require.NoError(t, err)
+ defer closeMigrateSourceInternal(sourceDriver, "test embedded migrate source")
+ currentVersion, dirty, versionErr := instance.Version()
+ require.NoError(t, versionErr)
+ assert.Equal(t, highestVersion, currentVersion)
+ assert.False(t, dirty)
+}
+
+func downgradeTargetVersionInternal(t *testing.T) uint {
+ t.Helper()
+
+ allVersions, err := getEmbeddedMigrationVersionsInternal("sqlite")
+ require.NoError(t, err)
+ require.GreaterOrEqual(t, len(allVersions), 2, "need at least 2 migration versions to test downgrade")
+
+ return allVersions[len(allVersions)-2]
+}
+
+func newSQLiteMigrationDriverInternal(t *testing.T, dirPath, fileName string) database.Driver {
+ t.Helper()
+
+ dsn := "file:" + filepath.Join(dirPath, fileName)
+ db, err := gorm.Open(glsqlite.Open(dsn), &gorm.Config{})
+ require.NoError(t, err)
+
+ sqlDB, err := db.DB()
+ require.NoError(t, err)
+ t.Cleanup(func() {
+ _ = sqlDB.Close()
+ })
+
+ driver, err := sqliteMigrate.WithInstance(sqlDB, &sqliteMigrate.Config{})
+ require.NoError(t, err)
+
+ return driver
+}
+
+func TestInitialize_AllowsMigrationOptions(t *testing.T) {
+ ctx := context.Background()
+ dsn := "file:" + filepath.Join(t.TempDir(), "arcane-init.db")
+
+ db, err := Initialize(ctx, dsn, MigrationOptions{})
+ require.NoError(t, err)
+ require.NotNil(t, db)
+
+ var settingsCount int64
+ require.NoError(t, db.WithContext(ctx).Table("settings").Count(&settingsCount).Error)
+
+ require.NoError(t, db.Close())
+}
+
+func TestMigrationOptions_GitHubRefUsesBuildRevision(t *testing.T) {
+ assert.Equal(t, "abc123def456", githubRefForRevisionInternal(MigrationOptions{}, "abc123def456"))
+ assert.Equal(t, "custom-ref", githubRefForRevisionInternal(MigrationOptions{githubRef: "custom-ref"}, "abc123def456"))
+ assert.Equal(t, migrationRepositoryRefFallback, githubRefForRevisionInternal(MigrationOptions{}, "unknown"))
+}