migra

README

Migra

Migra is a command line interface and library for managing sql migrations.

Installation

In order to use migra as a library, import the package as follows.

go get -u github.com/cristosal/migra

To build and install the CLI from source run the following command. This assumes you have go installed in your local environment, and have cloned the repo

go install ./cmd/migra.go

Getting Started

Create a new instance of migra from an *sql.DB

m := migra.New(db)

Initialize migration tables

err := m.Init(context.Background())

The core of migra functionality is encompassed in the following methods

// Push adds a migration to the database and executes it.
// No error is returned if migration was already executed
func (m *Migra) Push(ctx context.Context, migration *Migration) error

// Pop executes the down migration removes the migration from db
func (m *Migra) Pop(ctx context.Context) error

Example of pushing a migration

m.Push(context.TODO(), &migra.Migration{
	Name:        "Create Users Table",
	Description: "Add Users Table with username and password fields",
	Up: `CREATE TABLE users (
		id SERIAL PRIMARY KEY,
		username VARCHAR(255) NOT NULL UNIQUE,
		password TEXT NOT NULL
	)`,
	Down: "DROP TABLE users"
})

This Migration can then be reversed by calling the Pop method

m.Pop(context.TODO())

Using Migration Files

Migra also supports defining migrations in files.

Any file format that is compatible with viper can be used. This includes json yaml toml ini among many others.

Each migration file must define the following properties

• name - unique name which identifies the migration.
• description - description of the migration which provides context for users
• up - sql to be executed for the migration
• down - sql to be executed in order to reverse the migration

Here is an example of a migration file using toml

# 1-users-table.toml

name = "users-table"
description = "Creates a users table with username and password fields"
up = """
CREATE TABLE users (
	id SERIAL PRIMARY KEY,
	username VARCHAR(255) NOT NULL UNIQUE,
	password TEXT NOT NULL
);
"""
down = "DROP TABLE users;"

To execute the migrations from files, several Push methods exist

// PushFile pushes the migration file located at filepath
func (m *Migra) PushFile(ctx context.Context, filepath string) error

// PushDir pushes all migration files located within the specified directory
func (m *Migra) PushDir(ctx context.Context, dirpath string) error

Migra supports using an fs.FS filesystem to help support embedding migrations into the binary.

//PushFileFS is same as PushFile but looks for the filepath in the filesystem
func PushFileFS(ctx context.Context, filesystem fs.FS, filepath string) error

//PushDirFS is same as PushDir but looks for the dirpath in the filesystem
func PushDirFS(ctx context.Context, filesystem fs.FS, dirpath string) error

NOTE: PushDirFS and PushFS are recursive and will push any migration files found in subdirectories

CLI

When using the CLI, many of migra's methods map to commands with flags. For example:

PushDir becomes migra push -d <directory> PopAll becomes migra pop -a

A Command Line Interface for managing sql migrations

