source

Documentation

Index

• Variables
• func IsEmptyFile(m *Migration, directory string) (bool, error)
• func Register(name string, driver Driver)
• type Direction
• type Driver
  • func Open(url string, logger *log.Logger) (Driver, error)
• type Migration
  • func Parse(raw string) (*Migration, error)
  • func Parsev2(raw string) (*Migration, error)
• type Migrations
  • func NewMigrations() *Migrations
  • func (i *Migrations) Append(m *Migration) (err error)
  • func (i *Migrations) Down(version uint64) (m *Migration, ok bool)
  • func (i *Migrations) First() (version uint64, ok bool)
  • func (i *Migrations) GetDirections(version uint64) map[Direction]bool
  • func (i *Migrations) GetLocalVersion() uint64
  • func (i *Migrations) GetUnappliedMigrations(version uint64) (versions []uint64)
  • func (i *Migrations) MetaDown(version uint64) (m *Migration, ok bool)
  • func (i *Migrations) MetaUp(version uint64) (m *Migration, ok bool)
  • func (i *Migrations) Next(version uint64) (nextVersion uint64, ok bool)
  • func (i *Migrations) Prev(version uint64) (prevVersion uint64, ok bool)
  • func (i *Migrations) ReadName(version uint64) (name string)
  • func (i *Migrations) Up(version uint64) (m *Migration, ok bool)
• type Parser

Variables

var (
	DefaultParse   = Parse
	DefaultParsev2 = Parsev2
	DefaultRegex   = Regex
)

var (
	ErrParse = fmt.Errorf("no match")
)

var Regex = regexp.MustCompile(`^([0-9]+)_(.*)\.(` + string(Down) + `|` + string(Up) + `)\.(.*)$`)

Regex matches the following pattern:

123_name.up.ext
123_name.down.ext

var Regexv2 = regexp.MustCompile(`^([0-9]+)_(.*)\.(` + string(Down) + `|` + string(Up) + `)\.(sql)$`)

Functions

func IsEmptyFile

func IsEmptyFile(m *Migration, directory string) (bool, error)

Validate file to check for empty sql or yaml content.

func Register

func Register(name string, driver Driver)

Register globally registers a driver.

Types

type Direction

type Direction string

Direction is either up or down.

const (
	Down     Direction = "down"
	Up       Direction = "up"
	MetaDown Direction = "metadown"
	MetaUp   Direction = "metaup"
)

type Driver

type Driver interface {
	// Open returns a new driver instance configured with parameters
	// coming from the URL string. Migrate will call this function
	// only once per instance.
	Open(url string, logger *log.Logger) (Driver, error)

	// Close closes the underlying source instance managed by the driver.
	// Migrate will call this function only once per instance.
	Close() error

	// Scan scans the local migration files
	Scan() error

	// Default Parser to be used for scanning the file system
	DefaultParser(Parser)

	// First returns the very first migration version available to the driver.
	// Migrate will call this function multiple times.
	// If there is no version available, it must return os.ErrNotExist.
	First() (version uint64, err error)

	// GetLocalVersion returns the latest version available in migrations folder
	GetLocalVersion() (version uint64, err error)

	// Get all unapplied migrations present in local directory
	GetUnappliedMigrations(version uint64) (versions []uint64)

	// Prev returns the previous version for a given version available to the driver.
	// Migrate will call this function multiple times.
	// If there is no previous version available, it must return os.ErrNotExist.
	Prev(version uint64) (prevVersion uint64, err error)

	// Next returns the next version for a given version available to the driver.
	// Migrate will call this function multiple times.
	// If there is no next version available, it must return os.ErrNotExist.
	Next(version uint64) (nextVersion uint64, err error)

	GetDirections(version uint64) map[Direction]bool

	// ReadUp returns the UP migration body and an identifier that helps
	// finding this migration in the source for a given version.
	// If there is no up migration available for this version,
	// it must return os.ErrNotExist.
	// Do not start reading, just return the ReadCloser!
	ReadUp(version uint64) (r io.ReadCloser, identifier string, fileName string, err error)

	// ReadUp returns the UP migration body and an identifier that helps
	// finding this migration in the source for a given version.
	// If there is no up migration available for this version,
	// it must return os.ErrNotExist.
	// Do not start reading, just return the ReadCloser!
	ReadMetaUp(version uint64) (r io.ReadCloser, identifier string, fileName string, err error)

	// ReadDown returns the DOWN migration body and an identifier that helps
	// finding this migration in the source for a given version.
	// If there is no down migration available for this version,
	// it must return os.ErrNotExist.
	// Do not start reading, just return the ReadCloser!
	ReadDown(version uint64) (r io.ReadCloser, identifier string, fileName string, err error)

	// ReadDown returns the DOWN migration body and an identifier that helps
	// finding this migration in the source for a given version.
	// If there is no down migration available for this version,
	// it must return os.ErrNotExist.
	// Do not start reading, just return the ReadCloser!
	ReadMetaDown(version uint64) (r io.ReadCloser, identifier string, fileName string, err error)

	// ReadName returns an name that helps
	// finding this migration in the source for a given version
	ReadName(version uint64) (name string)
}

