xormigrate

README

Xormigrate

Supported databases

It supports any of the databases Xorm supports:

• PostgreSQL
• MySQL
• SQLite
• Microsoft SQL Server
• Full list of supported drivers...

Installing

go get -u github.com/sfere-elec/xormigrate

Usage

package main

import (
	"log"

	"github.com/sfere-elec/xormigrate"

	"xorm.io/xorm"
	_ "github.com/mattn/go-sqlite3"
)

func main() {
	db, err := xorm.NewEngine("sqlite3", "mydb.sqlite3")
	if err != nil {
		log.Fatal(err)
	}

	m := xormigrate.New(db.NewSession(), &Options{
			TableName:                 "migration",
			UseTransaction:            true,
			ValidateUnknownMigrations: true,
		}, []*xormigrate.Migration{
		// create persons table
		{
			ID: "201608301400",
			Migrate: func(tx *xorm.Session) error {
				// it's a good pratice to copy the struct inside the function,
				// so side effects are prevented if the original struct changes during the time
				type Person struct {
					Name string
				}
				return tx.Sync2(&Person{})
			},
			Rollback: func(tx *xorm.Session) error {
				return tx.DropTables(&Person{})
			},
		},
		// add age column to persons
		{
			ID: "201608301415",
			Migrate: func(tx *xorm.Session) error {
				// when table already exists, it just adds fields as columns
				type Person struct {
					Age int
				}
				return tx.Sync2(&Person{})
			},
			Rollback: func(tx *xorm.Session) error {
				// Note: Column dropping in sqlite is not support, and you will need to do this manually
				_, err = tx.Exec("ALTER TABLE person DROP COLUMN age")
				if err != nil {
					return fmt.Errorf("Drop column failed: %v", err)
				}
				return nil
			},
		},
		// add pets table
		{
			ID: "201608301430",
			Migrate: func(tx *xorm.Session) error {
				type Pet struct {
					Name     string
					PersonID int
				}
				return tx.Sync2(&Pet{})
			},
			Rollback: func(tx *xorm.Session) error {
				return tx.DropTables(&Pet{})
			},
		},
	})

	if err = m.Migrate(); err != nil {
		log.Fatalf("Could not migrate: %v", err)
	}
	log.Printf("Migration did run successfully")
}

Having a separated function for initializing the schema

If you have a lot of migrations, it can be a pain to run all them, as example, when you are deploying a new instance of the app, in a clean database. To prevent this, you can set a function that will run if no migration was run before (in a new clean database). Remember to create everything here, all tables, foreign keys and what more you need in your app.

type Person struct {
	Name string
	Age int
}

type Pet struct {
	Name     string
	PersonID int
}

m := xormigrate.New(db.NewSession(), []*xormigrate.Migration{
    // your migrations here
})

m.InitSchema(func(tx *xorm.Session) error {
	err := tx.sync2(
		&Person{},
		&Pet{},
		// all other tables of your app
	)
	if err != nil {
		return err
	}
	return nil
})

Credits

• Based on Gormigrate v2
• Uses Xorm

Documentation

Index

• Variables
• type DuplicatedIDError
  • func (e *DuplicatedIDError) Error() string
• type InitSchemaFunc
• type MigrateFunc
• type Migration
• type Options
• type ReservedIDError
  • func (e *ReservedIDError) Error() string
• type RollbackFunc
• type Xormigrate
  • func New(session *xorm.Session, options *Options, migrations []*Migration) *Xormigrate
  • func (x *Xormigrate) InitSchema(initSchema InitSchemaFunc)
  • func (x *Xormigrate) Migrate() error
  • func (x *Xormigrate) MigrateTo(migrationID string) error
  • func (x *Xormigrate) RollbackLast() error
  • func (x *Xormigrate) RollbackMigration(m *Migration) error
  • func (x *Xormigrate) RollbackTo(migrationID string) error

Variables

