migrataur

README

migrataur : a migration library for Go

migrataur is a simple and easy to understand library to manage database migrations in Go.

It exposes a simple API that you can use in your own application. A CLI is also at your disposal and was written using urfave/cli, have a look at the example to find out how to use it.

Documentation

Library

Documentation is available at godoc but here is a sneak peak:

package main

import (
  "database/sql"

  "github.com/YuukanOO/migrataur"
  adapter "github.com/YuukanOO/migrataur/adapters/sql"
  _ "github.com/lib/pq"
)

func main() {
  db, _ := sql.Open("postgres", "postgres://pqgotest:pqgotest@localhost/pqgotest?sslmode=disable")
  // In a real application, you should catch errors...
  defer db.Close()

  // Instantiates a new migrataur. Have a look at Options, almost everything is
  // configurable so it can be used for many backend
  instance := migrataur.New(adapter.WithDBAndOptions(db, adapter.DefaultTableName, "${i}"), migrataur.DefaultOptions)

  // Generates migration needed by the adapter, you should always call it ONCE
  // when starting a new project. The adapter will writes the migration that it
  // needs to work properly.
  instance.Init()

  // Creates a new migration and write it to the filesystem, the actual name will
  // be generated using the configurated SequenceGenerator and Extension
  instance.New("migration01")
  instance.New("migration02")
  instance.New("migration03")

  // Apply one
  instance.Migrate("migration01")
  // Or a range
  instance.Migrate("migration01..migration02")
  // Or every pending ones
  instance.MigrateToLatest()

  // Same for rollbacking
  instance.Rollback("migration02")
  instance.Rollback("migration02..migration01")
  instance.Reset()

  // Retrieve all migrations and if they were applied or not
  instance.GetAll()

  // If you want to remove migrations, call Remove. It will
  // rollback them and delete generated files.
  instance.Remove("migration03")
  instance.Remove("migration02..migration01")
}

Command

Check example.go. Run the docker-compose up -d to starts the database used to test and then go run example.go to check available commands.

But wait, how do I write migrations?

It depends on your instance configuration since you can override extension and up and down delimiters. The default configuration assumes an extension of .sql and contains something like this:

-- +migrataur up
create table Movies (
  ID int generated always as identity primary key,
  Name varchar(50)
);

insert into Movies (Name) values ('Film 1'), ('Film 2'), ('Film 3')
-- -migrataur up


-- +migrataur down
drop table Movies;
-- -migrataur down

Adapters

Adapters are what makes migrataur database agnostic. It's a simple interface to implement:

type Adapter interface {
	GetInitialMigration() (up, down string)
	MigrationApplied(migration *Migration) error
	MigrationRollbacked(migration *Migration) error
	Exec(command string) error
	GetAll() ([]*Migration, error)
}

For now, a generic sql adapter has been written. It you want to provide an adapter implementation, feel free to contribute!

Contributing

Contribution are much appreciated! Feel free to fork this project, pull requests are welcome.

Documentation

Overview

Package migrataur is a simple migration tool for the Go language. It's written as a library that needs an adapter to work. It has been build with simplicity in mind.

Index

• Variables
• func GetCurrentTimeFormatted() string
• type Adapter
• type Logger
• type MarshalOptions
• type Migrataur
  • func New(adapter Adapter, opts Options) *Migrataur
  • func (m *Migrataur) GetAll() ([]*Migration, error)
  • func (m *Migrataur) Init() (*Migration, error)
  • func (m *Migrataur) Migrate(rangeOrName string) ([]*Migration, error)
  • func (m *Migrataur) MigrateToLatest() ([]*Migration, error)
  • func (m *Migrataur) New(name string) (*Migration, error)
  • func (m *Migrataur) Printf(format string, args ...interface{})
  • func (m *Migrataur) Remove(rangeOrName string) ([]*Migration, error)
  • func (m *Migrataur) Reset() ([]*Migration, error)
  • func (m *Migrataur) Rollback(rangeOrName string) ([]*Migration, error)
• type Migration
  • func (m *Migration) HasBeenApplied() bool
  • func (m *Migration) IsInitial() bool
  • func (m *Migration) String() string
• type Options
  • func (opts Options) ExtendWith(other Options) Options

Variables

var DefaultMarshalOptions = MarshalOptions{
	UpStart:   "-- +migrataur up",
	UpEnd:     "-- -migrataur up",
	DownStart: "-- +migrataur down",
	DownEnd:   "-- -migrataur down",
}

DefaultMarshalOptions holds default marshal options for the migration used when writing or reading migration files to the filesystem.

var DefaultOptions = Options{
	Logger:               log.New(os.Stdout, "", log.LstdFlags),
	Directory:            "./migrations",
	Extension:            ".sql",
	InitialMigrationName: "createMigrationHistory",
	SequenceGenerator:    GetCurrentTimeFormatted,
	MarshalOptions:       DefaultMarshalOptions,
}

