gomigrate

README

Go SQL Migration Library

How To Use

basic usage

1, download

go get github.com/farseer810/gomigrate

2, get the migration executor you need(currently support MySQL)

executor := NewMySQLMigrateExecutor("user:password@tcp(host:port)/your_db?charset=utf8")

3, install migrations

migrations := []Migration{
  {
    Name:    "test_table1",
    Content: `create table if not exists test_table1(data text not null)`,
  },
  {
    Name:    "test_table2",
    Content: "create table if not exists test_table2(data text not null)",
  }
}
executor.SetMigrations(migrations)
executor.InstallMigrations()

show migrations

This idea comes from Django Web Framework. It shows problems in your migrations and schema table.

executor.SetMigrations(migrations)
executor.ShowMigrations()

and it prints out something like this:

+------+-------------+----------------+---------------------+--------------------+
| RANK | SCHEMA NAME | MIGRATION NAME | INSTALLED TIME      | STATUS             |
+------+-------------+----------------+---------------------+--------------------+
| 1    | test_table1 | test_table1    | 2021-04-03 07:52:58 | INSTALLED          |
| 2    | test_table2 | test_table2    | 2021-04-03 07:52:58 | INSTALLED          |
| -    |             | test_table3    | -                   | SCHEMA BROKEN      |
| 4    | test_table3 | test_table4    | 2021-04-03 07:52:58 | MIGRATION MODIFIED |
| 5    | test_table4 |                | 2021-04-03 07:52:58 | MIGRATION MISSING  |
| 6    | test_table5 |                | 2021-04-03 07:52:58 | MIGRATION MISSING  |
+------+-------------+----------------+---------------------+--------------------+
(1) to fix MIGRATION MISSING: provide the missing migrations
(2) to fix installed MIGRATION MODIFIED: recovery the installed but modified migrations. 
	Please DO NOT modify installed migrations
(3) to fix SCHEMA BROKEN: no cure (yet?:))

Flyway Style Migrations

We provide a way to parse flyway style migrations from file system or embed.FS

migrations, err := GetMigrationsFromFlywayDir("flyway_migrations_dir")
executor.SetMigrations(migrations)

or

//go:embed flyway_migrations_dir
var embedFS embed.FS

migrations, err := GetMigrationsFromFlywayEmbedFS(embedFS, flyway_migrations_dir)
executor.SetMigrations(migrations)

what is flyway style migrations

Here's an example:

V1__test_table1_migration_name.sql
V2__test_table4_migration_name.sql
v1_1__test_table2_migration_name.sql
V1_2__test_table3_migration_name.sql
v3_1__test_table5_migration_name.sql

To summarize, a valid migration file name must fit the following requirements:

• file name must start with letter 'V', case doesn't matter
• what comes after the leading letter 'V' is version number, which is either integer, or a decimal with its floating point replaced by underscore. version number determines the execution order of this migration
• an double underscore separates version number and migration name, both of them must be unique
• file name must end with ".sql", doesn't matter

So in the above example, the migrations will be executed in this order:

V1__test_table1_migration_name.sql
v1_1__test_table2_migration_name.sql
V1_2__test_table3_migration_name.sql
V2__test_table4_migration_name.sql
v3_1__test_table5_migration_name.sql

Ground Rules

• DO NOT TOUCH the SCHEMA HISTORY TABLE
• DO NOT MODIFY CONTENTS OF INSTALLED MIGRATIONS
• DO NOT INSERT NEW MIGRATIONS BETWEEN INSTALLED MIGRATIONS

Documentation

Index

• Variables
• type BaseExecutor
  • func (b *BaseExecutor) GetSchemaHistoryTableName() string
  • func (b *BaseExecutor) SetSchemaHistoryTableName(tableName string) error
• type MigrateStatus
• type Migration
  • func GetMigrationsFromFlywayDir(sourcePath string) ([]Migration, error)
  • func GetMigrationsFromFlywayEmbedFS(embedFS embed.FS, subDirPath string) ([]Migration, error)
  • func (m *Migration) GetContentHash() string
• type MigrationExecutor
  • func NewMySQLMigrateExecutor(connSource string) MigrationExecutor
• type MigrationVersion
  • func ParseMigrationVersion(version string) (MigrationVersion, error)
  • func (m MigrationVersion) String() string
• type SchemaHistory
• type SortableMigration
• type SortableMigrations
  • func (s SortableMigrations) Len() int
  • func (s SortableMigrations) Less(i, j int) bool
  • func (s SortableMigrations) Swap(i, j int)

Variables

var (
	ErrInitializeFail          = errors.New("failed to initialize")
	ErrBrokenSchemaHistory     = errors.New("broken schema history detected")
	ErrDuplicatedMigrationName = errors.New("duplicated migration name detected")
	ErrInvalidMigrations       = errors.New("invalid migrations")
	ErrMigrationMissing        = fmt.Errorf("%w(missing)", ErrInvalidMigrations)
	ErrMigrationModified       = fmt.Errorf("%w(modified)", ErrInvalidMigrations)
)

Types

type BaseExecutor

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

func (*BaseExecutor) GetSchemaHistoryTableName

func (b *BaseExecutor) GetSchemaHistoryTableName() string

func (*BaseExecutor) SetSchemaHistoryTableName

func (b *BaseExecutor) SetSchemaHistoryTableName(tableName string) error

type MigrateStatus

type MigrateStatus int

const (
	DefaultSchemaHistoryTableName = "gomigrate_schema_history"

	StatusUnknown MigrateStatus = iota
	StatusInstalled
	StatusReadyToInstall
	StatusMigrationMissing
	StatusMigrationModified
	StatusBrokenSchemaHistory
)

type Migration

type Migration struct {
	Name    string
	Content string
}

func GetMigrationsFromFlywayDir

func GetMigrationsFromFlywayDir(sourcePath string) ([]Migration, error)

func GetMigrationsFromFlywayEmbedFS

func GetMigrationsFromFlywayEmbedFS(embedFS embed.FS, subDirPath string) ([]Migration, error)

func (*Migration) GetContentHash

func (m *Migration) GetContentHash() string

type MigrationExecutor

type MigrationExecutor interface {
	GetSchemaHistoryTableName() string
	SetSchemaHistoryTableName(tableName string) error
	SetMigrations(migrations []Migration)
	InitSchemaHistoryTable() error
	ShowMigrations() error
	InstallMigrations() error
}

func NewMySQLMigrateExecutor

func NewMySQLMigrateExecutor(connSource string) MigrationExecutor

type MigrationVersion

type MigrationVersion []int

func ParseMigrationVersion

func ParseMigrationVersion(version string) (MigrationVersion, error)

func (MigrationVersion) String

func (m MigrationVersion) String() string

type SchemaHistory

type SchemaHistory struct {
	Migration
	Rank          int
	InstalledTime time.Time
}

type SortableMigration

type SortableMigration struct {
	M       *Migration
	Version []int
}

type SortableMigrations

type SortableMigrations []*SortableMigration

func (SortableMigrations) Len

func (s SortableMigrations) Len() int

func (SortableMigrations) Less

func (s SortableMigrations) Less(i, j int) bool

func (SortableMigrations) Swap

func (s SortableMigrations) Swap(i, j int)