README
¶
Migrate
Migrate is a Go library for doing migrations. It's stupidly simple and gets out of your way.
Features
- It's only dependency is
database/sql. - It supports any type of migration you want to run (e.g. raw sql, or Go code).
- It doesn't provide a command. It's designed to be embedded in projects and used exclusively as a library.
Usage
migrations := []migrate.Migration{
{
ID: 1,
Up: func(tx *sql.Tx) error {
_, err := tx.Exec("CREATE TABLE people (id int)")
return err
},
Down: func(tx *sql.Tx) error {
_, err := tx.Exec("DROP TABLE people")
return err
},
},
{
ID: 2,
// For simple sql migrations, you can use the migrate.Queries
// helper.
Up: migrate.Queries([]string{
"ALTER TABLE people ADD COLUMN first_name text",
}),
Down: func(tx *sql.Tx) error {
// It's not possible to remove a column with
// sqlite.
_, err := tx.Exec("SELECT 1 FROM people")
return err
},
},
}
db, _ := sql.Open("sqlite3", ":memory:")
_ = migrate.Exec(db, migrate.Up, migrations...)
Locking
All migrations are run in a transaction, but if you attempt to run a single long running migration concurrently, you could run into a deadlock. For Postgres connections, migrate can use pg_advisory_lock to ensure that only 1 migration is run at a time.
To use this, simply instantiate a Migrator instance using migrate.NewPostgresMigrator:
migrator := NewPostgresMigrator(db)
_ = migrator.Exec(migrate.Up, migrations...)
Documentation
¶
Overview ¶
Package migrate provides a dead simple Go package for performing sql migrations using database/sql.
Example ¶
package main
import (
"database/sql"
_ "github.com/mattn/go-sqlite3"
"github.com/remind101/migrate"
)
func main() {
migrations := []migrate.Migration{
{
ID: 1,
Up: func(tx *sql.Tx) error {
_, err := tx.Exec("CREATE TABLE people (id int)")
return err
},
Down: func(tx *sql.Tx) error {
_, err := tx.Exec("DROP TABLE people")
return err
},
},
{
ID: 2,
// For simple sql migrations, you can use the migrate.Queries
// helper.
Up: migrate.Queries([]string{
"ALTER TABLE people ADD COLUMN first_name text",
}),
Down: func(tx *sql.Tx) error {
// It's not possible to remove a column with
// sqlite.
_, err := tx.Exec("SELECT 1 FROM people")
return err
},
},
}
db, _ := sql.Open("sqlite3", ":memory:")
_ = migrate.Exec(db, migrate.Up, migrations...)
}
Index ¶
Examples ¶
Constants ¶
const DefaultTable = "schema_migrations"
The default table to store what migrations have been run.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ByID ¶
type ByID []Migration
ByID implements the sort.Interface interface for sorting migrations by ID.
type Migration ¶
type Migration struct {
// ID is a unique, numeric, identifier for this migration.
ID int
// Up is a function that gets called when this migration should go up.
Up func(tx *sql.Tx) error
// Down is a function that gets called when this migration should go
// down.
Down func(tx *sql.Tx) error
}
Migration represents a sql migration that can be migrated up or down.
type MigrationError ¶
MigrationError is an error that gets returned when an individual migration fails.
func (*MigrationError) Error ¶
func (e *MigrationError) Error() string
Error implements the error interface.
type Migrator ¶
type Migrator struct {
// Table is the table to store what migrations have been run. The zero
// value is DefaultTable.
Table string
// Locker is a sync.Locker to use to ensure that only 1 process is
// running migrations.
sync.Locker
// The TransactionMode to use. The zero value is IndividualTransactions,
// which runs each migration in it's own transaction.
TransactionMode TransactionMode
// contains filtered or unexported fields
}
Migrator performs migrations.
func NewMigrator ¶
NewMigrator returns a new Migrator instance that will use the sql.DB to perform the migrations.
func NewPostgresMigrator ¶
NewPostgresMigrator returns a new Migrator instance that uses the underlying sql.DB connection to a postgres database to perform migrations. It will use Postgres's advisory locks to ensure that only 1 migration is run at a time.
type TransactionMode ¶
type TransactionMode int
const ( // In this mode, each migration is run in it's own isolated transaction. // If a migration fails, only that migration will be rolled back. IndividualTransactions TransactionMode = iota // In this mode, all migrations are run inside a single transaction. If // one migration fails, all migrations are rolled back. SingleTransaction )
Source Files