migrate

README

Migrate

A simple database migration tool using an sql.DB connection and fs.FS for the migration source. It has no non-test dependencies.

Made in 🇩🇰 by maragu, maker of online Go courses.

Features

• Simple: The common usage is a one-liner.
• Safe: Each migration is run in a transaction, and automatically rolled back on errors.
• Flexible: Setup a custom migrations table and use callbacks before and after each migration.

Usage

go get -u github.com/maragudk/migrate

package main

import (
	"context"
	"database/sql"
	"os"

	_ "github.com/jackc/pgx/v4/stdlib"
	"github.com/maragudk/migrate"
)

// migrations is a directory with sql files that look something like this:
// migrations/1-accounts.up.sql
// migrations/1-accounts.down.sql
// migrations/2-users.up.sql
// migrations/2-users.down.sql
var migrations = os.DirFS("migrations")

func main() {
	db, err := sql.Open("pgx", "postgresql://postgres:123@localhost:5432/postgres?sslmode=disable")
	if err != nil {
		panic(err)
	}

	if err := migrate.Up(context.Background(), db, migrations); err != nil {
		panic(err)
	}

	if err := migrate.Down(context.Background(), db, migrations); err != nil {
		panic(err)
	}

	if err := migrate.To(context.Background(), db, migrations, "1-accounts"); err != nil {
		panic(err)
	}
}

Documentation

Overview

Package migrate provides simple migration functions Up, Down, and To, as well as a Migrator. Up, Down, and To are one-liner convenience functions that use default Options. If you need custom Options, use New.

Example

package main

import (
	"context"
	"database/sql"
	"os"

	_ "github.com/go-sql-driver/mysql"
	_ "github.com/jackc/pgx/v4/stdlib"
	"github.com/maragudk/migrate"

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

var migrations = os.DirFS("testdata/example")

func main() {
	db, err := sql.Open("sqlite3", "db.sqlite")
	if err != nil {
		panic(err)
	}

	if err := migrate.Up(context.Background(), db, migrations); err != nil {
		panic(err)
	}

	if err := migrate.Down(context.Background(), db, migrations); err != nil {
		panic(err)
	}

	if err := migrate.To(context.Background(), db, migrations, "1"); err != nil {
		panic(err)
	}
}

Example (Advanced)

package main

import (
	"context"
	"database/sql"
	"os"

	_ "github.com/go-sql-driver/mysql"
	_ "github.com/jackc/pgx/v4/stdlib"
	"github.com/maragudk/migrate"

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

var migrations = os.DirFS("testdata/example")

func main() {
	db, err := sql.Open("sqlite3", "db.sqlite")
	if err != nil {
		panic(err)
	}

	before := func(ctx context.Context, tx *sql.Tx, version string) error {
		// Do whatever you need to before each migration
		return nil
	}

	after := func(ctx context.Context, tx *sql.Tx, version string) error {
		// Do whatever you need to after each migration
		return nil
	}

	m := migrate.New(migrate.Options{
		After:  after,
		Before: before,
		DB:     db,
		FS:     migrations,
		Table:  "migrations2",
	})

	if err := m.MigrateUp(context.Background()); err != nil {
		panic(err)
	}

	if err := m.MigrateDown(context.Background()); err != nil {
		panic(err)
	}

	if err := m.MigrateTo(context.Background(), "1"); err != nil {
		panic(err)
	}
}

Example (Embed)

package main

import (
	"context"
	"database/sql"
	"embed"
	"io/fs"

	_ "github.com/go-sql-driver/mysql"
	_ "github.com/jackc/pgx/v4/stdlib"
	"github.com/maragudk/migrate"

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

//go:embed testdata/example
var embeddedMigrations embed.FS

func main() {
	db, err := sql.Open("sqlite3", "db.sqlite")
	if err != nil {
		panic(err)
	}

	// Because migrate always reads from the root of the provided file system,
	// use fs.Sub to return the subtree rooted at the provided dir.
	fsys, err := fs.Sub(embeddedMigrations, "testdata/example")
	if err != nil {
		panic(err)
	}

	if err := migrate.Up(context.Background(), db, fsys); err != nil {
		panic(err)
	}

	if err := migrate.Down(context.Background(), db, fsys); err != nil {
		panic(err)
	}

	if err := migrate.To(context.Background(), db, fsys, "1"); err != nil {
		panic(err)
	}
}

Index

• func Down(ctx context.Context, db *sql.DB, fsys fs.FS) error
• func To(ctx context.Context, db *sql.DB, fsys fs.FS, version string) error
• func Up(ctx context.Context, db *sql.DB, fsys fs.FS) error
• type Migrator
  • func New(opts Options) *Migrator
  • func (m *Migrator) MigrateDown(ctx context.Context) (err error)
  • func (m *Migrator) MigrateTo(ctx context.Context, version string) (err error)
  • func (m *Migrator) MigrateUp(ctx context.Context) (err error)
• type Options

Examples

• Package
• Package (Advanced)
• Package (Embed)

Functions

func Down

func Down(ctx context.Context, db *sql.DB, fsys fs.FS) error

Down from the current version.

func To

func To(ctx context.Context, db *sql.DB, fsys fs.FS, version string) error

To the given version.

func Up

func Up(ctx context.Context, db *sql.DB, fsys fs.FS) error

Up from the current version.

Types

type Migrator

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

func New

func New(opts Options) *Migrator

New Migrator with Options. If Options.Table is not set, defaults to "migrations". The table name must match ^[\w.]+$ . New panics on illegal options.

func (*Migrator) MigrateDown

func (m *Migrator) MigrateDown(ctx context.Context) (err error)

MigrateDown from the current version.

func (*Migrator) MigrateTo

func (m *Migrator) MigrateTo(ctx context.Context, version string) (err error)

func (*Migrator) MigrateUp

func (m *Migrator) MigrateUp(ctx context.Context) (err error)

MigrateUp from the current version.

type Options

type Options struct {
	After  callback
	Before callback
	DB     *sql.DB
	FS     fs.FS
	Table  string
}

Options for New. DB and FS are always required.