gomigrate

README

gomigrate

A SQL database migration toolkit in Golang.

Supported databases

• PostgreSQL
• MariaDB
• MySQL
• Sqlite3

Usage

First import the package:

import "github.com/DavidHuie/gomigrate"

Given a database/sql database connection to a PostgreSQL database, db, and a directory to migration files, create a migrator:

migrator, _ := gomigrate.NewMigrator(db, gomigrate.Postgres{}, "./migrations")

You may also specify a specific logger to use, such as logrus:

migrator, _ := gomigrate.NewMigratorWithLogger(db, gomigrate.Postgres{}, "./migrations", logrus.New())

To migrate the database, run:

err := migrator.Migrate()

To rollback the last migration, run:

err := migrator.Rollback()

Migration files

Migration files need to follow a standard format and must be present in the same directory. Given "up" and "down" steps for a migration, create a file for each by following this template:

{{ id }}_{{ name }}_{{ "up" or "down" }}.sql

For a given migration, the id and name fields must be the same. The id field is an integer that corresponds to the order in which the migration should run relative to the other migrations.

id should not be 0 as that value is used for internal validations.

Example

If I'm trying to add a "users" table to the database, I would create the following two files:

1_add_users_table_up.sql

CREATE TABLE users();

1_add_users_table_down.sql

DROP TABLE users;

Copyright

Copyright (c) 2014 David Huie. See LICENSE.txt for further details.

Documentation

Index

• Constants
• Variables
• type Logger
• type Mariadb
• type Migratable
• type Migration
• type Migrator
  • func NewMigrator(db *sql.DB, adapter Migratable, migrationsPath string) (*Migrator, error)
  • func NewMigratorWithLogger(db *sql.DB, adapter Migratable, migrationsPath string, logger Logger) (*Migrator, error)
  • func (m *Migrator) ApplyMigration(migration *Migration, mType migrationType) error
  • func (m *Migrator) CreateMigrationsTable() error
  • func (m *Migrator) Migrate() error
  • func (m *Migrator) MigrationTableExists() (bool, error)
  • func (m *Migrator) Migrations(status int) []*Migration
  • func (m *Migrator) Rollback() error
  • func (m *Migrator) RollbackAll() error
  • func (m *Migrator) RollbackN(n int) error
• type Mysql
  • func (m Mysql) CreateMigrationTableSql() string
  • func (m Mysql) GetMigrationCommands(sql string) []string
  • func (m Mysql) GetMigrationSql() string
  • func (m Mysql) MigrationLogDeleteSql() string
  • func (m Mysql) MigrationLogInsertSql() string
  • func (m Mysql) SelectMigrationTableSql() string
• type Postgres
  • func (p Postgres) CreateMigrationTableSql() string
  • func (p Postgres) GetMigrationCommands(sql string) []string
  • func (p Postgres) GetMigrationSql() string
  • func (p Postgres) MigrationLogDeleteSql() string
  • func (p Postgres) MigrationLogInsertSql() string
  • func (p Postgres) SelectMigrationTableSql() string
• type SqlServer
  • func (s SqlServer) CreateMigrationTableSql() string
  • func (s SqlServer) GetMigrationCommands(sql string) []string
  • func (s SqlServer) GetMigrationSql() string
  • func (s SqlServer) MigrationLogDeleteSql() string
  • func (s SqlServer) MigrationLogInsertSql() string
  • func (s SqlServer) SelectMigrationTableSql() string
• type Sqlite3
  • func (s Sqlite3) CreateMigrationTableSql() string
  • func (s Sqlite3) GetMigrationCommands(sql string) []string
  • func (s Sqlite3) GetMigrationSql() string
  • func (s Sqlite3) MigrationLogDeleteSql() string
  • func (s Sqlite3) MigrationLogInsertSql() string
  • func (s Sqlite3) SelectMigrationTableSql() string

Constants

const (
	Inactive = iota
	Active
)

Migration statuses.

Variables

var (
	InvalidMigrationFile  = errors.New("Invalid migration file")
	InvalidMigrationPair  = errors.New("Invalid pair of migration files")
	InvalidMigrationsPath = errors.New("Invalid migrations path")
	InvalidMigrationType  = errors.New("Invalid migration type")
	NoActiveMigrations    = errors.New("No active migrations to rollback")
)

Types

type Logger

type Logger interface {
	Print(v ...interface{})
	Printf(format string, v ...interface{})
	Println(v ...interface{})
	Fatalf(format string, v ...interface{})
}

type Mariadb

type Mariadb struct {
	Mysql
}

type Migratable

