[优化] 重构数据库迁移逻辑，整合遗留和Goose迁移处理

2026-10-04 23:16:37 +08:00 · 2026-06-02 23:35:02 +08:00
parent 4ca6f2957b
commit a0e9484e37
10 changed files with 312 additions and 134 deletions
@@ -1,4 +1,4 @@
-package model
+package goose

 import (
 	"database/sql"
@@ -9,6 +9,17 @@ import (
 	"gorm.io/gorm"
 )

+type BridgeContext interface {
+	Context
+	AutoMigrateLegacySchemaMetadata(db *gorm.DB) error
+	InitializeFreshDatabaseSchema(db *gorm.DB, backend string) error
+	IsDatabaseEmpty(db *gorm.DB) (bool, error)
+	RepairCurrentSchemaState(db *gorm.DB, backend string) error
+	SaveLegacyDatabaseSchemaVersion(db *gorm.DB, version int) error
+	UpgradeLegacyDatabaseSchema(db *gorm.DB, backend string, version int) error
+	ValidateCurrentDatabaseSchema(db *gorm.DB, backend string) error
+}
+
 type schemaMigrationState int

 const (
@@ -19,8 +30,8 @@ const (
 	schemaMigrationStateMixed
 )

-func detectLegacySchemaState(db *gorm.DB) (schemaMigrationState, error) {
-	hasLegacyTable := db.Migrator().HasTable(&DatabaseSchemaVersion{})
+func detectSchemaState(db *gorm.DB, ctx BridgeContext) (schemaMigrationState, error) {
+	hasLegacyTable := db.Migrator().HasTable("database_schema_versions")
 	hasGooseTable := db.Migrator().HasTable("goose_db_version")

 	switch {
@@ -32,7 +43,7 @@ func detectLegacySchemaState(db *gorm.DB) (schemaMigrationState, error) {
 		return schemaMigrationStateGooseOnly, nil
 	}

-	empty, err := isDatabaseEmpty(db)
+	empty, err := ctx.IsDatabaseEmpty(db)
 	if err != nil {
 		return 0, err
 	}
@@ -42,7 +53,7 @@ func detectLegacySchemaState(db *gorm.DB) (schemaMigrationState, error) {
 	return schemaMigrationStateLegacyBootstrap, nil
 }

-func loadGooseDatabaseVersion(db *gorm.DB) (int, bool, error) {
+func LoadDatabaseVersion(db *gorm.DB) (int, bool, error) {
 	if db == nil || !db.Migrator().HasTable("goose_db_version") {
 		return 0, false, nil
 	}
@@ -64,8 +75,29 @@ func loadGooseDatabaseVersion(db *gorm.DB) (int, bool, error) {
 	return int(version), true, nil
 }

-func bootstrapLegacySchemaVersion(db *gorm.DB) error {
-	if err := autoMigrateLegacySchemaMetadata(db); err != nil {
+func loadLegacyDatabaseSchemaVersion(db *gorm.DB) (int, bool, error) {
+	if db == nil || !db.Migrator().HasTable("database_schema_versions") {
+		return 0, false, nil
+	}
+
+	var version int
+	err := db.Table("database_schema_versions").
+		Where("id = ?", 1).
+		Select("version").
+		Limit(1).
+		Row().
+		Scan(&version)
+	if errors.Is(err, sql.ErrNoRows) {
+		return 0, false, nil
+	}
+	if err != nil {
+		return 0, false, err
+	}
+	return version, true, nil
+}
+
+func bootstrapLegacySchemaVersion(db *gorm.DB, ctx BridgeContext) error {
+	if err := ctx.AutoMigrateLegacySchemaMetadata(db); err != nil {
 		return err
 	}
 	version, exists, err := loadLegacyDatabaseSchemaVersion(db)
@@ -73,16 +105,16 @@ func bootstrapLegacySchemaVersion(db *gorm.DB) error {
 		return err
 	}
 	if exists {
-		if version > legacyMigrationTerminalVersion {
-			return fmt.Errorf("legacy schema version %d is newer than supported terminal version %d", version, legacyMigrationTerminalVersion)
+		if int64(version) > LegacyBridgeVersion {
+			return fmt.Errorf("legacy schema version %d is newer than supported terminal version %d", version, LegacyBridgeVersion)
 		}
 		return nil
 	}
-	return saveLegacyDatabaseSchemaVersion(db, legacyDatabaseSchemaVersion)
+	return ctx.SaveLegacyDatabaseSchemaVersion(db, 7)
 }

-func upgradeLegacyToLegacyTerminal(db *gorm.DB, backend string) error {
-	if err := bootstrapLegacySchemaVersion(db); err != nil {
+func upgradeLegacyToTerminal(db *gorm.DB, backend string, ctx BridgeContext) error {
+	if err := bootstrapLegacySchemaVersion(db, ctx); err != nil {
 		return err
 	}
 	version, exists, err := loadLegacyDatabaseSchemaVersion(db)
@@ -92,70 +124,64 @@ func upgradeLegacyToLegacyTerminal(db *gorm.DB, backend string) error {
 	if !exists {
 		return fmt.Errorf("legacy schema version record is missing after bootstrap")
 	}
-	return upgradeLegacyDatabaseSchema(db, backend, version)
+	return ctx.UpgradeLegacyDatabaseSchema(db, backend, version)
 }

 func validateGooseBridgeState(db *gorm.DB) error {
-	version, exists, err := loadGooseDatabaseVersion(db)
+	version, exists, err := LoadDatabaseVersion(db)
 	if err != nil {
 		return err
 	}
 	if !exists {
 		return nil
 	}
-	if version < legacyMigrationTerminalVersion {
-		return fmt.Errorf("goose schema version %d is below legacy bridge baseline %d", version, legacyMigrationTerminalVersion)
+	if int64(version) < LegacyBridgeVersion {
+		return fmt.Errorf("goose schema version %d is below legacy bridge baseline %d", version, LegacyBridgeVersion)
 	}
-	if int64(version) > currentGooseTargetVersion() {
-		return fmt.Errorf("goose schema version %d is newer than application target version %d", version, currentGooseTargetVersion())
+	if int64(version) > CurrentTargetVersion() {
+		return fmt.Errorf("goose schema version %d is newer than application target version %d", version, CurrentTargetVersion())
 	}
 	return nil
 }

 func finalizeLegacyToGooseBridge(db *gorm.DB) error {
-	gooseVersion, exists, err := loadGooseDatabaseVersion(db)
+	gooseVersion, exists, err := LoadDatabaseVersion(db)
 	if err != nil {
 		return err
 	}
-	if !exists || gooseVersion < legacyMigrationTerminalVersion {
+	if !exists || int64(gooseVersion) < LegacyBridgeVersion {
 		return nil
 	}
-	if !db.Migrator().HasTable(&DatabaseSchemaVersion{}) {
+	if !db.Migrator().HasTable("database_schema_versions") {
 		return nil
 	}
-	if err := db.Migrator().DropTable(&DatabaseSchemaVersion{}); err != nil {
+	if err := db.Exec("DROP TABLE IF EXISTS database_schema_versions").Error; err != nil {
 		return fmt.Errorf("drop legacy schema versions table failed: %w", err)
 	}
 	slog.Info("completed legacy-to-goose migration bridge", "goose_version", gooseVersion)
 	return nil
 }

-func repairCurrentSchemaState(db *gorm.DB, backend string) error {
-	if err := dropLegacyNodeColumns(db, backend); err != nil {
-		return err
-	}
-	if err := ensureDefaultGitHubAuthSource(db); err != nil {
-		return err
-	}
-	if err := ensureDefaultWAFRuleGroup(db); err != nil {
+func ValidateRegisteredSchema(db *gorm.DB) error {
+	if err := validateNodeCapabilitiesJSON(db); err != nil {
 		return err
 	}
 	return nil
 }

-func ensureDatabaseSchemaUpToDate(db *gorm.DB, backend string) error {
-	state, err := detectLegacySchemaState(db)
+func EnsureDatabaseSchemaUpToDate(db *gorm.DB, backend string, ctx BridgeContext) error {
+	state, err := detectSchemaState(db, ctx)
 	if err != nil {
 		return err
 	}

 	switch state {
 	case schemaMigrationStateFresh:
-		if err := initializeFreshDatabaseSchema(db, backend); err != nil {
+		if err := ctx.InitializeFreshDatabaseSchema(db, backend); err != nil {
 			return err
 		}
 	case schemaMigrationStateLegacyOnly:
-		if err := upgradeLegacyToLegacyTerminal(db, backend); err != nil {
+		if err := upgradeLegacyToTerminal(db, backend, ctx); err != nil {
 			return err
 		}
 	case schemaMigrationStateGooseOnly:
@@ -163,7 +189,7 @@ func ensureDatabaseSchemaUpToDate(db *gorm.DB, backend string) error {
 			return err
 		}
 	case schemaMigrationStateLegacyBootstrap:
-		if err := upgradeLegacyToLegacyTerminal(db, backend); err != nil {
+		if err := upgradeLegacyToTerminal(db, backend, ctx); err != nil {
 			return err
 		}
 	case schemaMigrationStateMixed:
@@ -171,8 +197,8 @@ func ensureDatabaseSchemaUpToDate(db *gorm.DB, backend string) error {
 		if err != nil {
 			return err
 		}
-		if exists && legacyVersion != legacyMigrationTerminalVersion {
-			return fmt.Errorf("incomplete mixed migration state: legacy schema version %d does not match bridge terminal version %d", legacyVersion, legacyMigrationTerminalVersion)
+		if exists && int64(legacyVersion) != LegacyBridgeVersion {
+			return fmt.Errorf("incomplete mixed migration state: legacy schema version %d does not match bridge terminal version %d", legacyVersion, LegacyBridgeVersion)
 		}
 		if err := validateGooseBridgeState(db); err != nil {
 			return err
@@ -181,14 +207,17 @@ func ensureDatabaseSchemaUpToDate(db *gorm.DB, backend string) error {
 		return fmt.Errorf("unknown schema migration state: %d", state)
 	}

-	if err := runGooseMigrations(db, backend); err != nil {
+	if err := runMigrations(db, backend, ctx); err != nil {
 		return err
 	}
 	if err := finalizeLegacyToGooseBridge(db); err != nil {
 		return err
 	}
-	if err := repairCurrentSchemaState(db, backend); err != nil {
+	if err := ctx.RepairCurrentSchemaState(db, backend); err != nil {
 		return err
 	}
-	return validateCurrentDatabaseSchema(db, backend)
+	if err := ctx.ValidateCurrentDatabaseSchema(db, backend); err != nil {
+		return err
+	}
+	return ValidateRegisteredSchema(db)
 }
@@ -0,0 +1,50 @@
+package goose
+
+import (
+	"encoding/json"
+	"fmt"
+
+	presslygoose "github.com/pressly/goose/v3"
+	"gorm.io/gorm"
+)
+
+const versionNodeCapabilitiesJSON int64 = 202606020001
+
+// migration202606020001 adds a future-proof JSON field for node capability
+// summaries after the legacy v17 migration bridge.
+func migration202606020001(backend string, ctx Context) *presslygoose.Migration {
+	return newGORMMigration(
+		versionNodeCapabilitiesJSON,
+		"202606020001_add_node_capabilities_json.go",
+		backend,
+		ctx,
+		migrateNodeCapabilitiesJSON,
+	)
+}
+
+func migrateNodeCapabilitiesJSON(ctx Context, db *gorm.DB, backend string) error {
+	if err := ctx.ApplyCurrentSchema(db, backend); err != nil {
+		return err
+	}
+	emptyJSON, err := json.Marshal([]string{})
+	if err != nil {
+		return fmt.Errorf("marshal default node capabilities: %w", err)
+	}
+	if err := db.Exec(
+		`UPDATE nodes SET capabilities_json = ? WHERE capabilities_json IS NULL OR TRIM(capabilities_json) = ''`,
+		string(emptyJSON),
+	).Error; err != nil {
+		return fmt.Errorf("backfill nodes.capabilities_json: %w", err)
+	}
+	return validateNodeCapabilitiesJSON(db)
+}
+
+func validateNodeCapabilitiesJSON(db *gorm.DB) error {
+	if db == nil {
+		return fmt.Errorf("database handle is nil")
+	}
+	if !db.Migrator().HasColumn("nodes", "capabilities_json") {
+		return fmt.Errorf("column nodes.capabilities_json is missing")
+	}
+	return nil
+}
@@ -0,0 +1,71 @@
+package goose
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+
+	presslygoose "github.com/pressly/goose/v3"
+	"gorm.io/gorm"
+)
+
+const LegacyBridgeVersion int64 = 17
+
+type migrationFunc func(ctx Context, db *gorm.DB, backend string) error
+
+func newBaselineMigration() *presslygoose.Migration {
+	migration := presslygoose.NewGoMigration(LegacyBridgeVersion, nil, nil)
+	migration.Source = fmt.Sprintf("%05d_legacy_terminal_baseline.go", LegacyBridgeVersion)
+	return migration
+}
+
+func newGORMMigration(version int64, source string, backend string, ctx Context, up migrationFunc) *presslygoose.Migration {
+	migration := presslygoose.NewGoMigration(version, &presslygoose.GoFunc{
+		RunDB: func(_ context.Context, sqlDB *sql.DB) error {
+			gormDB, err := openGORMDB(ctx, sqlDB, backend)
+			if err != nil {
+				return err
+			}
+			if backend == "postgres" {
+				return gormDB.Transaction(func(tx *gorm.DB) error {
+					return up(ctx, tx, backend)
+				})
+			}
+			return up(ctx, gormDB, backend)
+		},
+	}, nil)
+	migration.Source = source
+	return migration
+}
+
+func registeredMigrations(backend string, ctx Context) []*presslygoose.Migration {
+	return []*presslygoose.Migration{
+		migration202606020001(backend, ctx),
+	}
+}
+
+func buildMigrations(backend string, ctx Context) []*presslygoose.Migration {
+	migrations := []*presslygoose.Migration{newBaselineMigration()}
+	migrations = append(migrations, registeredMigrations(backend, ctx)...)
+	return migrations
+}
+
+func CurrentTargetVersion() int64 {
+	var maxVersion int64 = LegacyBridgeVersion
+	for _, migration := range buildMigrations("sqlite", noopContext{}) {
+		if migration.Version > maxVersion {
+			maxVersion = migration.Version
+		}
+	}
+	return maxVersion
+}
+
+type noopContext struct{}
+
+func (noopContext) ApplyCurrentSchema(db *gorm.DB, backend string) error {
+	return nil
+}
+
+func (noopContext) RegisterSharding(db *gorm.DB, backend string) error {
+	return nil
+}
@@ -1,4 +1,4 @@
-package model
+package goose

 import (
 	"context"
@@ -6,24 +6,29 @@ import (
 	"fmt"

 	"github.com/glebarez/sqlite"
-	"github.com/pressly/goose/v3"
+	presslygoose "github.com/pressly/goose/v3"
 	"gorm.io/driver/postgres"
 	"gorm.io/gorm"
 	"gorm.io/gorm/schema"
 )

-func gooseDialectForBackend(backend string) (goose.Dialect, error) {
+type Context interface {
+	ApplyCurrentSchema(db *gorm.DB, backend string) error
+	RegisterSharding(db *gorm.DB, backend string) error
+}
+
+func dialectForBackend(backend string) (presslygoose.Dialect, error) {
 	switch backend {
 	case "postgres":
-		return goose.DialectPostgres, nil
+		return presslygoose.DialectPostgres, nil
 	case "sqlite":
-		return goose.DialectSQLite3, nil
+		return presslygoose.DialectSQLite3, nil
 	default:
 		return "", fmt.Errorf("unsupported database backend: %s", backend)
 	}
 }

-func getGORMDBFromSQLDB(db *sql.DB, backend string) (*gorm.DB, error) {
+func openGORMDB(ctx Context, db *sql.DB, backend string) (*gorm.DB, error) {
 	var dialector gorm.Dialector
 	switch backend {
 	case "postgres":
@@ -40,32 +45,32 @@ func getGORMDBFromSQLDB(db *sql.DB, backend string) (*gorm.DB, error) {
 	if err != nil {
 		return nil, err
 	}
-	if err := registerSharding(gormDB, backend); err != nil {
+	if err := ctx.RegisterSharding(gormDB, backend); err != nil {
 		return nil, err
 	}
 	return gormDB, nil
 }

-func buildGooseProvider(db *gorm.DB, backend string) (*goose.Provider, error) {
+func buildProvider(db *gorm.DB, backend string, ctx Context) (*presslygoose.Provider, error) {
 	sqlDB, err := db.DB()
 	if err != nil {
 		return nil, err
 	}
-	dialect, err := gooseDialectForBackend(backend)
+	dialect, err := dialectForBackend(backend)
 	if err != nil {
 		return nil, err
 	}
-	return goose.NewProvider(
+	return presslygoose.NewProvider(
 		dialect,
 		sqlDB,
 		nil,
-		goose.WithDisableGlobalRegistry(true),
-		goose.WithGoMigrations(buildGooseMigrations(backend)...),
+		presslygoose.WithDisableGlobalRegistry(true),
+		presslygoose.WithGoMigrations(buildMigrations(backend, ctx)...),
 	)
 }

-func runGooseMigrations(db *gorm.DB, backend string) error {
-	provider, err := buildGooseProvider(db, backend)
+func runMigrations(db *gorm.DB, backend string, ctx Context) error {
+	provider, err := buildProvider(db, backend, ctx)
 	if err != nil {
 		return fmt.Errorf("build goose provider: %w", err)
 	}
@@ -1,62 +0,0 @@
-package model
-
-import (
-	"context"
-	"database/sql"
-	"fmt"
-
-	"github.com/pressly/goose/v3"
-	"gorm.io/gorm"
-)
-
-func newGooseBaselineMigration() *goose.Migration {
-	migration := goose.NewGoMigration(int64(legacyMigrationTerminalVersion), nil, nil)
-	migration.Source = fmt.Sprintf("%05d_legacy_terminal_baseline.go", legacyMigrationTerminalVersion)
-	return migration
-}
-
-func newGooseGORMMigration(
-	version int64,
-	source string,
-	backend string,
-	up func(ctx databaseSchemaMigrationContext, db *gorm.DB, backend string) error,
-) *goose.Migration {
-	migration := goose.NewGoMigration(version, &goose.GoFunc{
-		RunDB: func(_ context.Context, sqlDB *sql.DB) error {
-			gormDB, err := getGORMDBFromSQLDB(sqlDB, backend)
-			if err != nil {
-				return err
-			}
-			ctx := databaseSchemaMigrationContext{}
-			if backend == "postgres" {
-				return gormDB.Transaction(func(tx *gorm.DB) error {
-					return up(ctx, tx, backend)
-				})
-			}
-			return up(ctx, gormDB, backend)
-		},
-	}, nil)
-	migration.Source = source
-	return migration
-}
-
-func registeredGooseMigrations(backend string) []*goose.Migration {
-	_ = backend
-	return nil
-}
-
-func buildGooseMigrations(backend string) []*goose.Migration {
-	migrations := []*goose.Migration{newGooseBaselineMigration()}
-	migrations = append(migrations, registeredGooseMigrations(backend)...)
-	return migrations
-}
-
-func currentGooseTargetVersion() int64 {
-	var maxVersion int64 = legacyMigrationTerminalVersion
-	for _, migration := range buildGooseMigrations("sqlite") {
-		if migration.Version > maxVersion {
-			maxVersion = migration.Version
-		}
-	}
-	return maxVersion
-}
@@ -89,6 +89,10 @@ func findDBModelByTableName(t *testing.T, tableName string) dbModel {
 	return dbModel{}
 }

+func expectedCurrentDatabaseVersion() int {
+	return int(currentGooseTargetVersion())
+}
+
 func TestIsDatabaseEmpty(t *testing.T) {
 	db := openTestSQLiteDB(t, "empty.db")

@@ -303,8 +307,8 @@ func TestEnsureDatabaseSchemaUpToDateInitializesFreshDatabase(t *testing.T) {
 	if !exists {
 		t.Fatal("expected database schema version to be recorded")
 	}
-	if version != currentDatabaseSchemaVersion {
-		t.Fatalf("unexpected schema version: got %d want %d", version, currentDatabaseSchemaVersion)
+	if version != expectedCurrentDatabaseVersion() {
+		t.Fatalf("unexpected schema version: got %d want %d", version, expectedCurrentDatabaseVersion())
 	}
 	if db.Migrator().HasTable(&DatabaseSchemaVersion{}) {
 		t.Fatal("expected fresh database to avoid legacy database_schema_versions table")
@@ -312,6 +316,9 @@ func TestEnsureDatabaseSchemaUpToDateInitializesFreshDatabase(t *testing.T) {
 	if !db.Migrator().HasTable("goose_db_version") {
 		t.Fatal("expected fresh database to initialize goose_db_version")
 	}
+	if !db.Migrator().HasColumn(&Node{}, "capabilities_json") {
+		t.Fatal("expected fresh database to apply goose migration nodes.capabilities_json")
+	}
 }

 func TestEnsureDatabaseSchemaUpToDateUpgradesLegacyDatabase(t *testing.T) {
@@ -343,8 +350,8 @@ func TestEnsureDatabaseSchemaUpToDateUpgradesLegacyDatabase(t *testing.T) {
 	if !exists {
 		t.Fatal("expected legacy database to gain a schema version record")
 	}
-	if version != currentDatabaseSchemaVersion {
-		t.Fatalf("unexpected schema version: got %d want %d", version, currentDatabaseSchemaVersion)
+	if version != expectedCurrentDatabaseVersion() {
+		t.Fatalf("unexpected schema version: got %d want %d", version, expectedCurrentDatabaseVersion())
 	}
 	if db.Migrator().HasTable(&DatabaseSchemaVersion{}) {
 		t.Fatal("expected legacy database_schema_versions table to be removed after bridging to goose")
@@ -352,6 +359,9 @@ func TestEnsureDatabaseSchemaUpToDateUpgradesLegacyDatabase(t *testing.T) {
 	if !db.Migrator().HasTable("goose_db_version") {
 		t.Fatal("expected legacy upgrade to initialize goose_db_version")
 	}
+	if !db.Migrator().HasColumn(&Node{}, "capabilities_json") {
+		t.Fatal("expected legacy upgrade to apply goose migration nodes.capabilities_json")
+	}
 }

 func TestMigrateOriginsSchemaBackfillsOrigins(t *testing.T) {
@@ -544,8 +554,11 @@ func TestEnsureDatabaseSchemaUpToDateAddsNodeIPManualOverride(t *testing.T) {
 	if !exists {
 		t.Fatal("expected schema version record to exist")
 	}
-	if version != currentDatabaseSchemaVersion {
-		t.Fatalf("unexpected schema version: got %d want %d", version, currentDatabaseSchemaVersion)
+	if version != expectedCurrentDatabaseVersion() {
+		t.Fatalf("unexpected schema version: got %d want %d", version, expectedCurrentDatabaseVersion())
+	}
+	if !db.Migrator().HasColumn(&Node{}, "capabilities_json") {
+		t.Fatal("expected migration chain to include nodes.capabilities_json")
 	}
 }

@@ -628,8 +641,11 @@ func TestEnsureDatabaseSchemaUpToDateV16BackfillsNodeColumnsWhenNewColumnsAlread
 	if !exists {
 		t.Fatal("expected schema version record to exist")
 	}
-	if version != currentDatabaseSchemaVersion {
-		t.Fatalf("unexpected schema version: got %d want %d", version, currentDatabaseSchemaVersion)
+	if version != expectedCurrentDatabaseVersion() {
+		t.Fatalf("unexpected schema version: got %d want %d", version, expectedCurrentDatabaseVersion())
+	}
+	if !db.Migrator().HasColumn(&Node{}, "capabilities_json") {
+		t.Fatal("expected v16 upgrade path to apply goose migration nodes.capabilities_json")
 	}
 }

@@ -673,6 +689,9 @@ func TestEnsureDatabaseSchemaUpToDateV16DropsLegacyNodeColumnsWhenAlreadyCurrent
 	if !db.Migrator().HasTable("goose_db_version") {
 		t.Fatal("expected current-schema goose_db_version table to exist")
 	}
+	if !db.Migrator().HasColumn(&Node{}, "capabilities_json") {
+		t.Fatal("expected current-schema repair to preserve goose column nodes.capabilities_json")
+	}
 }

 func TestEnsureDatabaseSchemaUpToDateKeepsGooseOnlyDatabaseOnReentry(t *testing.T) {
@@ -702,8 +721,11 @@ func TestEnsureDatabaseSchemaUpToDateKeepsGooseOnlyDatabaseOnReentry(t *testing.
 	if !exists {
 		t.Fatal("expected goose-only database to keep goose version record")
 	}
-	if version != currentDatabaseSchemaVersion {
-		t.Fatalf("unexpected goose version: got %d want %d", version, currentDatabaseSchemaVersion)
+	if version != expectedCurrentDatabaseVersion() {
+		t.Fatalf("unexpected goose version: got %d want %d", version, expectedCurrentDatabaseVersion())
+	}
+	if !db.Migrator().HasColumn(&Node{}, "capabilities_json") {
+		t.Fatal("expected goose-only database to keep nodes.capabilities_json")
 	}
 }

@@ -37,6 +37,7 @@ type Node struct {
 	RelayAgentAccessAddr  string `json:"relay_agent_access_addr" gorm:"size:255"`
 	RelayClientAccessAddr string `json:"relay_client_access_addr" gorm:"size:255"`
 	RelayClientProxyURL   string `json:"relay_client_proxy_url" gorm:"size:512"`
+	CapabilitiesJSON      string `json:"capabilities_json" gorm:"type:text;not null;default:'[]'"`
 	RelayStatus           string `json:"relay_status" gorm:"size:16;not null;default:'unknown'"`
 	RelayWebServerEnabled bool   `json:"relay_web_server_enabled" gorm:"not null;default:false"`
 }
@@ -0,0 +1,60 @@
+package model
+
+import (
+	schemagoose "openflare/model/goose"
+
+	"gorm.io/gorm"
+)
+
+func currentGooseTargetVersion() int64 {
+	return schemagoose.CurrentTargetVersion()
+}
+
+func loadGooseDatabaseVersion(db *gorm.DB) (int, bool, error) {
+	return schemagoose.LoadDatabaseVersion(db)
+}
+
+func ensureDatabaseSchemaUpToDate(db *gorm.DB, backend string) error {
+	return schemagoose.EnsureDatabaseSchemaUpToDate(db, backend, databaseSchemaMigrationContext{})
+}
+
+func (databaseSchemaMigrationContext) RegisterSharding(db *gorm.DB, backend string) error {
+	return registerSharding(db, backend)
+}
+
+func (databaseSchemaMigrationContext) AutoMigrateLegacySchemaMetadata(db *gorm.DB) error {
+	return autoMigrateLegacySchemaMetadata(db)
+}
+
+func (databaseSchemaMigrationContext) InitializeFreshDatabaseSchema(db *gorm.DB, backend string) error {
+	return initializeFreshDatabaseSchema(db, backend)
+}
+
+func (databaseSchemaMigrationContext) IsDatabaseEmpty(db *gorm.DB) (bool, error) {
+	return isDatabaseEmpty(db)
+}
+
+func (databaseSchemaMigrationContext) RepairCurrentSchemaState(db *gorm.DB, backend string) error {
+	if err := dropLegacyNodeColumns(db, backend); err != nil {
+		return err
+	}
+	if err := ensureDefaultGitHubAuthSource(db); err != nil {
+		return err
+	}
+	if err := ensureDefaultWAFRuleGroup(db); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (databaseSchemaMigrationContext) SaveLegacyDatabaseSchemaVersion(db *gorm.DB, version int) error {
+	return saveLegacyDatabaseSchemaVersion(db, version)
+}
+
+func (databaseSchemaMigrationContext) UpgradeLegacyDatabaseSchema(db *gorm.DB, backend string, version int) error {
+	return upgradeLegacyDatabaseSchema(db, backend, version)
+}
+
+func (databaseSchemaMigrationContext) ValidateCurrentDatabaseSchema(db *gorm.DB, backend string) error {
+	return validateCurrentDatabaseSchema(db, backend)
+}