README
¶
gomigrate
A SQL database migration toolkit in Golang.
This is a fork of https://github.com/DavidHuie/gomigrate that adds support for
reading migration files embedded directly within the built executable, or from
any other source available via the fs.FS interface present in Go 1.16 and up.
This simplifies deployment by removing the need to install and manage a
separate migrations directory.
The previous file-based API also remains supported, even though the
implementation now uses fs.FS internally.
Supported databases
- PostgreSQL
- MariaDB
- MySQL
- Sqlite3
Usage
First import the Go 1.16 embed package and this package:
import (
"embed"
"github.com/ashearer/gomigrate"
)
Given a database/sql database connection to a PostgreSQL database, db,
and a directory named migrations in the same directory as the source code,
create a migrator that reads files within the embedded migrations directory:
//go:embed migrations
var migrationsDirFS embed.FS // files will be embedded under path "migrations/"
// make an FS to access the files without the "migrations/" path prefix
migrationsFS, err := fs.Sub(migrationsDirFS, "migrations")
if err != nil {
log.Fatal(err)
}
migrator, _ := gomigrate.NewMigratorFS(db, gomigrate.Postgres{}, migrationsFS)
You may also specify a logger, such as logrus:
migrator, _ := gomigrate.NewMigratorFSWithLogger(db, gomigrate.Postgres{}, migrationsFS, logrus.New())
To migrate the database, run:
err := migrator.Migrate()
To rollback the last migration, run:
err := migrator.Rollback()
Migration files
Migration files need to follow a standard format and must be present in the same directory. Given "up" and "down" steps for a migration, create a file for each by following this template:
{{ id }}_{{ name }}_{{ "up" or "down" }}.sql
For a given migration, the id and name fields must be the same.
The id field is an integer that corresponds to the order in which
the migration should run relative to the other migrations.
id should not be 0 as that value is used for internal validations.
Note that in the example above of embedding migrations, Go will automatically skip filenames beginning with a period or underscore. This is typically useful, but could be overridden if necessary by using a wildcard glob pattern.
Example
If I'm trying to add a "users" table to the database, I would create the following two files:
1_add_users_table_up.sql
CREATE TABLE users();
1_add_users_table_down.sql
DROP TABLE users;
Requirements
Go 1.16 or higher.
Copyright
Copyright © 2014-2021 David Huie and Andrew Shearer. Based on https://github.com/DavidHuie/gomigrate by David Huie. See LICENSE.txt for further details.
Documentation
¶
Index ¶
- Constants
- Variables
- type Logger
- type Mariadb
- type Migratable
- type Migration
- type Migrator
- func NewMigrator(db *sql.DB, adapter Migratable, migrationsPath string) (*Migrator, error)
- func NewMigratorFS(db *sql.DB, adapter Migratable, migrationsFS fs.FS) (*Migrator, error)
- func NewMigratorFSWithLogger(db *sql.DB, adapter Migratable, migrationsFS fs.FS, logger Logger) (*Migrator, error)
- func NewMigratorWithLogger(db *sql.DB, adapter Migratable, migrationsPath string, logger Logger) (*Migrator, error)
- func (m *Migrator) ApplyMigration(migration *Migration, mType migrationType) error
- func (m *Migrator) CreateMigrationsTable() error
- func (m *Migrator) Migrate() error
- func (m *Migrator) MigrationTableExists() (bool, error)
- func (m *Migrator) Migrations(status int) []*Migration
- func (m *Migrator) Rollback() error
- func (m *Migrator) RollbackAll() error
- func (m *Migrator) RollbackN(n int) error
- type Mysql
- type Postgres
- func (p Postgres) CreateMigrationTableSql() string
- func (p Postgres) GetMigrationCommands(sql string) []string
- func (p Postgres) GetMigrationSql() string
- func (p Postgres) MigrationLogDeleteSql() string
- func (p Postgres) MigrationLogInsertSql() string
- func (p Postgres) SelectMigrationTableSql() string
- type SqlServer
- func (s SqlServer) CreateMigrationTableSql() string
- func (s SqlServer) GetMigrationCommands(sql string) []string
- func (s SqlServer) GetMigrationSql() string
- func (s SqlServer) MigrationLogDeleteSql() string
- func (s SqlServer) MigrationLogInsertSql() string
- func (s SqlServer) SelectMigrationTableSql() string
- type Sqlite3
Constants ¶
const ( Inactive = iota Active )
Migration statuses.
Variables ¶
var ( InvalidMigrationFile = errors.New("Invalid migration file") InvalidMigrationPair = errors.New("Invalid pair of migration files") InvalidMigrationsPath = errors.New("Invalid migrations path") InvalidMigrationType = errors.New("Invalid migration type") NoActiveMigrations = errors.New("No active migrations to rollback") )
Functions ¶
This section is empty.
Types ¶
type Migratable ¶
type Migrator ¶
func NewMigrator ¶
Returns a new migrator based on a directory pathname.
func NewMigratorFS ¶
Returns a new migrator based on an fs.FS filesystem.
func NewMigratorFSWithLogger ¶
func NewMigratorFSWithLogger(db *sql.DB, adapter Migratable, migrationsFS fs.FS, logger Logger) (*Migrator, error)
Returns a new migrator with the specified logger based on an fs.FS filesystem.
func NewMigratorWithLogger ¶
func NewMigratorWithLogger(db *sql.DB, adapter Migratable, migrationsPath string, logger Logger) (*Migrator, error)
Returns a new migrator with the specified logger based on a directory pathname.
func (*Migrator) ApplyMigration ¶
Applies a single migration.
func (*Migrator) CreateMigrationsTable ¶
Creates the migrations table if it doesn't exist.
func (*Migrator) MigrationTableExists ¶
Returns true if the migration table already exists.
func (*Migrator) Migrations ¶
Returns a sorted list of migration ids for a given status. -1 returns all migrations.
type Mysql ¶
type Mysql struct{}
func (Mysql) CreateMigrationTableSql ¶
func (Mysql) GetMigrationCommands ¶
func (Mysql) GetMigrationSql ¶
func (Mysql) MigrationLogDeleteSql ¶
func (Mysql) MigrationLogInsertSql ¶
func (Mysql) SelectMigrationTableSql ¶
type Postgres ¶
type Postgres struct{}
func (Postgres) CreateMigrationTableSql ¶
func (Postgres) GetMigrationCommands ¶
func (Postgres) GetMigrationSql ¶
func (Postgres) MigrationLogDeleteSql ¶
func (Postgres) MigrationLogInsertSql ¶
func (Postgres) SelectMigrationTableSql ¶
type SqlServer ¶
type SqlServer struct{}
func (SqlServer) CreateMigrationTableSql ¶
func (SqlServer) GetMigrationCommands ¶
func (SqlServer) GetMigrationSql ¶
func (SqlServer) MigrationLogDeleteSql ¶
func (SqlServer) MigrationLogInsertSql ¶
func (SqlServer) SelectMigrationTableSql ¶
type Sqlite3 ¶
type Sqlite3 struct{}
Source Files