migration

Documentation

Overview

Package migration includes migrations related structures and migrations registration related logic.

Index

• Constants
• Variables
• func GenerateBlankMigration(dirPath MigrationsDirPath) (fileName string, err error)
• type DirMigrationsRegistry
  • func NewDirMigrationsRegistry(dirPath MigrationsDirPath, allMigrations []Migration) *DirMigrationsRegistry
  • func NewEmptyDirMigrationsRegistry(dirPath MigrationsDirPath) *DirMigrationsRegistry
  • func (registry *DirMigrationsRegistry) AssertValidRegistry()
  • func (registry *DirMigrationsRegistry) HasAllMigrationsRegistered() (bool, []string, []string, error)
• type DummyMigration
  • func NewDummyMigration(version uint64) *DummyMigration
  • func (dm *DummyMigration) Down() error
  • func (dm *DummyMigration) Up() error
  • func (dm *DummyMigration) Version() uint64
• type GenericRegistry
  • func NewGenericRegistry() *GenericRegistry
  • func (registry *GenericRegistry) Count() int
  • func (registry *GenericRegistry) Get(version uint64) Migration
  • func (registry *GenericRegistry) OrderedMigrations() []Migration
  • func (registry *GenericRegistry) OrderedVersions() []uint64
  • func (registry *GenericRegistry) Register(migration Migration) error
• type Migration
• type MigrationsDirPath
  • func NewMigrationsDirPath(dirPath string) (MigrationsDirPath, error)
• type MigrationsRegistry

Constants

const FileNamePrefix = "version"

FileNamePrefix File name prefix, static value, which will be set for all migration files.

const FileNameSeparator = "_"

FileNameSeparator A separator used to separate words in a migration file.

Variables

var ErrBlankMigration = errors.New("could not generate blank migration")

ErrBlankMigration is a generic error for failing to create a blank migration

var ErrCreateMigrationsDirPath = errors.New("could not create new migrations directory path")

ErrCreateMigrationsDirPath is a generic error for the scenarios when the migrations directory path can't be created (for example, nonexistent directory in the file system).

var TmplContents string

TmplContents File template to be used to generate a new, base migration file to make it easier for devs to create new migrations.

Functions

func GenerateBlankMigration

func GenerateBlankMigration(dirPath MigrationsDirPath) (fileName string, err error)

GenerateBlankMigration generates a blank migration file in the specified directory Returns the generated file name Errors if template processing failed or file creation failed

Types

type DirMigrationsRegistry

type DirMigrationsRegistry struct {
	GenericRegistry
	// contains filtered or unexported fields
}

DirMigrationsRegistry is an implementation of MigrationsRegistry. It will include all migrations available in the specified directory (see struct builder function, there you can specify the used directory).

func NewDirMigrationsRegistry

func NewDirMigrationsRegistry(
	dirPath MigrationsDirPath,
	allMigrations []Migration,
) *DirMigrationsRegistry

NewDirMigrationsRegistry builds a migrations registry with all migrations available in the specified directory. Panics if it detects that allMigrations argument does not match with whatever migration files exist in the specified dirPath

func NewEmptyDirMigrationsRegistry

func NewEmptyDirMigrationsRegistry(dirPath MigrationsDirPath) *DirMigrationsRegistry

NewEmptyDirMigrationsRegistry builds an empty migrations registry which can be used for the use case where migrations are saved in a directory.

func (*DirMigrationsRegistry) AssertValidRegistry

func (registry *DirMigrationsRegistry) AssertValidRegistry()

AssertValidRegistry checks if there are any issues with the list of registered migrations and panics if it finds any

func (*DirMigrationsRegistry) HasAllMigrationsRegistered

func (registry *DirMigrationsRegistry) HasAllMigrationsRegistered() (
	bool, []string, []string, error,
)

HasAllMigrationsRegistered checks if everything from the migrations directory has been registered in the registry. If it returns false, next 2 return values show which file names are missing and which file names are extra, compare to the registered migrations. Errors if reading the directory fails (maybe insufficient permissions?)

type DummyMigration

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

DummyMigration struct that should be used only in tests

func NewDummyMigration

func NewDummyMigration(version uint64) *DummyMigration

func (*DummyMigration) Down

func (dm *DummyMigration) Down() error

func (*DummyMigration) Up

func (dm *DummyMigration) Up() error

func (*DummyMigration) Version

func (dm *DummyMigration) Version() uint64

type GenericRegistry

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

GenericRegistry is a generic implementation for MigrationsRegistry

func NewGenericRegistry

func NewGenericRegistry() *GenericRegistry

NewGenericRegistry creates a new, empty registry

func (*GenericRegistry) Count

func (registry *GenericRegistry) Count() int

func (*GenericRegistry) Get

func (registry *GenericRegistry) Get(version uint64) Migration

func (*GenericRegistry) OrderedMigrations

func (registry *GenericRegistry) OrderedMigrations() []Migration

func (*GenericRegistry) OrderedVersions

func (registry *GenericRegistry) OrderedVersions() []uint64

func (*GenericRegistry) Register

func (registry *GenericRegistry) Register(migration Migration) error

type Migration

type Migration interface {
	// Version must be a static, globally unique value which identifies the migration file
	// globally. It must match the value set in the file name. By default, this will be
	// the unix timestamp in seconds when the migration file was generated.
	Version() uint64

	// Up must include any code that will change the structure and/or state of your database.
	// Preferably, it should be idempotent and resilient. It should not use, set or modify
	// global state, to not impact other migration executions. You can have multiple migrations
	// Up() act as a unit, but, care should be taken when coordinating them (use save points
	// for example, and save them in a central place which can be used as a persistent
	// source of truth).
	Up() error

	// Down must include all necessary code that will roll back the changes made by the Up()
	// function. Care should be taken when designing your rollback strategy, to not lose any
	// critical database state. Other things mentioned for Up() function are valid for Down()
	// also.
	Down() error
}

Migration Represents the base behavior a migration should include

type MigrationsDirPath

type MigrationsDirPath string

MigrationsDirPath should be used, preferably, as a global, static value, to determine where the migration files are placed in the file system.

func NewMigrationsDirPath

func NewMigrationsDirPath(dirPath string) (MigrationsDirPath, error)

NewMigrationsDirPath can be used to create a new MigrationsDirPath

type MigrationsRegistry

type MigrationsRegistry interface {
	// Register must push a migration in the registry. It should fail with error if the
	// migration can't be registered, for example, it its version overlaps with an
	// already registered migration
	Register(migration Migration) error

	// OrderedVersions must return a list of all registered migration versions,
	// ordered in ascending order. Can be used to determine the order in which the migrations
	// should run.
	OrderedVersions() []uint64

	// OrderedMigrations must return a list of all registered migrations,
	// ordered in ascending order by using their version. Can be used to determine the
	// order in which the migrations should run.
	OrderedMigrations() []Migration

	// Get must find and return the migration from the registry, by using its version.
	Get(version uint64) Migration

	// Count must return the total number of registered migrations.
	Count() int
}

MigrationsRegistry allows implementations to manage a collection of migration files. Implementations should act as a single source for all created migrations.