var (
	// DefaultOptions can be used if you don't want to think about options.
	DefaultOptions = &Options{
		TableName:                 "migrations",
		UseTransaction:            false,
		ValidateUnknownMigrations: false,
	}

	// ErrRollbackImpossible is returned when trying to rollback a migration
	// that has no rollback function.
	ErrRollbackImpossible = errors.New("xormigrate: It's impossible to rollback this migration")

	// ErrNoMigrationDefined is returned when no migration is defined.
	ErrNoMigrationDefined = errors.New("xormigrate: No migration defined")

	// ErrMissingID is returned when the ID od migration is equal to ""
	ErrMissingID = errors.New("xormigrate: Missing ID in migration")

	// ErrNoRunMigration is returned when any run migration was found while
	// running RollbackLast
	ErrNoRunMigration = errors.New("xormigrate: Could not find last run migration")

	// ErrMigrationIDDoesNotExist is returned when migrating or rolling back to a migration ID that
	// does not exist in the list of migrations
	ErrMigrationIDDoesNotExist = errors.New("xormigrate: Tried to migrate to an ID that doesn't exist")

	// ErrUnknownPastMigration is returned if a migration exists in the DB that doesn't exist in the code
	ErrUnknownPastMigration = errors.New("xormigrate: Found migration in DB that does not exist in code")
)

Types

type DuplicatedIDError

type DuplicatedIDError struct {
	ID string
}

DuplicatedIDError is returned when more than one migration have the same ID

func (*DuplicatedIDError) Error

func (e *DuplicatedIDError) Error() string

type InitSchemaFunc

type InitSchemaFunc func(*xorm.Session) error

InitSchemaFunc is the func signature for initializing the schema.

type MigrateFunc

type MigrateFunc func(*xorm.Session) error

MigrateFunc is the func signature for migratinx.

type Migration

type Migration struct {
	// ID is the migration identifier. Usually a timestamp like "201601021504".
	ID string `xorm:"VARCHAR(50) notnull pk 'id'"`
	// Migrate is a function that will br executed while running this migration.
	Migrate MigrateFunc `xorm:"-"`
	// Rollback will be executed on rollback. Can be nil.
	Rollback RollbackFunc `xorm:"-"`
}

Migration represents a database migration (a modification to be made on the database).

type Options

type Options struct {
	// TableName is the migration table.
	TableName string
	// UseTransaction makes Gormigrate execute migrations inside a single transaction.
	// Keep in mind that not all databases support DDL commands inside transactions.
	UseTransaction bool
	// ValidateUnknownMigrations will cause migrate to fail if there's unknown migration
	// IDs in the database
	ValidateUnknownMigrations bool
}

Options define options for all migrations.

type ReservedIDError

type ReservedIDError struct {
	ID string
}

ReservedIDError is returned when a migration is using a reserved ID

func (*ReservedIDError) Error

func (e *ReservedIDError) Error() string

type RollbackFunc

type RollbackFunc func(*xorm.Session) error

RollbackFunc is the func signature for rollbackinx.

type Xormigrate

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

Xormigrate represents a collection of all migrations of a database schema.

func New

func New(session *xorm.Session, options *Options, migrations []*Migration) *Xormigrate

New returns a new Xormigrate.

func (*Xormigrate) InitSchema

func (x *Xormigrate) InitSchema(initSchema InitSchemaFunc)

InitSchema sets a function that is run if no migration is found. The idea is preventing to run all migrations when a new clean database is being migratinx. In this function you should create all tables and foreign key necessary to your application.

func (*Xormigrate) Migrate

func (x *Xormigrate) Migrate() error

Migrate executes all migrations that did not run yet.

func (*Xormigrate) MigrateTo

func (x *Xormigrate) MigrateTo(migrationID string) error

MigrateTo executes all migrations that did not run yet up to the migration that matches `migrationID`.

func (*Xormigrate) RollbackLast

func (x *Xormigrate) RollbackLast() error

RollbackLast undo the last migration

func (*Xormigrate) RollbackMigration

func (x *Xormigrate) RollbackMigration(m *Migration) error

RollbackMigration undo a migration.

func (*Xormigrate) RollbackTo

func (x *Xormigrate) RollbackTo(migrationID string) error

RollbackTo undoes migrations up to the given migration that matches the `migrationID`. Migration with the matching `migrationID` is not rolled back.