pkg/migrate — Migration Diff 自動生成

設計理念

Model struct 變更 → 反射掃描 bun tag → 比對上次快照 → 產生 SQL

快速上手

1. 註冊 Model

import "github.com/maoxiaoyue/hypgo/pkg/migrate"
type User struct {
 bun.BaseModel `bun:"table:users"`
 ID int64 `bun:"id,pk,autoincrement"`
 Name string `bun:"name,notnull"`
 Email string `bun:"email,notnull,unique"`
 Bio string `bun:"bio,type:text"`
 CreatedAt time.Time `bun:"created_at,notnull,default:current_timestamp"`
}
registry := migrate.NewRegistry()
registry.Register((*User)(nil))

2. 掃描 & Diff

// 掃描 Model → 提取 TableSchema
tables := migrate.ScanModels(registry)
// 載入上次快照
snapshot, _ := migrate.LoadSnapshot(".hyp/schema_snapshot.json")
// 比對 → 產生 ChangeSet
changes := migrate.Diff(tables, snapshot)
// 產生 SQL
up, down := migrate.GenerateSQL(changes, "postgres")
fmt.Println(up)
// → ALTER TABLE "users" ADD COLUMN "bio" TEXT;

3. 儲存

// 儲存新快照
migrate.SaveSnapshot(".hyp/schema_snapshot.json", tables)
// 取得 migration 檔名
upFile, downFile := migrate.MigrationFiles("migrations/")
// → migrations/20260326_200000_auto.up.sql
// → migrations/20260326_200000_auto.down.sql

完整工作流程

func generateMigration() {
 // 1. 註冊所有 Model
 registry := migrate.NewRegistry()
 registry.Register(
 (*models.User)(nil),
 (*models.Post)(nil),
 (*models.Comment)(nil),
 )
 // 2. 掃描
 tables := migrate.ScanModels(registry)
 // 3. Diff
 snapshot, _ := migrate.LoadSnapshot(".hyp/schema_snapshot.json")
 changes := migrate.Diff(tables, snapshot)
 if len(changes) == 0 {
 fmt.Println("No changes detected")
 return
 }
 // 4. 顯示變更
 for _, c := range changes {
 fmt.Println(c.String())
 }
 // 5. 產生 SQL
 up, down := migrate.GenerateSQL(changes, "postgres")
 // 6. 儲存 migration 檔案
 upFile, downFile := migrate.MigrationFiles("migrations/")
 os.WriteFile(upFile, []byte(up), 0644)
 os.WriteFile(downFile, []byte(down), 0644)
 // 7. 更新快照
 migrate.SaveSnapshot(".hyp/schema_snapshot.json", tables)
}

Scanner — bun tag 解析

Diff — 變更偵測

SQL Generator — 多 Dialect 支援

Go → SQL 型別對映

快照格式

{
 "tables": {
 "users": {
 "name": "users",
 "columns": [
 {"name": "id", "go_type": "int64", "primary_key": true, "auto_increment": true},
 {"name": "name", "go_type": "string", "not_null": true},
 {"name": "email", "go_type": "string", "not_null": true, "unique": true}
 ]
 }
 }
}

架構

pkg/migrate/
├── registry.go ModelRegistry — Model 註冊
├── scanner.go ScanModel() — 反射提取 bun tag → TableSchema
├── snapshot.go 快照讀寫(JSON)
├── diff.go Diff() — 比對新舊 schema → ChangeSet
├── generator.go GenerateSQL() — ChangeSet → SQL(pg/mysql)
└── migrate_test.go 22 個單元測試