lightmigrate

README

LightMigrate - a lightweight database migration library

This library is heavily inspired by golang-migrate.

It currently lacks support for many database drivers and the CLI feature, this is still WIP.

But it is completely restructured to minimize the dependency footprint.

Currently Supported databases

• MongoDB

Usage example:

fsys := os.DirFS("/app/data") // Migration File Source Root (/app/data/migration-files)

source, err := NewFsSource(fsys, "migration-files")
if err != nil {
    t.Fatalf("unable to setup source: %v", err)
}
defer source.Close()

driver, err := test.NewMockDriver() // Database Driver (for example lightmigrate_mongo.NewDriver())
if err != nil {
    t.Fatalf("unable to setup driver: %v", err)
}
defer driver.Close()

migrator, err := NewMigrator(source, driver, WithVerboseLogging(true)) // The migrator instance
if err != nil {
    t.Fatalf("unable to setup migrator: %v", err)
}

err = migrator.Migrate(3) // Migrate to schema version 3
if err != nil {
    t.Fatalf("migration error: %v", err)
}

Documentation

Index

• Constants
• Variables
• type Direction
• type DriverError
  • func (e DriverError) Error() string
  • func (e DriverError) Unwrap() error
• type ErrDuplicateMigration
  • func (e ErrDuplicateMigration) Error() string
• type Logger
• type MigrationDriver
• type MigrationSource
  • func NewFsSource(fsys fs.FS, basePath string) (MigrationSource, error)
• type Migrator
  • func NewMigrator(source MigrationSource, driver MigrationDriver, opts ...MigratorOption) (Migrator, error)
• type MigratorOption
  • func WithLogger(logger Logger) MigratorOption
  • func WithVerboseLogging(verbose bool) MigratorOption

Constants

const NoMigrationVersion uint64 = 0

NoMigrationVersion is a constant for version 0.

Variables

var (
	// ErrDatabaseDirty is used to signal a dirty database.
	ErrDatabaseDirty = fmt.Errorf("database contains unsuccessful migration")
	// ErrNoChange is used to signal that no migration is necessary.
	ErrNoChange = fmt.Errorf("no change")
	// ErrVersionNotAllowed is used to signal that the version 0 is not a valid version.
	ErrVersionNotAllowed = fmt.Errorf("version 0 is not allowed")
)

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

ErrParse describes a filename parsing error.

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

Regex matches the following pattern:

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

Types

type Direction

type Direction string

Direction is either up or down.

const (
	// Down direction is used when migrations should be reverted.
	Down Direction = "down"
	// Up direction is the default direction for migrations.
	Up Direction = "up"
)

type DriverError

type DriverError struct {
	// Optional: the line number
	Line uint

	// Query is a query excerpt
	Query []byte

	// Msg is a useful/helping error message for humans
	Msg string

	// OrigErr is the underlying error
	OrigErr error
}

DriverError should be used for errors involving queries ran against the database

func (DriverError) Error

func (e DriverError) Error() string

func (DriverError) Unwrap

func (e DriverError) Unwrap() error

type ErrDuplicateMigration

type ErrDuplicateMigration struct {
	os.FileInfo
	// contains filtered or unexported fields
}

ErrDuplicateMigration is used to signal a duplicate migration file (with the same version number).

func (ErrDuplicateMigration) Error

func (e ErrDuplicateMigration) Error() string

Error implements error interface.

type Logger

type Logger interface {
	// Printf is like fmt.Printf
	Printf(format string, v ...interface{})
}

Logger is an interface so you can pass in your own logging implementation.

type MigrationDriver

type MigrationDriver interface {
	io.Closer

	// Lock should acquire a database lock so that only one migration process
	// can run at a time. Migrate will call this function before Run is called.
	// If the implementation can't provide this functionality, return nil.
	// Return database.ErrLocked if database is already locked.
	Lock() error

	// Unlock should release the lock. Migrate will call this function after
	// all migrations have been run.
	Unlock() error

	// GetVersion returns the currently active version and the database dirty state.
	// When no migration has been applied, it must return version NoMigrationVersion (0).
	// Dirty means, a previous migration failed and user interaction is required.
	GetVersion() (version uint64, dirty bool, err error)

	// SetVersion saves version and dirty state.
	// Migrate will call this function before and after each call to RunMigration.
	// version must be >= 1. 0 means NoMigrationVersion.
	SetVersion(version uint64, dirty bool) error

	// RunMigration applies a migration to the database. migration is guaranteed to be not nil.
	RunMigration(migration io.Reader) error

	// Reset deletes everything related to LightMigrate in the database.
	Reset() error
}

MigrationDriver is the interface every database driver must implement.

type MigrationSource

type MigrationSource interface {
	io.Closer

	// First returns the very first migration version available.
	// If there is no version available, it must return os.ErrNotExist.
	First() (version uint64, err error)

	// Prev returns the previous version for a given version.
	// 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.
	// If there is no next version available, it must return os.ErrNotExist.
	Next(version uint64) (nextVersion uint64, 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.
	ReadUp(version uint64) (r io.ReadCloser, identifier 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.
	ReadDown(version uint64) (r io.ReadCloser, identifier string, err error)
}

MigrationSource is the interface every migration source must implement.

func NewFsSource

func NewFsSource(fsys fs.FS, basePath string) (MigrationSource, error)

NewFsSource returns a new MigrationSource from io/fs#FS and a relative path.

type Migrator

type Migrator interface {
	Migrate(version uint64) error
}

Migrator is a generic interface that provides compatibility with golang-migrate migrator.

func NewMigrator

func NewMigrator(source MigrationSource, driver MigrationDriver, opts ...MigratorOption) (Migrator, error)

NewMigrator instantiates a new migrator.

type MigratorOption

type MigratorOption func(svc *migrator)

MigratorOption is a function that can be used within the migrator constructor to modify the migrator object.

func WithLogger

func WithLogger(logger Logger) MigratorOption

WithLogger sets the logging instance used by the migrator.

func WithVerboseLogging

func WithVerboseLogging(verbose bool) MigratorOption

WithVerboseLogging sets the verbose flag of the migrator.