go-migrate

go-migrate

Intelligent database migration toolkit with GORM model integration and automated script generation.

Ecosystem

CHINESE README

中文说明

Features

• Smart Schema Analysis: Auto-compare GORM models with existing database schemas
• Automated Script Generation: Create migration scripts with intelligent version management
• Safe Operations: DryRun mode and preview to ensure secure migrations
• Multi-Database Support: Works with MySQL, PostgreSQL, SQLite through golang-migrate
• Comprehensive CLI: Intuitive Cobra commands covering all migration operations
• Status Inspection: Check database version, pending migrations and schema differences

Core Packages

Installation

go get github.com/go-xlan/go-migrate

Quick Start

1. Define GORM Models

type User struct {
    ID   uint   `gorm:"primarykey"`
    Name string `gorm:"size:100"`
    Age  int
}

2. Setup CLI Tool

package main

import (
    "github.com/go-xlan/go-migrate/cobramigration"
    "github.com/go-xlan/go-migrate/migrationstate"
    "github.com/go-xlan/go-migrate/newmigrate"
    "github.com/go-xlan/go-migrate/newscripts"
    "github.com/go-xlan/go-migrate/previewmigrate"
    "github.com/golang-migrate/migrate/v4"
    mysqlmigrate "github.com/golang-migrate/migrate/v4/database/mysql"
    "github.com/spf13/cobra"
    "github.com/yyle88/must"
    "github.com/yyle88/rese"
    "gorm.io/gorm"
)

func main() {
    scriptsPath := "./scripts"

    // MigrationParam with lazy initialization and unified resource management
    param := newmigrate.NewMigrationParam(
        func() *gorm.DB {
            return setupYourDatabase() // Your GORM setup
        },
        func(db *gorm.DB) *migrate.Migrate {
            sqlDB := rese.P1(db.DB())
            driver := rese.V1(mysqlmigrate.WithInstance(sqlDB, &mysqlmigrate.Config{}))
            return rese.P1(newmigrate.NewWithScriptsAndDatabase(&newmigrate.ScriptsAndDatabaseParam{
                ScriptsInRoot:    scriptsPath,
                DatabaseName:     "mysql",
                DatabaseInstance: driver,
            }))
        },
    )

    objects := []any{
        &User{},
        &Product{},
        &Cart{},
    }

    rootCmd := &cobra.Command{Use: "app"}
    rootCmd.AddCommand(newscripts.NewScriptCmd(&newscripts.Config{
        Param:   param,
        Options: newscripts.NewOptions(scriptsPath),
        Objects: objects,
    }))
    rootCmd.AddCommand(cobramigration.NewMigrateCmd(param))
    rootCmd.AddCommand(previewmigrate.NewPreviewCmd(param, scriptsPath))
    rootCmd.AddCommand(migrationstate.NewStatusCmd(&migrationstate.Config{
        Param:       param,
        ScriptsPath: scriptsPath,
        Objects:     objects,
    }))

    must.Done(rootCmd.Execute())
}

3. Common Workflow

# Step 1: Check current status
go run main.go status

# Step 2: Update GORM model (add field, change type, etc.)

# Step 3: Generate migration script
go run main.go new-script
# Creates: scripts/000001_xxx.up.sql and scripts/000001_xxx.down.sql

# Step 4: Preview pending execution
go run main.go preview inc

# Step 5: Execute migration
go run main.go migrate inc    # One step
go run main.go migrate all    # All pending

CLI Commands

Database Support

Works with MySQL, PostgreSQL, SQLite through golang-migrate drivers:

// MySQL
import mysqlmigrate "github.com/golang-migrate/migrate/v4/database/mysql"
driver := rese.V1(mysqlmigrate.WithInstance(sqlDB, &mysqlmigrate.Config{}))

// PostgreSQL
import postgresmigrate "github.com/golang-migrate/migrate/v4/database/postgres"
driver := rese.V1(postgresmigrate.WithInstance(sqlDB, &postgresmigrate.Config{}))

// SQLite
import sqlite3migrate "github.com/golang-migrate/migrate/v4/database/sqlite3"
driver := rese.V1(sqlite3migrate.WithInstance(sqlDB, &sqlite3migrate.Config{}))

Advanced Configuration

Embedded Migrations

//go:embed migrations
var migrationsFS embed.FS

migration := rese.V1(newmigrate.NewWithEmbedFsAndDatabase(&newmigrate.EmbedFsAndDatabaseParam{
    MigrationsFS:     &migrationsFS,
    EmbedDirName:     "migrations",
    DatabaseName:     "mysql",
    DatabaseInstance: driver,
}))

Custom Script Naming

naming := &newscripts.ScriptNaming{
    NewScriptPrefix: func(version uint) string {
        return fmt.Sprintf("%d_%s", version, description)
    },
}

Migration Options

options := newscripts.NewOptions("./scripts").
    WithDryRun(true).
    WithSurveyWritten(true)

Examples

See internal/demos/ with complete working examples:

• demo1x: MySQL integration with Makefile commands
• demo2x: PostgreSQL integration with Makefile commands

cd internal/demos/demo1x
make STATUS              # Check status
make CREATE-SCRIPT-CREATE-TABLE  # Generate scripts
make MIGRATE-PREVIEW-INC # Preview
make MIGRATE-ALL         # Execute

📄 License

MIT License - see LICENSE.

💬 Contact & Feedback

Contributions are welcome! Report bugs, suggest features, and contribute code:

• 🐛 Mistake reports? Open an issue on GitHub with reproduction steps
• 💡 Fresh ideas? Create an issue to discuss
• 📖 Documentation confusing? Report it so we can improve
• 🚀 Need new features? Share the use cases to help us understand requirements
• ⚡ Performance issue? Help us optimize through reporting slow operations
• 🔧 Configuration problem? Ask questions about complex setups
• 📢 Follow project progress? Watch the repo to get new releases and features
• 🌟 Success stories? Share how this package improved the workflow
• 💬 Feedback? We welcome suggestions and comments

🔧 Development

New code contributions, follow this process:

1. Fork: Fork the repo on GitHub (using the webpage UI).
2. Clone: Clone the forked project (git clone https://github.com/yourname/repo-name.git).
3. Navigate: Navigate to the cloned project (cd repo-name)
4. Branch: Create a feature branch (git checkout -b feature/xxx).
5. Code: Implement the changes with comprehensive tests
6. Testing: (Golang project) Ensure tests pass (go test ./...) and follow Go code style conventions
7. Documentation: Update documentation to support client-facing changes
8. Stage: Stage changes (git add .)
9. Commit: Commit changes (git commit -m "Add feature xxx") ensuring backward compatible code
10. Push: Push to the branch (git push origin feature/xxx).
11. PR: Open a merge request on GitHub (on the GitHub webpage) with detailed description.

Please ensure tests pass and include relevant documentation updates.

🌟 Support

Welcome to contribute to this project via submitting merge requests and reporting issues.

Project Support:

• ⭐ Give GitHub stars if this project helps you
• 🤝 Share with teammates and (golang) programming friends
• 📝 Write tech blogs about development tools and workflows - we provide content writing support
• 🌟 Join the ecosystem - committed to supporting open source and the (golang) development scene

Have Fun Coding with this package! 🎉🎉🎉

GitHub Stars