diff --git a/CHANGELOG.md b/CHANGELOG.md index 0fe72a5e1..c8262ac7d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -96,7 +96,7 @@ is not connected, or refuses is "not found". See [the client docs](https://heads #### Database -- Only upgrades from 0.29.x are supported; migrations for older releases are removed and headscale refuses to start on an older database. Upgrade to the latest 0.29.x first [#3352](https://github.com/juanfont/headscale/pull/3352) +- Only upgrades from 0.29.x are supported; migrations for older releases are removed and headscale refuses to start on an older database. Upgrade one minor release at a time to the latest 0.29.x first [#3352](https://github.com/juanfont/headscale/pull/3352) [#3650](https://github.com/juanfont/headscale/pull/3650) - The `pre_auth_keys`, `api_keys`, `oauth_clients` and `oauth_access_tokens` tables are merged into `credentials` and dropped. The migration cannot be reversed; take a backup before upgrading, as downgrading means restoring it [#3352](https://github.com/juanfont/headscale/pull/3352) - API key IDs are renumbered, as all credential kinds now share one ID sequence; scripts using `headscale apikeys expire|delete --id` should look IDs up again or use `--prefix` [#3352](https://github.com/juanfont/headscale/pull/3352) - Deleting a user now clears the owner of its API keys and OAuth clients instead of leaving a dangling reference [#3352](https://github.com/juanfont/headscale/pull/3352) diff --git a/hscontrol/db/db.go b/hscontrol/db/db.go index 0d813b27a..3c55e3110 100644 --- a/hscontrol/db/db.go +++ b/hscontrol/db/db.go @@ -69,7 +69,8 @@ func NewHeadscaleDatabase(cfg *types.Config) (*HSDatabase, error) { []*gormigrate.Migration{ // New migrations must be added as transactions at the end of this list. // Migrations start from v0.29.0; older databases are rejected by - // checkMinimumMigration and must upgrade to the latest 0.29.x first. + // checkMinimumMigration and must upgrade one minor release at a time + // to the latest 0.29.x first. // // Rules: // - NEVER use gorm.AutoMigrate, write the exact migration steps needed diff --git a/hscontrol/db/versioncheck.go b/hscontrol/db/versioncheck.go index b63be3628..f6893ce03 100644 --- a/hscontrol/db/versioncheck.go +++ b/hscontrol/db/versioncheck.go @@ -183,21 +183,26 @@ func isDev(version string) bool { return ok } +// upgradePath is the documented route for any database older than v0.29.0. +const upgradePath = "upgrade one minor release at a time, using the latest patch of each, " + + "to the latest v0.29.x first, release page: https://github.com/juanfont/headscale/releases" + // checkMinimumMigration rejects non-fresh databases that have not reached // v0.29.0. It keys on the migrations table rather than database_versions, // which only exists since 0.29.0 and is skipped for dev builds. func checkMinimumMigration(db *gorm.DB) error { - if !db.Migrator().HasTable("migrations") { - // Databases created before gormigrate was introduced (0.23) have no - // migrations table either. Only treat the database as fresh when no - // legacy or current core table exists; otherwise InitSchema would - // stamp the schema as initialised instead of running migrations. - for _, table := range []string{"users", "machines", "nodes"} { - if db.Migrator().HasTable(table) { - return tooOldUpgradeError() - } - } + // Every release before 0.23 has a machines table and every path to 0.29 + // renames or drops it. Check it before the migrations table, which + // InitSchema may have stamped without migrating. + if db.Migrator().HasTable("machines") { + return fmt.Errorf( + "database has the machines table of a release before v0.23.0, "+ + "if a later release has started on it, restore the backup taken before that, then %s: %w", + upgradePath, errDatabaseTooOld, + ) + } + if !db.Migrator().HasTable("migrations") { return nil } @@ -208,6 +213,8 @@ func checkMinimumMigration(db *gorm.DB) error { return fmt.Errorf("counting migrations: %w", err) } + // Still fresh: InitSchema is not atomic, so a crashed first start leaves + // core tables beside an empty migrations table. if total == 0 { return nil } @@ -222,20 +229,12 @@ func checkMinimumMigration(db *gorm.DB) error { } if found == 0 { - return tooOldUpgradeError() + return fmt.Errorf("%s: %w", upgradePath, errDatabaseTooOld) } return nil } -func tooOldUpgradeError() error { - return fmt.Errorf( - "upgrade to the latest v0.29.x release first, "+ - "release page: https://github.com/juanfont/headscale/releases: %w", - errDatabaseTooOld, - ) -} - // checkVersionUpgradePath verifies that the running headscale version // is compatible with the version that last used this database. // diff --git a/hscontrol/db/versioncheck_test.go b/hscontrol/db/versioncheck_test.go index 2bd45d7ba..c5a48b2a8 100644 --- a/hscontrol/db/versioncheck_test.go +++ b/hscontrol/db/versioncheck_test.go @@ -514,17 +514,20 @@ func checkVersionUpgradePathFromVersions(db *gorm.DB, currentVersion string) err func TestCheckMinimumMigration(t *testing.T) { tests := []struct { - name string - ids []string // nil means no migrations table - legacyTable string // non-empty creates this legacy/current core table without a migrations table - wantErr bool + name string + ids []string // nil means no migrations table + table string // non-empty creates this table first + wantErr bool }{ {name: "no migrations table", ids: nil}, {name: "empty migrations table", ids: []string{}}, + {name: "fresh database after a failed InitSchema", ids: []string{}, table: "users"}, {name: "0.29 database", ids: []string{"SCHEMA_INIT", minimumMigrationID}}, {name: "created fresh by this release", ids: []string{"SCHEMA_INIT", "202606181200-recover-null-tags-node-user-id"}}, {name: "0.28 database", ids: []string{"SCHEMA_INIT", "202601121700-migrate-hostinfo-request-tags"}, wantErr: true}, - {name: "legacy database without migrations table", legacyTable: "users", wantErr: true}, + {name: "pre-0.23 database", table: "machines", wantErr: true}, + {name: "pre-0.23 database after a failed InitSchema", ids: []string{}, table: "machines", wantErr: true}, + {name: "pre-0.23 database stamped by InitSchema", ids: []string{"SCHEMA_INIT", minimumMigrationID}, table: "machines", wantErr: true}, } for _, tt := range tests { @@ -532,8 +535,8 @@ func TestCheckMinimumMigration(t *testing.T) { db, err := gorm.Open(sqlite.Open("file::memory:"), &gorm.Config{}) require.NoError(t, err) - if tt.legacyTable != "" { - require.NoError(t, db.Exec("CREATE TABLE "+tt.legacyTable+" (id varchar(255) PRIMARY KEY)").Error) + if tt.table != "" { + require.NoError(t, db.Exec("CREATE TABLE "+tt.table+" (id varchar(255) PRIMARY KEY)").Error) } if tt.ids != nil {