migrationrunner

README

migrationrunner

migrationrunner is a golang package for managing and running data migrations.

A "migration" is defined as a series of one-time operations that need to be performed to set up a data solution. For example, in the case of a SQL database, a migration may create tables and insert some initial data.

A "data solution" is defined as the specific data storage being used. This may be a SQL or NoSQL database, cloud solution, some ad-hoc in-memory DB, floppy disk, or whatever floats your boat.

Usage

The runner is designed to work on an abstract level and is independent of the specific data solution being used. As long as the interfaces are implemented as specified, the migration algorithm should will work correctly.

View the GoDocs for specific interface and usage details, but in general three types will be needed to be implemented:

• Migration: this represents a single migration and implements the actual logic for running your migration
• MigrationRepository: this interface simply fetches a slice of Migrations to be run by the runner
• MigrationCRUD: this interface acts as a wrapper for your data solution enabling the runner to act abstractly

Once the interfaces have been implemented to adhere to your needs, the MigrationRunner struct can be created. Basic usage example:

func main() {
    crud := MyMigrationCRUD{} //your MigrationCRUD implementation
    repo := MyMigrationRepository{} //your MigrationRepository implementation

    runner := MigrationRunner{
        MigrationCRUD: crud,
        MigrationRepository: repo,
    }

    err := runner.MigrateUp()
    if err != nil {
        log.Fatal(err)
    }
}

Documentation

Index

• type Migration
• type MigrationCRUD
• type MigrationRepository
• type MigrationRunner
  • func (m MigrationRunner) MigrateDown() error
  • func (m MigrationRunner) MigrateUp() error
• type Migrator

Types

type Migration

type Migration struct {
	// The required timestamp string for the migration.
	// The format is arbitrary but must be orderable using standard string comparison.
	Timestamp string

	// An optional string that will be displayed alongside the timestamp in logs.
	Description string

	// Implementation of the Migrator interface.
	Migrator Migrator
}

Migration is a struct that represents a single migration.

type MigrationCRUD

type MigrationCRUD interface {
	// Setup performs setup operations needed before other CRUD operations can be used.
	// Returns any errors.
	//
	// For example, this method can create a migrations table if it does not already exist.
	Setup() error

	// CreateMigration creates a new migration with the given timestamp and returns any errors.
	CreateMigration(timestamp string) error

	// GetLatestTimestamp returns the latest timestamp of all migrations.
	// If no timestamps are found then hasLatest should be false, else it should be true.
	// Also returns any errors encountered.
	GetLatestTimestamp() (timestamp string, hasLatest bool, err error)

	// DeleteMigrationByTimestamp deletes the migration with the given timestamp and returns any errors.
	DeleteMigrationByTimestamp(timestamp string) error
}

MigrationCRUD is an interface for performing CRUD (Create, Read, Update, Delete) operations on a migration.

This interface should be implemented as a wrapper for your data solution.

type MigrationRepository

type MigrationRepository interface {
	// GetMigrations returns a slice of migrations to run.
	// This can be a hard coded list, or perhaps loaded from some other source.
	GetMigrations() []Migration
}

MigrationRepository is an interface for fetching the migrations to run.

type MigrationRunner

type MigrationRunner struct {
	// Implementation of the MigrationRepository interface that will fetch the migrations to run.
	MigrationRepository MigrationRepository

	// Implementation of the MigrationCRUD interface that will perform the CRUD operations on the data solution.
	MigrationCRUD MigrationCRUD
}

func (MigrationRunner) MigrateDown

func (m MigrationRunner) MigrateDown() error

MigrateDown runs the Down method for the migration whose timestamp matches the latest timestamp returned by MigrationCRUD.GetLatestTimestamp.

If there is no latest timestamp, an error will be returned. Will also return any other errors that are encountered.

func (MigrationRunner) MigrateUp

func (m MigrationRunner) MigrateUp() error

MigrateUp runs the Up method for all migrations returned by the MigrationRepository that are newer than the timestamp fetched by MigrationCRUD.GetLatestTimestamp. This will trigger a call to MigrationCRUD.CreateMigration for every one that's run.

If there is no latest timestamp, all migrations will be run.

If any errors are encountered, the whole function will be aborted and any migrations yet to run will not be run. Returns any such errors encountered.

type Migrator

type Migrator interface {
	// Up runs the migration and returns any errors.
	Up() error

	// Down runs the inverse migration and returns any errors.
	Down() error
}

Migrator is an interface for running a migration.

A new struct that implements this interface should be created for each migration. Any additional dependencies required to run your migrations can be added as fields to this struct.