Usage:
  migra [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  init        Creates migration tables and schema if specified.
  list        list all migrations
  pop         Undo migration
  push        Pushes a new migration

Flags:
      --conn string     database connection string. If unset, defaults to environment variable MIGRA_CONNECTION_STRING
      --driver string   database driver to use. If unset the environment variable for MIGRA_DRIVER is used otherwise the default driver is pgx.
  -h, --help            help for migra
  -s, --schema string   schema to use (default "public")
  -t, --table string    migrations table to use (default "_migrations")

Use "migra [command] --help" for more information about a command.

Documentation

Index

• Constants
• Variables
• type Migra
  • func New(db *sql.DB) *Migra
  • func Open(driver, dsn string) (*Migra, error)
  • func (m *Migra) CreateMigrationTable(ctx context.Context) error
  • func (m *Migra) DB() *sql.DB
  • func (m *Migra) DropMigrationTable(ctx context.Context) error
  • func (m *Migra) Latest(ctx context.Context) (*Migration, error)
  • func (m *Migra) List(ctx context.Context) ([]Migration, error)
  • func (m *Migra) MigrationTable() string
  • func (m *Migra) Pop(ctx context.Context) error
  • func (m *Migra) PopAll(ctx context.Context) (int, error)
  • func (m *Migra) PopUntil(ctx context.Context, name string) error
  • func (m *Migra) Push(ctx context.Context, migration *Migration) error
  • func (m *Migra) PushDir(ctx context.Context, dirpath string) error
  • func (m *Migra) PushDirFS(ctx context.Context, filesystem fs.FS, dirpath string) error
  • func (m *Migra) PushFS(ctx context.Context, filesystem fs.FS) error
  • func (m *Migra) PushFile(ctx context.Context, filepath string) error
  • func (m *Migra) PushFileFS(ctx context.Context, filesystem fs.FS, filepath string) error
  • func (m *Migra) PushMany(ctx context.Context, migrations []Migration) error
  • func (m *Migra) SetMigrationTable(table string) *Migra
  • func (m *Migra) SetSchema(schema string) *Migra
• type Migration

Constants

const (
	// DefaultMigrationTable is the name given to the migration table if not overriden by SetMigrationTable
	DefaultMigrationTable = "_migrations"

	// DefaultSchemaName is the name given to the migration table schema if not overriden by SetSchemaName
	DefaultSchemaName = "public"
)

Variables

var (
	ErrNoMigration = errors.New("no migration found")
)

Types

type Migra

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

Migra contains methods for migrating an sql database

func New

func New(db *sql.DB) *Migra

New creates a new Migra instance.

func Open

func Open(driver, dsn string) (*Migra, error)

Open is a helper function for opening the sql database and creating the migra instance

func (*Migra) CreateMigrationTable

func (m *Migra) CreateMigrationTable(ctx context.Context) error

CreateMigrationTable creates the table and schema where migrations will be stored and executed. The name of the table can be set using the SetMigrationTable method.

func (*Migra) DB

func (m *Migra) DB() *sql.DB

DB Allows access to the underlying sql database

func (*Migra) DropMigrationTable

func (m *Migra) DropMigrationTable(ctx context.Context) error

DropMigrationTable

func (*Migra) Latest

func (m *Migra) Latest(ctx context.Context) (*Migration, error)

Latest returns the latest migration executed

func (*Migra) List

func (m *Migra) List(ctx context.Context) ([]Migration, error)

List returns all the executed migrations

func (*Migra) MigrationTable

func (m *Migra) MigrationTable() string

MigrationTable returns the fully qualified, schema prefixed table name

func (*Migra) Pop

func (m *Migra) Pop(ctx context.Context) error

Pop reverts the last migration

func (*Migra) PopAll

func (m *Migra) PopAll(ctx context.Context) (int, error)

PopAll reverts all migrations

func (*Migra) PopUntil

func (m *Migra) PopUntil(ctx context.Context, name string) error

PopUntil pops until a migration with given name is reached

func (*Migra) Push

func (m *Migra) Push(ctx context.Context, migration *Migration) error

Push adds a migration to the database and executes it

func (*Migra) PushDir

func (m *Migra) PushDir(ctx context.Context, dirpath string) error

PushDir pushes all migrations inside a directory

func (*Migra) PushDirFS

func (m *Migra) PushDirFS(ctx context.Context, filesystem fs.FS, dirpath string) error

func (*Migra) PushFS

func (m *Migra) PushFS(ctx context.Context, filesystem fs.FS) error

PushFS pushes all migrations in a directory using fs.FS

func (*Migra) PushFile

func (m *Migra) PushFile(ctx context.Context, filepath string) error

PushFile pushes a migration from a file

func (*Migra) PushFileFS

func (m *Migra) PushFileFS(ctx context.Context, filesystem fs.FS, filepath string) error

PushFileFS pushes a file with given name from the filesystem

func (*Migra) PushMany

func (m *Migra) PushMany(ctx context.Context, migrations []Migration) error

PushMany pushes multiple migrations and returns first error encountered

func (*Migra) SetMigrationTable

func (m *Migra) SetMigrationTable(table string) *Migra

SetMigrationTable sets the default table where migrations will be stored and executed

func (*Migra) SetSchema

func (m *Migra) SetSchema(schema string) *Migra

SetSchema sets the schema for the migration table

type Migration

type Migration struct {
	ID          int64
	Name        string `mapstructure:"name"`
	Description string `mapstructure:"description"`
	Up          string `mapstructure:"up"`
	Down        string `mapstructure:"down"`
	Position    int64
	MigratedAt  time.Time
}

Migration is a structured change to the database