migrations

README

SQL migrations for Golang and PostgreSQL

This package allows you to run migrations on your PostgreSQL database using Golang Postgres client. See example for details.

Example

You need to create database pg_migrations_example before running this example.

> psql -c "CREATE DATABASE pg_migrations_example"
CREATE DATABASE

> go run *.go version
version is 0

> go run *.go
creating table my_table...
adding id column...
seeding my_table...
migrated from version 0 to 3

> go run *.go version
version is 3

> go run *.go reset
truncating my_table...
dropping id column...
dropping table my_table...
migrated from version 3 to 0

> go run *.go up 2
creating table my_table...
adding id column...
migrated from version 0 to 2

> go run *.go
seeding my_table...
migrated from version 2 to 3

> go run *.go down
truncating my_table...
migrated from version 3 to 2

> go run *.go version
version is 2

> go run *.go set_version 1
migrated from version 2 to 1

> go run *.go create add email to users
created migration 4_add_email_to_users.go

Registering Migrations

migrations.RegisterTx and migrations.MustRegisterTx

Registers migrations to be executed inside transactions.

migrations.Register and migrations.MustRegister

Registers migrations to be executed without any transaction.

Transactions

By default, the migrations are executed outside without any transactions. Individual migrations can however be marked to be executed inside transactions by using the RegisterTx function instead of Register.

Global Transactions

var oldVersion, newVersion int64

err := db.RunInTransaction(func(tx *pg.Tx) (err error) {
    oldVersion, newVersion, err = migrations.Run(tx, flag.Args()...)
    return
})
if err != nil {
    exitf(err.Error())
}

Documentation

Index

• func MustRegister(fns ...func(DB) error)
• func MustRegisterTx(fns ...func(DB) error)
• func Register(fns ...func(DB) error) error
• func RegisterTx(fns ...func(DB) error) error
• func Run(db DB, a ...string) (oldVersion, newVersion int64, err error)
• func RunMigrations(db DB, migrations []Migration, a ...string) (oldVersion, newVersion int64, err error)
• func SetTableName(name string)
• func SetVersion(db DB, version int64) error
• func Version(db DB) (int64, error)
• type DB
• type Migration
  • func RegisteredMigrations() []Migration
  • func (m *Migration) String() string

Functions

func MustRegister

func MustRegister(fns ...func(DB) error)

func MustRegisterTx

func MustRegisterTx(fns ...func(DB) error)

func Register

func Register(fns ...func(DB) error) error

Register registers new database migration. Must be called from file with name like "1_initialize_db.go", where:

• 1 - migration version;
• initialize_db - comment.

func RegisterTx

func RegisterTx(fns ...func(DB) error) error

RegisterTx is just like Register but marks the migration to be executed inside a transaction.

func Run

func Run(db DB, a ...string) (oldVersion, newVersion int64, err error)

Run runs command on the db. Supported commands are: - up [target] - runs all available migrations by default or up to target one if argument is provided. - down - reverts last migration. - reset - reverts all migrations. - version - prints current db version. - set_version - sets db version without running migrations.

func RunMigrations

func RunMigrations(db DB, migrations []Migration, a ...string) (oldVersion, newVersion int64, err error)

RunMigrations is like Run, but accepts list of migrations.

func SetTableName

func SetTableName(name string)

func SetVersion

func SetVersion(db DB, version int64) error

func Version

func Version(db DB) (int64, error)

Types

type DB

type DB = orm.DB

type Migration

type Migration struct {
	Version       int64
	Transactional bool
	Up            func(DB) error
	Down          func(DB) error
}

func RegisteredMigrations

func RegisteredMigrations() []Migration

RegisteredMigrations returns currently registered Migrations.

func (*Migration) String

func (m *Migration) String() string