DefaultOptions represents the default migrataur options

Functions

func GetCurrentTimeFormatted

func GetCurrentTimeFormatted() string

GetCurrentTimeFormatted retrieves the current time formatted. It's used as the default sequence generator since a linux timestamp goes up to 2038 :)

Types

type Adapter

type Adapter interface {
	// GetInitialMigration retrieves the migration up and down code and is used to populate
	// the migrations history table.
	GetInitialMigration() (up, down string)
	// MigrationApplied is called when the migration has been successfully applied by the
	// adapter. This is where you should insert the migration in the history.
	MigrationApplied(migration *Migration) error
	// MigrationRollbacked is called when the migration has been successfully rolled back.
	// This is where you should remove the migration from the history.
	MigrationRollbacked(migration *Migration) error
	// Exec the given commands. This is call by Migrataur to apply or rollback a migration
	// with the corresponding code.
	Exec(command string) error
	// GetAll retrieves all migrations for this adapter
	GetAll() ([]*Migration, error)
}

Adapter is the interface needed to access the underlying database. This is where you should implements the desired behavior. Built-in adapters are found in the subpackage /adapters.

type Logger

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

	Fatal(...interface{})
	Fatalf(string, ...interface{})
	Fatalln(...interface{})

	Panic(...interface{})
	Panicf(string, ...interface{})
	Panicln(...interface{})
}

Logger is the interface to be implemented by a logger since golang does not exposes a common interface. This interface is taken from the logrus library.

type MarshalOptions

type MarshalOptions struct {
	UpStart   string
	UpEnd     string
	DownStart string
	DownEnd   string
}

MarshalOptions holds configuration for the migration marshaling & unmarshaling

type Migrataur

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

Migrataur represents an instance configurated for a particular use. This is the main object you will use.

func New

func New(adapter Adapter, opts Options) *Migrataur

New instantiates a new Migrataur instance for the given options

func (*Migrataur) GetAll

func (m *Migrataur) GetAll() ([]*Migration, error)

GetAll retrieve all migrations for the current instance. It will list applied and pending migrations

func (*Migrataur) Init

func (m *Migrataur) Init() (*Migration, error)

Init writes the initial migration provided by the adapter to create the needed migrations table, you should call it at the start of your project.

func (*Migrataur) Migrate

func (m *Migrataur) Migrate(rangeOrName string) ([]*Migration, error)

Migrate migrates the database and returns an array of effectively applied migrations (it will not contains those that were already applied. rangeOrName can be the exact migration name or a range such as <migration>..<another migration name>

func (*Migrataur) MigrateToLatest

func (m *Migrataur) MigrateToLatest() ([]*Migration, error)

MigrateToLatest migrates the database to the latest version

func (*Migrataur) New

func (m *Migrataur) New(name string) (*Migration, error)

New creates a new migration in the configured folder and returns the instance of the migration attached to the newly created file

func (*Migrataur) Printf

func (m *Migrataur) Printf(format string, args ...interface{})

Printf logs a message using the provided Logger if any

func (*Migrataur) Remove

func (m *Migrataur) Remove(rangeOrName string) ([]*Migration, error)

Remove one or many migrations given a name or a range. It will rollbacks them and delete needed files.

func (*Migrataur) Reset

func (m *Migrataur) Reset() ([]*Migration, error)

Reset resets the database to its initial state

func (*Migrataur) Rollback

func (m *Migrataur) Rollback(rangeOrName string) ([]*Migration, error)

Rollback inverts migrations and return an array of effectively rollbacked migrations (it will not contains those that were not applied).

type Migration

type Migration struct {
	Name string

	AppliedAt *time.Time
	// contains filtered or unexported fields
}

Migration represents a database migration, nothing more.

func (*Migration) HasBeenApplied

func (m *Migration) HasBeenApplied() bool

HasBeenApplied checks if the migration has already been applied in the database.

func (*Migration) IsInitial

func (m *Migration) IsInitial() bool

IsInitial checks if this migration appears to be the initial one. It is primarily used in adapters when you want to perform specific checks.

func (*Migration) String

func (m *Migration) String() string

type Options

type Options struct {
	Logger               Logger
	Directory            string
	Extension            string
	InitialMigrationName string
	SequenceGenerator    func() string
	MarshalOptions       MarshalOptions
}

Options represents migrataur options to give to an instance

func (Options) ExtendWith

func (opts Options) ExtendWith(other Options) Options

ExtendWith extends self with the given Options. It means that if a field is not present in this option, it will be replaced by the one in the other Options. This will not work for the Logger field since a user may want to not provide it.