type Migratable interface {
	SelectMigrationTableSql() string
	CreateMigrationTableSql() string
	GetMigrationSql() string
	MigrationLogInsertSql() string
	MigrationLogDeleteSql() string
	GetMigrationCommands(string) []string
}

type Migration

type Migration struct {
	DownPath string
	Id       uint64
	Name     string
	Status   int
	UpPath   string
}

Holds configuration information for a given migration.

type Migrator

type Migrator struct {
	DB             *sql.DB
	MigrationsPath string
	// contains filtered or unexported fields
}

func NewMigrator

func NewMigrator(db *sql.DB, adapter Migratable, migrationsPath string) (*Migrator, error)

Returns a new migrator.

func NewMigratorWithLogger

func NewMigratorWithLogger(db *sql.DB, adapter Migratable, migrationsPath string, logger Logger) (*Migrator, error)

Returns a new migrator with the specified logger.

func (*Migrator) ApplyMigration

func (m *Migrator) ApplyMigration(migration *Migration, mType migrationType) error

Applies a single migration.

func (*Migrator) CreateMigrationsTable

func (m *Migrator) CreateMigrationsTable() error

Creates the migrations table if it doesn't exist.

func (*Migrator) Migrate

func (m *Migrator) Migrate() error

Applies all inactive migrations.

func (*Migrator) MigrationTableExists

func (m *Migrator) MigrationTableExists() (bool, error)

Returns true if the migration table already exists.

func (*Migrator) Migrations

func (m *Migrator) Migrations(status int) []*Migration

Returns a sorted list of migration ids for a given status. -1 returns all migrations.

func (*Migrator) Rollback

func (m *Migrator) Rollback() error

Rolls back the last migration.

func (*Migrator) RollbackAll

func (m *Migrator) RollbackAll() error

Rolls back all migrations.

func (*Migrator) RollbackN

func (m *Migrator) RollbackN(n int) error

Rolls back N migrations.

type Mysql

type Mysql struct{}

func (Mysql) CreateMigrationTableSql

func (m Mysql) CreateMigrationTableSql() string

func (Mysql) GetMigrationCommands

func (m Mysql) GetMigrationCommands(sql string) []string

func (Mysql) GetMigrationSql

func (m Mysql) GetMigrationSql() string

func (Mysql) MigrationLogDeleteSql

func (m Mysql) MigrationLogDeleteSql() string

func (Mysql) MigrationLogInsertSql

func (m Mysql) MigrationLogInsertSql() string

func (Mysql) SelectMigrationTableSql

func (m Mysql) SelectMigrationTableSql() string

type Postgres

type Postgres struct{}

func (Postgres) CreateMigrationTableSql

func (p Postgres) CreateMigrationTableSql() string

func (Postgres) GetMigrationCommands

func (p Postgres) GetMigrationCommands(sql string) []string

func (Postgres) GetMigrationSql

func (p Postgres) GetMigrationSql() string

func (Postgres) MigrationLogDeleteSql

func (p Postgres) MigrationLogDeleteSql() string

func (Postgres) MigrationLogInsertSql

func (p Postgres) MigrationLogInsertSql() string

func (Postgres) SelectMigrationTableSql

func (p Postgres) SelectMigrationTableSql() string

type SqlServer

type SqlServer struct{}

func (SqlServer) CreateMigrationTableSql

func (s SqlServer) CreateMigrationTableSql() string

func (SqlServer) GetMigrationCommands

func (s SqlServer) GetMigrationCommands(sql string) []string

func (SqlServer) GetMigrationSql

func (s SqlServer) GetMigrationSql() string

func (SqlServer) MigrationLogDeleteSql

func (s SqlServer) MigrationLogDeleteSql() string

func (SqlServer) MigrationLogInsertSql

func (s SqlServer) MigrationLogInsertSql() string

func (SqlServer) SelectMigrationTableSql

func (s SqlServer) SelectMigrationTableSql() string

type Sqlite3

type Sqlite3 struct{}

func (Sqlite3) CreateMigrationTableSql

func (s Sqlite3) CreateMigrationTableSql() string

func (Sqlite3) GetMigrationCommands

func (s Sqlite3) GetMigrationCommands(sql string) []string

func (Sqlite3) GetMigrationSql

func (s Sqlite3) GetMigrationSql() string

func (Sqlite3) MigrationLogDeleteSql

func (s Sqlite3) MigrationLogDeleteSql() string

func (Sqlite3) MigrationLogInsertSql

func (s Sqlite3) MigrationLogInsertSql() string

func (Sqlite3) SelectMigrationTableSql

func (s Sqlite3) SelectMigrationTableSql() string