migrate

package module

v0.3.1 Latest Latest Go to latest Published: Oct 27, 2021 License: MIT Imports: 14 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/seeruk/go-migrate

Links

Open Source Insights

README ¶

go-migrate

A Go library for handling database migrations.

Features

Safe to run on application startup: The migration versions table is locked, preventing multiple copies of the same migrations from executing at the same time.
Migrations are code: Meaning you don't have to worry about how to package up .sql files, etc. into your Go binary, or transporting the .sql files with your application.
Simple versioning: Versions are just numbers - easy to sort (timestamps make good versions).
Configurable versions table: Migration drivers have relevant configuration exposed.
Designed to be integrated in to your code: Output is handled by implementing an EventHandler where you can use your own logger, etc.
Namespaced migrations: If you have multiple databases to migrate in one app, you can keep the migrations completely separate, and run them separately too.

Usage

See the examples/ folder for a complete usage example.

TODO

Unit tests
Documentation
- Godoc comments

Documentation ¶

Index ¶

Variables
func Execute(driver Driver, events EventHandler, namespace string, timeout time.Duration) (err error)
func MustRegisterFS(namespace string, in fs.FS)
func Register(namespace string, migration Migration)
func RegisterFS(namespace string, in fs.FS) error
type Driver
type EventHandler
type Migration
- func NewMigration(version int, commands ...string) Migration
type Migrations
type MySQLDriver
- func NewMySQLDriver(conn *sql.DB, database, table string) *MySQLDriver
type NamespacedMigrations
type NoopEventHandler
type PostgresDriver
- func NewPostgresDriver(conn *pgxpool.Pool, schema, table string) *PostgresDriver

Constants ¶

This section is empty.

Variables ¶

View Source

var (
	// ErrTransactionAlreadyStarted ...
	ErrTransactionAlreadyStarted = errors.New("migrate: transaction already started")
	// ErrTransactionNotStarted ...
	ErrTransactionNotStarted = errors.New("migrate: transaction not started")
)

Functions ¶

func MustRegisterFS ¶ added in v0.3.0

func MustRegisterFS(namespace string, in fs.FS)

MustRegisterFS calls RegisterFS, but panics if an error is returned.

func Register ¶

func Register(namespace string, migration Migration)

Register ... You can call this manually, or you can take advantage of `init` functions and just import a whole package of migrations at once. Sub-packages could easily be the namespace, e.g. migrations/users.

func RegisterFS ¶ added in v0.3.0

func RegisterFS(namespace string, in fs.FS) error

RegisterFS takes a filesystem and attempts to find SQL files to register as migrations.

Types ¶

type Driver ¶

type Driver interface {
	Begin(ctx context.Context) error
	Commit(ctx context.Context) error
	Rollback(ctx context.Context) error
	Lock(ctx context.Context) error
	Exec(ctx context.Context, command string) error
	CreateVersionsTable(ctx context.Context) error
	InsertVersion(ctx context.Context, version int) error
	Versions(ctx context.Context) ([]int, error)
	VersionTableExists(ctx context.Context) (bool, error)
}

Driver ... TODO: Can this be simplified, leaving more to each driver? It's quite heavily tied to SQL databases currently?

type EventHandler ¶

type EventHandler interface {
	BeforeVersionsMigrate(versions []int)
	BeforeVersionMigrate(version int)
	AfterVersionsMigrate(versions []int)
	AfterVersionMigrate(version int)
	OnVersionSkipped(version int)
	OnVersionTableNotExists()
	OnVersionTableCreated()
	OnExecuteError(err error)
	OnRollbackError(err error)
}

EventHandler is a type used to allow consumers of this library to handle output themselves for certain events as they happen during the migration process.

type Migration ¶

type Migration struct {
	Version  int
	Commands []string
}

Migration ...

func NewMigration ¶ added in v0.2.0

func NewMigration(version int, commands ...string) Migration

NewMigration returns a new Migration value.

type Migrations ¶

type Migrations map[int]Migration

Migrations ...

type MySQLDriver ¶ added in v0.2.0

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

MySQLDriver ...

func NewMySQLDriver ¶ added in v0.2.0

func NewMySQLDriver(conn *sql.DB, database, table string) *MySQLDriver

