migrate

README

Go migrations

A very simple migration library for your Go projects.

Features

• Any database/sql compatible drivers should work. See https://github.com/golang/go/wiki/SQLDrivers

• Each migration is run in a transaction so there should be no 'dirty' state.

• Only migrates "up". I have never used a "down" migration.

• Enables a callback function to suit whatever logging implementation you choose.

• Supports Go1.16's io/fs interface for embedded migrations.

Example usage

import "src.userspace.com.au/migrate"
// or import "github.com/felix/migrate"

db, err := sql.Open("pgx", uri)
//db, err := sql.Open("sqlite3", uri)
if err != nil {
    return err
}
defer db.Close()

// Relative path to migration files
migrator, err := migrate.NewFileMigrator(db, "file://migrations/")
if err != nil {
    return fmt.Errorf("failed to create migrator: %s", err)
}

// Migrate all the way
err = migrator.Migrate()
if err != nil {
    return fmt.Errorf("failed to migrate: %s", err)
}

v, err := migrator.Version()
fmt.Printf("database at version %d\n", v)

Documentation

Index

• Constants
• type Migration
• type Migrator
  • func NewFSMigrator(db *sql.DB, fs fs.ReadDirFS, opts ...Option) (*Migrator, error)
  • func NewFileMigrator(db *sql.DB, path string, opts ...Option) (*Migrator, error)
  • func NewStringMigrator(db *sql.DB, src []string, opts ...Option) (*Migrator, error)
  • func (m *Migrator) Migrate() error
  • func (m *Migrator) MigrateTo(toVersion int) error
  • func (m *Migrator) Version() (int, error)
• type Option
  • func SetCallback(cb ResultFunc) Option
  • func SetVersionTable(vt string) Option
• type ResultFunc

Examples

• NewFSMigrator
• NewFileMigrator
• NewStringMigrator

Constants

const (
	// NilVersion is a Claytons version
	// "the version you are at when you are not at a version"
	NilVersion = -1
)

Types

type Migration

type Migration interface {
	// The version of this migration
	Version() int
	// Run the migration
	Run(*sql.Tx) error
}

Migration interface

type Migrator

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

A Migrator collates and runs migrations

func NewFSMigrator

func NewFSMigrator(db *sql.DB, fs fs.ReadDirFS, opts ...Option) (*Migrator, error)

Example

package main

import (
	"database/sql"
	"embed"
	"fmt"

	"src.userspace.com.au/migrate"
)

func main() {
	//go:embed testdata/*.sql
	var migrations embed.FS

	db, err := sql.Open("sqlite3", "file:test?mode=memory&cache=shared")
	if err != nil {
		fmt.Printf("error: %s\n", err)
	}
	defer db.Close()

	// Relative path to migration files
	migrator, err := migrate.NewFSMigrator(db, migrations)
	if err != nil {
		fmt.Printf("error: %s\n", err)
	}

	// Migrate all the way
	err = migrator.Migrate()
	if err != nil {
		fmt.Printf("error: %s\n", err)
	}

	v, err := migrator.Version()
	fmt.Printf("database at version %d\n", v)
}

Output:

database at version 2

func NewFileMigrator

func NewFileMigrator(db *sql.DB, path string, opts ...Option) (*Migrator, error)

NewFileMigrator creates a new set of migrations from a path Each one is run in a transaction.

Example

package main

import (
	"database/sql"
	"fmt"

	"src.userspace.com.au/migrate"
)

func main() {
	db, err := sql.Open("sqlite3", "file:test?mode=memory&cache=shared")
	if err != nil {
		fmt.Printf("error: %s\n", err)
	}
	defer db.Close()

	// Relative path to migration files
	migrator, err := migrate.NewFileMigrator(db, "file://testdata/")
	if err != nil {
		fmt.Printf("error: %s\n", err)
	}

	// Migrate all the way
	err = migrator.Migrate()
	if err != nil {
		fmt.Printf("error: %s\n", err)
	}

	v, err := migrator.Version()
	fmt.Printf("database at version %d\n", v)
}

Output:

database at version 2

func NewStringMigrator

func NewStringMigrator(db *sql.DB, src []string, opts ...Option) (*Migrator, error)

NewStringMigrator creates a new set of migrations from a slice of strings Each one is run in a transaction.

Example

package main

import (
	"database/sql"
	"fmt"

	"src.userspace.com.au/migrate"
)

func main() {

	migrations := []string{
		"create table if not exists test1 (pk bigint not null primary key);",
		"insert into test1 (pk) values (1)",
	}

	db, err := sql.Open("sqlite3", "file:test?mode=memory&cache=shared")
	if err != nil {
		fmt.Printf("error: %s\n", err)
	}
	defer db.Close()

	// Relative path to migration files
	migrator, err := migrate.NewStringMigrator(db, migrations)
	if err != nil {
		fmt.Printf("error: %s\n", err)
	}

	// Migrate all the way
	err = migrator.Migrate()
	if err != nil {
		fmt.Printf("error: %s\n", err)
	}

	v, err := migrator.Version()
	fmt.Printf("database at version %d\n", v)
}

Output:

database at version 2

func (*Migrator) Migrate

func (m *Migrator) Migrate() error

Migrate migrates the database to the highest possible version

func (*Migrator) MigrateTo

func (m *Migrator) MigrateTo(toVersion int) error

MigrateTo migrates the database to the specified version

func (*Migrator) Version

func (m *Migrator) Version() (int, error)

Version reports the current version of the database

type Option

type Option func(*Migrator) error

An Option configures a migrator

func SetCallback

func SetCallback(cb ResultFunc) Option

SetCallback configures the table used for recording the schema version

func SetVersionTable

func SetVersionTable(vt string) Option

SetVersionTable configures the table used for recording the schema version

type ResultFunc

type ResultFunc func(int, int, error)

ResultFunc is the callback signature