mig

README

mig

Go PostgreSQL database schema migration library.

Supported drivers

• pgx/v5 single connection and connection pool
• pgx/v4 single connection and connection pool

In theory, you can also make an implementation for any database using mig.Database interface and instantiate mig using mig.New constructor. Since there are other migration libraries supporting multiple databases using Go's standard library's interface database/sql, this project has no intention to make such implementations since there is no other library specific to pgx driver. As of now, there is only tern CLI, but it doesn't provide a library.

Warning 🚧

This project is in an early stage so you can expect API breaking changes until the first major release.

Naming migration files

1-initial.sql
2-alter-some-table.sql
...

or

001-initial.sql
002-alter-some-table.sql

mig will try to parse the number prefix in the correct order without matter if it is prefixed with zeroes or not. So, in theory, the following migration files should also work as expected:

001-initial.sql
2-alter-some-table.sql
03-insert-some-fixed-data.sql
...

Run tests

• make start to start the docker-compose with PostgreSQL and adminer
• make test to run all tests
• make stop so that new make start gets clean database

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Documentation

Index

• Variables
• type Database
• type Mig
  • func FromPgxV4(ms Migrations, conn *pgx4.Conn, opts ...Option) *Mig
  • func FromPgxV4Pool(ms Migrations, pool *pgxPoolV4.Pool, opts ...Option) (*Mig, func(), error)
  • func FromPgxV5(ms Migrations, conn *pgx5.Conn, opts ...Option) *Mig
  • func FromPgxV5Pool(ms Migrations, pool *pgxPoolV5.Pool, opts ...Option) (*Mig, func(), error)
  • func New(ms Migrations, db Database, opts ...Option) *Mig
  • func (d *Mig) Migrate(ctx context.Context) error
• type Migration
• type Migrations
  • func FromDir(path string) (Migrations, error)
  • func FromEmbedFS(fs embed.FS, path string) (Migrations, error)
  • func (ms *Migrations) Len() int
  • func (ms *Migrations) Less(i, j int) bool
  • func (ms *Migrations) Swap(i, j int)
• type Option
  • func WithAcquireConnectionTimeout(timeout time.Duration) Option
  • func WithCustomTable(name string) Option

Examples

• FromPgxV4
• FromPgxV4Pool
• FromPgxV5
• FromPgxV5Pool

Variables

var (
	ErrInvalidVersion   = errors.New("invalid migration version prefix")
	ErrDuplicateVersion = errors.New("duplicate version")
)

Types

type Database

type Database interface {
	Lock(ctx context.Context) error
	CreateSchemaMigrationsTable(ctx context.Context) error
	LastVersion(ctx context.Context) (uint64, error)
	SetLastVersion(ctx context.Context, lastVersion uint64) error
	RunMigration(ctx context.Context, query string) error
	Unlock(ctx context.Context) error
}

type Mig

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

func FromPgxV4

func FromPgxV4(ms Migrations, conn *pgx4.Conn, opts ...Option) *Mig

Example

package main

import (
	"context"
	"os"
	"path/filepath"

	pgx4 "github.com/jackc/pgx/v4"
	"go.acim.net/mig"
)

const dsn = "postgres://postgres@localhost:5432/mig"

func main() {
	wd, err := os.Getwd()
	if err != nil {
		panic(err)
	}

	migrations, err := mig.FromDir(filepath.Join(wd, "migrations"))
	if err != nil {
		panic(err)
	}

	ctx := context.Background()

	conn, err := pgx4.Connect(ctx, dsn)
	if err != nil {
		panic(err)
	}

	migrator := mig.FromPgxV4(migrations, conn, mig.WithCustomTable("bob"))

	if err := migrator.Migrate(ctx); err != nil {
		panic(err)
	}

}

func FromPgxV4Pool

func FromPgxV4Pool(ms Migrations, pool *pgxPoolV4.Pool, opts ...Option) (*Mig, func(), error)

Example

package main

import (
	"context"
	"os"
	"path/filepath"

	pgx4pool "github.com/jackc/pgx/v4/pgxpool"
	"go.acim.net/mig"
)

const dsn = "postgres://postgres@localhost:5432/mig"

func main() {
	wd, err := os.Getwd()
	if err != nil {
		panic(err)
	}

	migrations, err := mig.FromDir(filepath.Join(wd, "migrations"))
	if err != nil {
		panic(err)
	}

	ctx := context.Background()

	pool, err := pgx4pool.Connect(ctx, dsn)
	if err != nil {
		panic(err)
	}

	migrator, cleanup, err := mig.FromPgxV4Pool(migrations, pool, mig.WithCustomTable("alice"))
	if err != nil {
		panic(err)
	}

	defer cleanup()

	if err := migrator.Migrate(ctx); err != nil {
		panic(err)
	}

}

func FromPgxV5

func FromPgxV5(ms Migrations, conn *pgx5.Conn, opts ...Option) *Mig

Example

package main

import (
	"context"
	"os"
	"path/filepath"

	pgx5 "github.com/jackc/pgx/v5"
	"go.acim.net/mig"
)

const dsn = "postgres://postgres@localhost:5432/mig"

func main() {
	wd, err := os.Getwd()
	if err != nil {
		panic(err)
	}

	migrations, err := mig.FromDir(filepath.Join(wd, "migrations"))
	if err != nil {
		panic(err)
	}

	ctx := context.Background()

	conn, err := pgx5.Connect(ctx, dsn)
	if err != nil {
		panic(err)
	}

	migrator := mig.FromPgxV5(migrations, conn, mig.WithCustomTable("trudy"))

	if err := migrator.Migrate(ctx); err != nil {
		panic(err)
	}

}

func FromPgxV5Pool

func FromPgxV5Pool(ms Migrations, pool *pgxPoolV5.Pool, opts ...Option) (*Mig, func(), error)

Example

package main

import (
	"context"
	"os"
	"path/filepath"
	"time"

	pgx5pool "github.com/jackc/pgx/v5/pgxpool"
	"go.acim.net/mig"
)

const dsn = "postgres://postgres@localhost:5432/mig"

func main() {
	wd, err := os.Getwd()
	if err != nil {
		panic(err)
	}

	migrations, err := mig.FromDir(filepath.Join(wd, "migrations"))
	if err != nil {
		panic(err)
	}

	ctx := context.Background()

	pool, err := pgx5pool.New(ctx, dsn)
	if err != nil {
		panic(err)
	}

	migrator, cleanup, err := mig.FromPgxV5Pool(migrations, pool, mig.WithCustomTable("eve"),
		mig.WithAcquireConnectionTimeout(time.Second))
	if err != nil {
		panic(err)
	}

	defer cleanup()

	if err := migrator.Migrate(ctx); err != nil {
		panic(err)
	}

}

func New

func New(ms Migrations, db Database, opts ...Option) *Mig

func (*Mig) Migrate

func (d *Mig) Migrate(ctx context.Context) error

type Migration

type Migration struct {
	Version uint64
	Name    string
	Path    string
	SQL     string
}

type Migrations

type Migrations []Migration

func FromDir

func FromDir(path string) (Migrations, error)

func FromEmbedFS

func FromEmbedFS(fs embed.FS, path string) (Migrations, error)

func (*Migrations) Len

func (ms *Migrations) Len() int

func (*Migrations) Less

func (ms *Migrations) Less(i, j int) bool

func (*Migrations) Swap

func (ms *Migrations) Swap(i, j int)

type Option

type Option func(*Mig)

func WithAcquireConnectionTimeout

func WithAcquireConnectionTimeout(timeout time.Duration) Option

func WithCustomTable

func WithCustomTable(name string) Option