migrations

README

Migrations

Migrations is a minimalistic database migration tool that uses go's database/sql from the standard library.

Features

• supports any database driver that is compatible with database/sql, including: MySQL, Microsoft SQL Server, PostgreSQL, Oracle and SQLite.
• migrations are simple SQL files
• migrations can contain multiple queries
• easy generation of migration files
• we keep track of run migrations
• minimal dependencies
• customizable
• support for environment variables

Usage

Examples

Create a migration file

./migrations create -name=createGophersTable -path=/app/migrations/

or use environment variables:

MIGRATIONS_COMMAND="create" MIGRATIONS_PATH="/app/migrations/" MIGRATIONS_NEW_MIGRATION_NAME="createGophersTable" ./migrations

Run migrations

./migrations migrate -path=/app/migrations/

or use environment variables:

MIGRATIONS_COMMAND="migrate" MIGRATIONS_PATH="/app/migrations/" ./migrations

create command

The create command creates a file with a prefix using the current timestamp. That's going to be used to determine the order on which migrations should be run.

For example, running:

./migrations create -name=createGophersTable -path=/app/migrations/
./migrations create -name=createGolfersTable -path=/app/migrations/

Will result in:

/app/migrations/1627676712447528000_createGophersTable.sql
/app/migrations/1627676757857350000_createGolfersTable.sql

migrate command

The migrate command runs migrations and then displays a report with the result of each migration run, if any.

./migrations migrate -path=/app/migrations/

Example output:

[ INFO ] Run migrations
[  OK  ] 1627676712447528000_createGophersTable.sql
[  OK  ] 1627676757857350000_createGolfersTable.sql
[ INFO ] Done

Setup

1. Get the module

go get github.com/jimenezmaximiliano/migrations

1. Create a go file using the next template:

package main

import (
	"database/sql"

	// This example uses mysql but you can pick any other driver compatible with database/sql
	_ "github.com/go-sql-driver/mysql"

	"github.com/jimenezmaximiliano/migrations"
)

func main() {
	migrations.RunMigrationsCommand(func() (*sql.DB, error) {
		// Here you can set up your db connection
		return sql.Open("mysql", "user:password@/db?multiStatements=true")
	})
}

1. Then use the binary like this:

./migrations migrate -path=/app/migrations

or

go run migrations.go migrate -path=/app/migrations

See the example directory in this repository for a working example

Migration files

All migration files must:

• be in the provided path (not inside subdirectories)
• end in .sql (files without the .sql extension will be ignored)
• be in this format: {number}_{string}.sql where number determines the order on which migrations will be run
• be ordered by filename in the order they should run (you can use the create command for that)

Example:

/app/migrations
/app/migrations/1627676712447528000_createGophersTable.sql
/app/migrations/1627676757857350000_createGolfersTable.sql

See example migrations in the example directory

Customization

You can use the migrations facade as a tutorial on how to replace any component of the package by implementing one of its interfaces.

Documentation

Index

• func RunMigrations(DB *sql.DB, migrationsDirectoryAbsolutePath string) (models.Collection, error)
• func RunMigrationsCommand(setupDB SetupDB)
• type SetupDB

Functions

func RunMigrations

func RunMigrations(DB *sql.DB, migrationsDirectoryAbsolutePath string) (models.Collection, error)

RunMigrations runs the migrations using the given DB connection and migrations directory path. Returns a MigrationCollection, to be used programmatically.

func RunMigrationsCommand

func RunMigrationsCommand(setupDB SetupDB)

RunMigrationsCommand runs migrations as a command (it will output the results to stdout).

Types

type SetupDB

type SetupDB func() (*sql.DB, error)

SetupDB is a function that handles the configuration for the DB connection.