morph

README

A database migration tool designed to make schema migrations easy.

Morph

As an application evolves, the data flowing inside inevitably evolves along with it. If you have an application that persists the data in a relational database, the way you store the data will probably change over time. Morph is a database migration tool that helps you to apply your migrations. It is written with Go so you can use it from your Go application as well. Read our blog post to learn more about the motivation behind this project.

Usage

Morph can be used as a library or a CLI tool.

Library

import (
    "context"

    "github.com/mattermost/morph"
    "github.com/mattermost/morph/drivers/mysql"
    "github.com/mattermost/morph/sources/embedded"
)

src, err := embedded.WithInstance(&embedded.AssetSource{
    Names: []string{}, // add migration file names
    AssetFunc: func(name string) ([]byte, error) {
        return []byte{}, nil // should return the file contents
    },
})
if err != nil {
    return err
}
defer src.Close()

driver, err := mysql.WithInstance(db)
if err != nil {
    return err
}

engine, err := morph.New(context.Background(), driver, src)
if err != nil {
    return err
}
defer engine.Close()

engine.ApplyAll()

CLI

To install morph you can use:

go install github.com/mattermost/morph/cmd/morph@latest

Then you can apply your migrations like below:

morph apply up --driver postgres --dsn "postgres://user:pass@localhost:5432/mydb?sslmode=disable" --path ./db/migrations/postgres --number 1

Migration Files

The migrations files should have an up and down versions. The program requires each migration to be reversible, and the naming of the migration should be in the following form:

0000000001_create_user.up.sql
0000000001_create_user.down.sql

The first part will be used to determine the order in which the migrations should be applied and the next part until the up|down.sql suffix will be the migration name.

The program requires this naming convention to be followed as it saves the order and names of the migrations. Also, it can rollback migrations with the down files.

LICENSE

MIT

Documentation

Index

• Variables
• func SwapPlanDirection(plan *models.Plan)
• type Config
• type EngineOption
  • func SetDryRun(enable bool) EngineOption
  • func SetMigrationTableName(name string) EngineOption
  • func SetStatementTimeoutInSeconds(n int) EngineOption
  • func WithLock(key string) EngineOption
  • func WithLogger(logger Logger) EngineOption
• type Interceptor
• type Logger
• type Morph
  • func New(ctx context.Context, driver drivers.Driver, source sources.Source, ...) (*Morph, error)
  • func (m *Morph) AddInterceptor(version int, direction models.Direction, handler Interceptor)
  • func (m *Morph) Apply(limit int) (int, error)
  • func (m *Morph) ApplyAll() error
  • func (m *Morph) ApplyDown(limit int) (int, error)
  • func (m *Morph) ApplyPlan(plan *models.Plan) error
  • func (m *Morph) Close() error
  • func (m *Morph) Diff(mode models.Direction) ([]*models.Migration, error)
  • func (m *Morph) GeneratePlan(migrations []*models.Migration, auto bool) (*models.Plan, error)
  • func (m *Morph) GetOppositeMigrations(migrations []*models.Migration) ([]*models.Migration, error)
  • func (m *Morph) RemoveInterceptor(version int, direction models.Direction)

Variables

var (
	ErrorLogger      = color.New(color.FgRed, color.Bold)
	ErrorLoggerLight = color.New(color.FgRed)
	InfoLogger       = color.New(color.FgCyan, color.Bold)
	InfoLoggerLight  = color.New(color.FgCyan)
	SuccessLogger    = color.New(color.FgGreen, color.Bold)
)

Functions

func SwapPlanDirection

func SwapPlanDirection(plan *models.Plan)

SwapPlanDirection alters the plan direction to the opposite direction.

Types

type Config

type Config struct {
	Logger  Logger
	LockKey string
	DryRun  bool
}

type EngineOption

type EngineOption func(*Morph) error

func SetDryRun

func SetDryRun(enable bool) EngineOption

SetDryRun will not execute any migrations if set to true, but will still log the migrations that would be executed.

func SetMigrationTableName

func SetMigrationTableName(name string) EngineOption

func SetStatementTimeoutInSeconds

func SetStatementTimeoutInSeconds(n int) EngineOption

func WithLock

func WithLock(key string) EngineOption

WithLock creates a lock table in the database so that the migrations are guaranteed to be executed from a single instance. The key is used for naming the mutex.

func WithLogger

func WithLogger(logger Logger) EngineOption

type Interceptor

type Interceptor func() error

Interceptor is a handler function that being called just before the migration applied. If the interceptor returns an error, migration will be aborted.

type Logger

type Logger interface {
	Printf(format string, v ...interface{})
	Println(v ...interface{})
}

type Morph

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

func New

func New(ctx context.Context, driver drivers.Driver, source sources.Source, options ...EngineOption) (*Morph, error)

New creates a new instance of the migrations engine from an existing db instance and a migrations source. If the driver implements the Lockable interface, it will also wait until it has acquired a lock. The context is propagated to the drivers lock method (if the driver implements divers.Locker interface) and it can be used to cancel the lock acquisition.

func (*Morph) AddInterceptor

func (m *Morph) AddInterceptor(version int, direction models.Direction, handler Interceptor)

AddInterceptor registers a handler function to be executed before the actual migration

func (*Morph) Apply

func (m *Morph) Apply(limit int) (int, error)

Applies limited number of migrations upwards.

func (*Morph) ApplyAll

func (m *Morph) ApplyAll() error

ApplyAll applies all pending migrations.

func (*Morph) ApplyDown

func (m *Morph) ApplyDown(limit int) (int, error)

ApplyDown rollbacks a limited number of migrations if limit is given below zero, all down scripts are going to be applied.

func (*Morph) ApplyPlan

func (m *Morph) ApplyPlan(plan *models.Plan) error

func (*Morph) Close

func (m *Morph) Close() error

Close closes the underlying database connection of the engine.

func (*Morph) Diff

func (m *Morph) Diff(mode models.Direction) ([]*models.Migration, error)

Diff returns the difference between the applied migrations and the available migrations.

func (*Morph) GeneratePlan

func (m *Morph) GeneratePlan(migrations []*models.Migration, auto bool) (*models.Plan, error)

GeneratePlan returns the plan to apply these migrations and also includes the safe rollback steps for the given migrations.

func (*Morph) GetOppositeMigrations

func (m *Morph) GetOppositeMigrations(migrations []*models.Migration) ([]*models.Migration, error)

func (*Morph) RemoveInterceptor

func (m *Morph) RemoveInterceptor(version int, direction models.Direction)

RemoveInterceptor removes the handler function from the engine