db: reject pre-0.23 databases by their machines table

Missing, empty or InitSchema-stamped migrations tables all hid them.
Error follows the one-minor-at-a-time upgrade path.

Fixes #3648
This commit is contained in:
Kristoffer Dalby committed 2026-11-06 10:04:31 +01:00
1 parent 3bb5789d24
commit 059b95bacc
4 files changed
+31 -28

No files matched your search

+1 -1
View File
@@ -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)
+2 -1
View File
@@ -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
+18 -19
View File
@@ -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.
//
+10 -7
View File
@@ -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 {