pkg/migrate -- Automatic Migration Diff Generation

Design Philosophy

Model struct changes -> Reflect & scan bun tags -> Compare with last snapshot -> Generate SQL

Quick Start

1. Register Models

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. Scan & Diff

// Scan Models -> Extract TableSchema
tables := migrate.ScanModels(registry)
// Load last snapshot
snapshot, _ := migrate.LoadSnapshot(".hyp/schema_snapshot.json")
// Compare -> Generate ChangeSet
changes := migrate.Diff(tables, snapshot)
// Generate SQL
up, down := migrate.GenerateSQL(changes, "postgres")
fmt.Println(up)
// -> ALTER TABLE "users" ADD COLUMN "bio" TEXT;

3. Save

// Save new snapshot
migrate.SaveSnapshot(".hyp/schema_snapshot.json", tables)
// Get migration filenames
upFile, downFile := migrate.MigrationFiles("migrations/")
// -> migrations/20260326_200000_auto.up.sql
// -> migrations/20260326_200000_auto.down.sql

Complete Workflow

func generateMigration() {
 // 1. Register all Models
 registry := migrate.NewRegistry()
 registry.Register(
 (*models.User)(nil),
 (*models.Post)(nil),
 (*models.Comment)(nil),
 )
 // 2. Scan
 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. Display changes
 for _, c := range changes {
 fmt.Println(c.String())
 }
 // 5. Generate SQL
 up, down := migrate.GenerateSQL(changes, "postgres")
 // 6. Save migration files
 upFile, downFile := migrate.MigrationFiles("migrations/")
 os.WriteFile(upFile, []byte(up), 0644)
 os.WriteFile(downFile, []byte(down), 0644)
 // 7. Update snapshot
 migrate.SaveSnapshot(".hyp/schema_snapshot.json", tables)
}

Scanner -- bun Tag Parsing

Diff -- Change Detection

SQL Generator -- Multi-Dialect Support

Go -> SQL Type Mapping

Snapshot Format

{
 "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}
 ]
 }
 }
}

Architecture

pkg/migrate/
├── registry.go ModelRegistry -- Model registration
├── scanner.go ScanModel() -- Reflect & extract bun tags -> TableSchema
├── snapshot.go Snapshot read/write (JSON)
├── diff.go Diff() -- Compare old/new schema -> ChangeSet
├── generator.go GenerateSQL() -- ChangeSet -> SQL (pg/mysql)
└── migrate_test.go 22 unit tests