NewMySQLDriver returns a new MySQLDriver instance.

func (*MySQLDriver) Begin ¶ added in v0.2.0

func (d *MySQLDriver) Begin(ctx context.Context) error

Begin ...

func (*MySQLDriver) Commit ¶ added in v0.2.0

func (d *MySQLDriver) Commit(_ context.Context) error

Commit ...

func (*MySQLDriver) CreateVersionsTable ¶ added in v0.2.0

func (d *MySQLDriver) CreateVersionsTable(ctx context.Context) error

CreateVersionsTable ...

func (*MySQLDriver) Exec ¶ added in v0.2.0

func (d *MySQLDriver) Exec(ctx context.Context, command string) error

Exec ...

func (*MySQLDriver) InsertVersion ¶ added in v0.2.0

func (d *MySQLDriver) InsertVersion(ctx context.Context, version int) error

InsertVersion ...

func (*MySQLDriver) Lock ¶ added in v0.2.0

func (d *MySQLDriver) Lock(ctx context.Context) error

Lock ...

func (*MySQLDriver) Rollback ¶ added in v0.2.0

func (d *MySQLDriver) Rollback(_ context.Context) error

Rollback ...

func (*MySQLDriver) Unlock ¶ added in v0.2.0

func (d *MySQLDriver) Unlock()

Unlock must be explicitly implemented for MySQL.

func (*MySQLDriver) VersionTableExists ¶ added in v0.2.0

func (d *MySQLDriver) VersionTableExists(ctx context.Context) (bool, error)

VersionTableExists ...

func (*MySQLDriver) Versions ¶ added in v0.2.0

func (d *MySQLDriver) Versions(ctx context.Context) ([]int, error)

Versions ...

type NamespacedMigrations ¶

type NamespacedMigrations map[string]Migrations

NamespacedMigrations ...

type NoopEventHandler ¶

type NoopEventHandler struct{}

NoopEventHandler is a no-op EventHandler implementation.

func (NoopEventHandler) AfterVersionMigrate ¶

func (n NoopEventHandler) AfterVersionMigrate(version int)

AfterVersionMigrate is a no-op AfterVersionMigrate method.

func (NoopEventHandler) AfterVersionsMigrate ¶

func (n NoopEventHandler) AfterVersionsMigrate(versions []int)

AfterVersionsMigrate is a no-op AfterVersionsMigrate method.

func (NoopEventHandler) BeforeVersionMigrate ¶

func (n NoopEventHandler) BeforeVersionMigrate(version int)

BeforeVersionMigrate is a no-op BeforeVersionMigrate method.

func (NoopEventHandler) BeforeVersionsMigrate ¶

func (n NoopEventHandler) BeforeVersionsMigrate(versions []int)

BeforeVersionsMigrate is a no-op BeforeVersionsMigrate method.

func (NoopEventHandler) OnExecuteError ¶ added in v0.2.0

func (n NoopEventHandler) OnExecuteError(err error)

OnExecuteError is a no-op OnExecuteError method.

func (NoopEventHandler) OnRollbackError ¶

func (n NoopEventHandler) OnRollbackError(err error)

OnRollbackError is a no-op OnRollbackError method.

func (NoopEventHandler) OnVersionSkipped ¶

func (n NoopEventHandler) OnVersionSkipped(version int)

OnVersionSkipped is a no-op OnVersionSkipped method.

func (NoopEventHandler) OnVersionTableCreated ¶

func (n NoopEventHandler) OnVersionTableCreated()

OnVersionTableCreated is a no-op OnVersionTableCreated method.

func (NoopEventHandler) OnVersionTableNotExists ¶

func (n NoopEventHandler) OnVersionTableNotExists()

OnVersionTableNotExists is a no-op OnVersionTableNotExists method.

type PostgresDriver ¶ added in v0.2.0

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

PostgresDriver ...

func NewPostgresDriver ¶ added in v0.2.0

func NewPostgresDriver(conn *pgxpool.Pool, schema, table string) *PostgresDriver

NewPostgresDriver returns a new PostgresDriver instance. TODO: Config...

func (*PostgresDriver) Begin ¶ added in v0.2.0

func (d *PostgresDriver) Begin(ctx context.Context) error