migrate

README

Gorm database migration

Simple library to take advantage of the gorm's migration API.

Choices

• It only applies migrations. It's up to you to chose when to apply each operation.
• Any failure cancels every single change (including the one to the migrations listing table)
• There are no consistency checks between migrations. ALl migrations will be applied as long as they are after the current migration.

Known issues

• The column dropping operation doesn't work in SQLite because this library performs all the changes within a transaction, and the SQLite Migrator's DropColumn works by creating a transaction in pure-SQL with a BEGIN when a sub-transaction using a SAVEPOINT is necessary here.

How to use

import (
	"gorm.io/gorm"
	migrate "github.com/fclairamb/gorm-migrate"
)

func performMigrations(db *gorm.DB) error {
    
    steps := []*migrate.MigrationStep{
        {
            Name: "2020-09-12 01:00",
            Up: func(db *gorm.DB) error {
                return db.Migrator().AutoMigrate(&User{})
            },
            Down: func(db *gorm.DB) error {
                if db.Migrator().HasTable(&User{}) {
                    return db.Migrator().DropTable(&User{})
                }
                return nil
            },
        },
        {
            Name: "2020-09-12 02:00",
            Up: func(db *gorm.DB) error {
                return nil
            },
            Down: func(db *gorm.DB) error {
                return nil
            },
        },
    }
    
    if nb, err := migrate.Migrate(db, steps, migrate.UpFull); err != nil {
        return err
    } else if nb > 0 {
        log.Printf("Performed %d migrations !\n", nb)
    }
    return nil
}

Documentation

Overview

Package migrate allows to easily manage database migration with gorm v2

Index

• Constants
• Variables
• func Migrate(db *gorm.DB, steps Migrations, direction int) (int, error)
• func ValidateSteps(db *gorm.DB, steps Migrations, dual bool) error
• type ErrBadMigration
  • func (e *ErrBadMigration) Error() string
• type MigrationMethod
• type MigrationStep
• type Migrations

Constants

const (
	// StepIssueUpMissing means the issue is a missing upgrade method.
	StepIssueUpMissing = "up_missing"

	// StepIssueDownMissing means the issue is a missing downgrade method.
	StepIssueDownMissing = "down_missing"

	// StepIssueBadlyOrdered means the issue is badly ordered.
	StepIssueBadlyOrdered = "badly_ordered"
)

const (
	// UpFull is a complete upgrade migration.
	UpFull = 100000
	// DownFull is a complete downgrade migration.
	DownFull = -100000
	// UpOne is a single upgrade migration.
	UpOne = 1
	// DownOne is a single downgrade migration.
	DownOne = -1
)

Variables

var (
	// ErrBadDirection is returned when the direction is equal to 0.
	ErrBadDirection = fmt.Errorf("bad direction")

	// ErrInconsistentSteps is returned when we couldn't apply all the migration steps ups & downs.
	ErrInconsistentSteps = fmt.Errorf("inconsistent steps")
)

Functions

func Migrate

func Migrate(db *gorm.DB, steps Migrations, direction int) (int, error)

Migrate handles all the step of the migration steps.

func ValidateSteps

func ValidateSteps(db *gorm.DB, steps Migrations, dual bool) error

ValidateSteps validates that all the steps can be applied up & down.

Types

type ErrBadMigration

type ErrBadMigration struct {
	Name string // Name of the migration that has an issue
	Type string // Type of the issue
}

ErrBadMigration is reported when a migration has a bad definition.

func (*ErrBadMigration) Error

func (e *ErrBadMigration) Error() string

type MigrationMethod

type MigrationMethod func(db *gorm.DB) error

MigrationMethod declares the method we want to apply to the database.

type MigrationStep

type MigrationStep struct {
	Name string          // Name is the name of the migration
	Up   MigrationMethod // Up is the upgrade migration method
	Down MigrationMethod // Down is the downgrade migration method
}

MigrationStep declares a migration.

type Migrations

type Migrations []*MigrationStep

Migrations contains the migration steps we want to apply.