gomigration

🧠 GoMigration

GoMigration is a lightweight and extensible database migration library for Go, designed with simplicity and flexibility in mind. It allows you to register migrations in Go code, manage them efficiently, and execute or roll them back in a safe and structured manner.

📝 Note: This project is a fork of ruangdeveloper/qafoia, moved under a new organization for long-term maintenance and development.

✨ Features

• Register migrations using Go structs.
• Run, rollback, reset, or re-run migrations with ease.
• Debug SQL output during migration execution.
• Automatically generates migration file templates.
• Tracks applied migrations using a dedicated database table.
• Ready-to-use MySQL and Postgres drivers.

📦 Installation

To install GoMigration, use the following command:

go get github.com/openframebox/gomigration

🛠️ Usage

1. Initialize GoMigration

First, configure the library by providing a Config:

cfg := &gomigration.Config{
    Driver:             yourDriver,  // Must implement gomigration.Driver
    MigrationFilesDir:  "migrations",  // Optional: default is "migrations"
    MigrationTableName: "migrations",  // Optional: default is "migrations"
    DebugSql:           true,  // Optional: enables SQL debugging
}

q, err := gomigration.New(cfg)
if err != nil {
    log.Fatal(err)
}

2. Register Migrations

q.Register(
    migration1, // Must implement gomigration.Migration
    // Example
    &migrations.M20250418220011CreateUsersTable{},
)

Migration struct is created automatically when creating migration file.

3. Apply Migrations

To apply the migrations:

err := q.Migrate(context.Background())
if err != nil {
    log.Fatal(err)
}

4. Other Operations

• Create a new migration file:

  q.Create("add_users_table")
  

• Run fresh migrations (clean + migrate):

  q.Fresh(context.Background())
  

• Reset migrations (rollback all and reapply):

  q.Reset(context.Background())
  

• Rollback last n migrations:

  q.Rollback(context.Background(), 2)
  

• Clean the database:

  q.Clean(context.Background())
  

• List all registered migrations and their status:

  list, err := q.List(context.Background())
  

5. Set migration files directory before creating migration file

If you want to set migration files directory before creating migration file, you can use SetMigrationFilesDir method. This is useful when you want to dynamically set the migration files directory, e.g. passing it as a command-line argument.

q.SetMigrationFilesDir("migrations")
q.Create("add_users_table")

// or using chain
q.SetMigrationFilesDir("migrations").Create("add_users_table")

📁 Migration Interface

Each migration must implement the following interface:

type Migration interface {
    Name() string
    UpScript() string
    DownScript() string
}

🔌 Driver Interface

You can use any database driver that implements the Driver interface. We currently provide ready-to-use MySQL and Postgres drivers.

MySQL Driver

To use the MySQL driver:

d, err := gomigration.NewMySqlDriver(
    "localhost", // Host
    "3306",      // Port
    "root",      // Username
    "",          // Password
    "gomigration",    // Database Name
    "utf8mb4",   // Charset
)

Postgres Driver

To use the Postgres driver:

d, err := gomigration.NewPostgresDriver(
    "localhost", // Host
    "5432",      // Port
    "root",      // Username
    "",          // Password
    "gomigration",    // Database Name
    "public",    // Schema
)

📦 Generated Migration File Example

When you run q.Create("create_users_table"), a file like this will be created:

package migrations

type M20250418220011CreateUsersTable struct{}

func (m *M20250418220011CreateUsersTable) Name() string {
  // Don't change this name
	return "20250418220011_create_users_table"
}

func (m *M20250418220011CreateUsersTable) UpScript() string {
  // Write your migration SQL here
	return ""
}

func (m *M20250418220011CreateUsersTable) DownScript() string {
  // Write your rollback SQL here
	return ""
}

🧑‍💻 CLI Helper

GoMigration provides an optional CLI helper that simplifies running migrations and other tasks. You can use the CLI as follows:

1. Initialize the CLI

You can initialize the CLI with the CliConfig:

cli, err := gomigration.NewCli(gomigration.CliConfig{
    GoMigration: q,  // The GoMigration instance you've initialized earlier
})

if err != nil {
    log.Fatal(err)
}

err = cli.Execute(context.TODO())

if err != nil {
    log.Fatal(err)
}

2. Run CLI Commands

After setting up the CLI, you can run the following commands directly from the terminal:

• Clean database (delete all tables):

  go run main.go clean
  

• Create a new migration:

  go run main.go create
  

• List all migrations:

  go run main.go list
  

• Run all pending migrations:

  go run main.go migrate
  

• Rollback all migrations and re-run all migrations:

  go run main.go reset
  

• Rollback the last migration:

  go run main.go rollback
  

These commands are built into the CLI, making it easy to perform common migration tasks without having to write custom code each time.

3. Add Commands to Existing cobra.Command

var rootCmd = &cobra.Command{
    Use:   "migration",
    Short: "This is your existing cobra.Command",
    Run: func(cmd *cobra.Command, args []string) {
        cmd.Help()
    },
}

rootCmd.AddCommand(
    cli.ListCommand(ctx),
    cli.MigrateCommand(ctx),
    cli.RollbackCommand(ctx),
    cli.ResetCommand(ctx),
    cli.CleanCommand(ctx),
    cli.CreateCommand(ctx),
)

Full Example

package main

import (
	"context"
	"log"

	"github.com/openframebox/gomigration"
	"your_app/migrations"
)

func main() {
	d, err := gomigration.NewMySqlDriver(
		"localhost",
		"3306",
		"root",
		"",
		"gomigration",
		"utf8mb4",
	)

	if err != nil {
		log.Fatal(err)
	}
	q, err := gomigration.New(&gomigration.Config{
		Driver:             d,
		MigrationFilesDir:  "migrations",
		MigrationTableName: "migrations",
		DebugSql:           false,
	})

	if err != nil {
		log.Fatal(err)
	}

	err = q.Register(
		&migrations.M20250418220011CreateUsersTable{},
		&migrations.M20250418233018CreateRolesTable{},
	)

	if err != nil {
		log.Fatal(err)
	}

	cli, err := gomigration.NewCli(gomigration.CliConfg{
		GoMigration: q,
	})

	if err != nil {
		log.Fatal(err)
	}

	err = cli.Execute(context.TODO())

	if err != nil {
		log.Fatal(err)
	}
}

📄 License

MIT License