petersanchez.com/migrate Index | Files

package migrate

import "petersanchez.com/migrate"

Package migrate is a simple and flexible module to manage database migrations.

You can use migration files, queries, and custom functions to manage your migrations. Also has full Context support (globally and per migration) with has no external dependencies.

Index

Package Files

command.go doc.go migrate.go sql.go

Constants

const (
    UNKNOWN = iota
    // Use ? for sql placeholder
    QUESTION
    // Use $<num> for sql placeholder
    DOLLAR
    // Use :<name> for sql placeholder
    NAMED
    // Use @ for sql placeholder
    AT
)

Pulled from sqlx: https://github.com/jmoiron/sqlx

func Command

func Command(db *sql.DB, migrations []Migration, bindType int) error

Command will run a very simple command line processor using `os.Args[2:]`. bindType should be set to one of the constants exported in this module.

flag options are:

-fake - this will "fake" migrations and just add entries to the migration table.
-verbose - this will enable verbose output.

positional arguments are

up | down - Migrate up (forward) or down (rollback). If not given "up" is assumed.
<migration id> - If given, migrations will stop after this migration is processed.

type Migration

type Migration struct {
    // Unique ID for the migration. You must self enforce this.
    ID  string
    // Optional timeout for this particular migration.
    Timeout int
    // Function to migrate forward. Functions should respect context's Done
    // channel if they want the timeout to work.
    Migrate func(ctx context.Context, tx *sql.Tx) error
    // Function to migrate backward. Functions should respect context's Done
    // channel if they want the timeout to work.
    Rollback func(ctx context.Context, tx *sql.Tx) error
}

Migration is a unique ID plus a function that uses a sql transaction to perform a database migration step.

func FileMigration

func FileMigration(id, upFile, downFile string, timeout int) Migration

FileMigration will create a Migration using the provided migration ID, up/down files, and migration timeout. If timeout is set, the queries will be cancelled if the timeout period passes.

func QueryMigration

func QueryMigration(id, upQuery, downQuery string, timeout int) Migration

QueryMigration will create a Migration using the provided migration ID and up/down queries, and migration timeout. If timeout is set, the queries will be cancelled if the timeout period passes.

type MigrationEngine

type MigrationEngine struct {
    Migrations []Migration
    // Printf is used to print out additional information during a migration, such
    // as which step the migration is currently on. It can be replaced with any
    // custom printf function, including one that just ignores inputs. If nil it
    // will default to fmt.Printf.
    Printf func(format string, a ...interface{}) (n int, err error)
    // contains filtered or unexported fields
}

MigrationEngine is the base migration engine

func NewEngine

func NewEngine(db *sql.DB, migrations []Migration, bindType int, verbose bool) *MigrationEngine

NewEngine returns a new MigrationEngine object bindType should be one of the constants: QUESTION, DOLLAR, NAMED or AT

func (*MigrationEngine) Migrate

func (me *MigrationEngine) Migrate(ctx context.Context, stopID string, fakeIt bool) error

Migrate will run the migrations using the provided db connection. `stopID` is the migration ID to stop at (after running it) `fakeIt` is a flag that says whether or not to "fake" the migration. Faking the migration means it will add the migration entry into the `migrations` db table as if it ran but without actually running it.

func (*MigrationEngine) Rollback

func (me *MigrationEngine) Rollback(ctx context.Context, stopID string) error

Rollback will run all rollbacks using the provided db connection. `stopID` is the migration ID to stop at (after running it)

Version
v0.2.0 (latest)
Published
Feb 19, 2022
Platform
linux/amd64
Imports
10 packages (graph)
Last checked
2 months ago

Tools for package owners.