Driver is the interface every source driver must implement.

How to implement a source driver?

1. Implement this interface.
2. Optionally, add a function named `WithInstance`. This function should accept an existing source instance and a Config{} struct and return a driver instance.
3. Add a test that calls source/testing.go:Test()
4. Add own tests for Open(), WithInstance() (when provided) and Close(). All other functions are tested by tests in source/testing. Saves you some time and makes sure all source drivers behave the same way.
5. Call Register in init().

Guidelines:

• All configuration input must come from the URL string in func Open() or the Config{} struct in WithInstance. Don't os.Getenv().
• Drivers are supposed to be read only.
• Ideally don't load any contents (into memory) in Open or WithInstance.

func Open

func Open(url string, logger *log.Logger) (Driver, error)

Open returns a new driver instance.

type Migration

type Migration struct {
	// Version is the version of this migration.
	Version uint64

	// Identifier can be any string that helps identifying
	// this migration in the source.
	Identifier string

	// Direction is either Up or Down.
	Direction Direction

	// Raw holds the raw location path to this migration in source.
	// ReadUp and ReadDown will use this.
	Raw string

	// Check if the file exists in a directory
	IsDir bool
}

Migration is a helper struct for source drivers that need to build the full directory tree in memory. Migration is fully independent from migrate.Migration.

func Parse

func Parse(raw string) (*Migration, error)

Parse returns Migration for matching Regex pattern.

func Parsev2

func Parsev2(raw string) (*Migration, error)

Parsev2 returns Migration for matching Regex (only sql) pattern.

type Migrations

type Migrations struct {
	Index      uint64Slice
	Migrations map[uint64]map[Direction]*Migration
}

Migrations wraps Migration and has an internal index to keep track of Migration order.

func NewMigrations

func NewMigrations() *Migrations

func (*Migrations) Append

func (i *Migrations) Append(m *Migration) (err error)

func (*Migrations) Down

func (i *Migrations) Down(version uint64) (m *Migration, ok bool)

func (*Migrations) First

func (i *Migrations) First() (version uint64, ok bool)

func (*Migrations) GetDirections

func (i *Migrations) GetDirections(version uint64) map[Direction]bool

func (*Migrations) GetLocalVersion

func (i *Migrations) GetLocalVersion() uint64

func (*Migrations) GetUnappliedMigrations

func (i *Migrations) GetUnappliedMigrations(version uint64) (versions []uint64)

func (*Migrations) MetaDown

func (i *Migrations) MetaDown(version uint64) (m *Migration, ok bool)

func (*Migrations) MetaUp

func (i *Migrations) MetaUp(version uint64) (m *Migration, ok bool)

func (*Migrations) Next

func (i *Migrations) Next(version uint64) (nextVersion uint64, ok bool)

func (*Migrations) Prev

func (i *Migrations) Prev(version uint64) (prevVersion uint64, ok bool)

func (*Migrations) ReadName

func (i *Migrations) ReadName(version uint64) (name string)

func (*Migrations) Up

func (i *Migrations) Up(version uint64) (m *Migration, ok bool)

type Parser

type Parser func(raw string) (*Migration, error)

Parser to parse source files