migrate

README

go-migrate

Stupidly simple SQL migrations

Migrations should be packages with your binary, so why not codify them!

Example migration

//your-package/migrations/2020_09_21_115238_create_users_table.go
package migrations

import (
	"database/sql"
	"time"

	"github.com/tcfw/go-migrate"
)

func init() {
	register(migrate.NewSimpleMigration(
		//Migration name to use in DB
		"create_users_table",

		//Timestamp of migration
		time.Date(2020, 9, 21, 11, 52, 38, 0, time.Local),

		//Up
		func(tx *sql.Tx) error {
			_, err := tx.Exec(`CREATE TABLE users (
				id UUID PRIMARY KEY,
				email string
			)`)
			return err
		},

		//Down
		func(tx *sql.Tx) error {
			_, err := tx.Exec(`DROP TABLE users`)
			return err
		},
	))
}

//your-package/migrations/migrations.go
package migrations

import (
	"database/sql"
	"github.com/sirupsen/logrus"
	"github.com/tcfw/go-migrate"
)

//migs List of known migrations
var migs migrate.MigrationList = migrate.MigrationList{}

//register helper to register migrations from init
func register(mig migrate.Migration) {
	migs = append(migs, mig)
}

//Migrate runs migrations up (run in main or init)
func Migrate(db *sql.DB, log *logrus.Logger) error {
	return migrate.Migrate(db, log, migs)
}

Notes

• File names are irrelevant which is why name and date are in the migration struct (possibly fix in future)
• There's no auto migrate down like there is for up as increments aren't stored in groups (like in for example Laravel migrations in PHP) and it is assumed that if you are migrating down, it should probably be a manual process anyway
• There is no DB table locking.
• Any failures rollback the TX of the total increment over multiple migrations

Documentation

Index

• func Migrate(db *sql.DB, log *logrus.Logger, migs []Migration) error
• type Migration
• type MigrationIncrement
• type MigrationList
  • func (ml MigrationList) Len() int
  • func (ml MigrationList) Less(i, j int) bool
  • func (ml MigrationList) Swap(i, j int)
• type SimpleMigration
  • func NewSimpleMigration(name string, date time.Time, up, down MigrationIncrement) *SimpleMigration
  • func (tm *SimpleMigration) Date() time.Time
  • func (tm *SimpleMigration) Down(tx *sql.Tx) error
  • func (tm *SimpleMigration) Name() string
  • func (tm *SimpleMigration) Up(tx *sql.Tx) error

Functions

func Migrate

func Migrate(db *sql.DB, log *logrus.Logger, migs []Migration) error

Migrate runs all migration up increments in date order

Types

type Migration

type Migration interface {
	Up(*sql.Tx) error
	Down(*sql.Tx) error
	Date() time.Time
	Name() string
}

Migration holds both up and down increments for a single migration

type MigrationIncrement

type MigrationIncrement func(tx *sql.Tx) error

MigrationIncrement applies an increment to the DB

type MigrationList

type MigrationList []Migration

MigrationList a slice of migration

func (MigrationList) Len

func (ml MigrationList) Len() int

func (MigrationList) Less

func (ml MigrationList) Less(i, j int) bool

func (MigrationList) Swap

func (ml MigrationList) Swap(i, j int)

type SimpleMigration

type SimpleMigration struct {
	// contains filtered or unexported fields
}

SimpleMigration a simple struct where the up and down functions can be assigned by attributes

func NewSimpleMigration

func NewSimpleMigration(name string, date time.Time, up, down MigrationIncrement) *SimpleMigration

NewSimpleMigration helper func for quickly declaring a simple migration

func (*SimpleMigration) Date

func (tm *SimpleMigration) Date() time.Time

Date which the migration was created (not applied)

func (*SimpleMigration) Down

func (tm *SimpleMigration) Down(tx *sql.Tx) error

Down the rollback decrement

func (*SimpleMigration) Name

func (tm *SimpleMigration) Name() string

Name provides a human readable name

func (*SimpleMigration) Up

func (tm *SimpleMigration) Up(tx *sql.Tx) error

Up the apply increment