migration

package module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 10, 2024 License: MIT Imports: 17 Imported by: 0

README

Go Migration

A simple to use database schema migration tool for go applications.

Installation

Open your favorite terminal app and cd into your go module enabled project root:

cd packagename

[Replace "packagename" with your package's name]

To install the migration package, run:

go get -u github.com/lemmego/migration

Usage

This package resolves the DSN (Data Source Name) from the following env variables:

DB_DRIVER=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=test
DB_USERNAME=root
DB_PASSWORD=
DB_PARAMS=charset=utf8mb4&collation=utf8mb4_unicode_ci

The supported DB_DRIVER values are sqlite, mysql and postgres

// projectroot/cmd/migrations/main.go

package main

import (
  "github.com/joho/godotenv"
  "github.com/lemmego/migration/cmd"
)

func main() {
  if err := godotenv.Load(); err != nil {
    panic(err)
  }
  cmd.Execute()
}

Then run go run ./cmd/migratations create create_users_table to create a sample migration. A migration file will be created inside the projectroot/cmd/migrations/ directory. If the migrations directory is not present in your project root, the migrate create ... command will create one for you. Open the migration file and populate the up() and down() method like this:

// 20220729200658_create_users_table.go

package migrations

import (
	"database/sql"
	"github.com/lemmego/migration"
)

func init() {
	migration.GetMigrator().AddMigration(&migration.Migration{
		Version: "20220729200658",
		Up:      mig_20220729200658_create_users_table_up,
		Down:    mig_20220729200658_create_users_table_down,
	})
}

func mig_20220729200658_create_users_table_up(tx *sql.Tx) error {
	_, err := tx.Exec("CREATE TABLE users ( name varchar(255) );")
	if err != nil {
		return err
	}
	return nil
}

func mig_20220729200658_create_users_table_down(tx *sql.Tx) error {
	_, err := tx.Exec("DROP TABLE users")
	if err != nil {
		return err
	}
	return nil
}

Optionally, you could also use the db agnostic schema builder API:

// 20220729200658_create_users_table.go

package migrations

import (
	"database/sql"
	"github.com/lemmego/migration"
)

func init() {
	migration.GetMigrator().AddMigration(&migration.Migration{
		Version: "20220729200658",
		Up:      mig_20220729200658_create_users_table_up,
		Down:    mig_20220729200658_create_users_table_down,
	})
}

func mig_20220729200658_create_users_table_up(tx *sql.Tx) error {
  schema := migration.Create("users", func(t *migration.Table) {
    t.BigIncrements("id").Primary()
    t.Integer("org_id")
    t.String("first_name", 255)
    t.String("last_name", 255)
    t.String("email", 255).Unique()
    t.String("password", 255)
    t.DateTime("created_at", 0).Default("now()")
    t.DateTime("updated_at", 0).Default("now()")
  }).Build()

  if _, err := tx.Exec(schema); err != nil {
    return err
  }

  return nil
}

func mig_20220729200658_create_users_table_down(tx *sql.Tx) error {
  schema := migration.Drop("users").Build()
  if _, err := tx.Exec(schema); err != nil {
    return err
  }
  return nil
}

Once you've made sure that the expected environment variables are present in your .env file, you can run go run . migrate up

You should see something like the following:

Connecting to database...
Database connected!
Running migration 20220729200658
Finished running migration 20220729200658

Open your database client application (e.g. SequelPro, TablePlus) and open the database. You should see two new tables: schema_migrations and users.

You can revert the migration by running go run . migrate down. You should see something like this:

Connecting to database...
Database connected!
Reverting Migration 20220729200658
Finished reverting migration 20220729200658

Both the migrate up and the migrate down commands take a --step integer flag to indicate how many step should the migration run forward or backward:

E.g.:

go run . migrate down --step=1

There is also a migrate status command to see which migrations are currently pending and/or completed.

Documentation

The package documentation can be found at: https://pkg.go.dev/github.com/lemmego/migration

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT

Documentation

Index

Constants

View Source 
const (
	DialectSQLite   = "sqlite"
	DialectMySQL    = "mysql"
	DialectPostgres = "postgres"

	ColTypeIncrements    = "increments"
	ColTypeBigIncrements = "bigIncrements"
	ColTypeTinyInt       = "tinyInt"
	ColTypeBool          = "bool"
	ColTypeSmallInt      = "smallInt"
	ColTypeMediumInt     = "mediumInt"
	ColTypeInt           = "int"
	ColTypeBigInt        = "bigInt"
	ColTypeFloat         = "float"
	ColTypeDouble        = "double"
	ColTypeDecimal       = "decimal"
	ColTypeDate          = "date"
	ColTypeDateTime      = "dateTime"
	ColTypeDateTimeTz    = "dateTimeTz"
	ColTypeTime          = "time"
	ColTypeTimestamp     = "timestamp"
	ColTypeTimestampTz   = "timestampTz"
	ColTypeChar          = "char"
	ColTypeVarchar       = "varchar"
	ColTypeText          = "text"
	ColTypeTinyText      = "tinyText"
	ColTypeMediumText    = "mediumText"
	ColTypeLongText      = "longText"
	ColTypeBinary        = "binary"
	ColTypeVarBinary     = "varBinary"
	ColTypeBlob          = "blob"
	ColTypeTinyBlob      = "tinyBlob"
	ColTypeMediumBlob    = "mediumBlob"
	ColTypeLongBlob      = "longBlob"
	ColTypeEnum          = "enum"
	ColTypeSet           = "set"
)

Variables

View Source 
var (
	ErrUnsupportedDialect = errors.New("unsupported dialect")
)

Functions

func CreateMigration added in v0.1.0 

func CreateMigration(name string) error

CreateMigration creates a migration file

func NewDB 

func NewDB(dsn string, driverName string) *sql.DB

NewDB creates a new database connection

Types

type Column added in v0.1.0 

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

Column type is the column definition

func (*Column) Change added in v0.1.0 

func (c *Column) Change()

Change changes the operation of the column to alter

func (*Column) Default added in v0.1.0 

func (c *Column) Default(defaultValue any) *Column

Default adds the default value to the column

func (*Column) Done added in v0.1.0 

func (c *Column) Done() *Table

Done returns the table that the column belongs to

func (*Column) NotNull added in v0.1.0 

func (c *Column) NotNull() *Column

NotNull adds the not null attribute to the column

func (*Column) Nullable added in v0.1.0 

func (c *Column) Nullable() *Column

Nullable adds the nullable attribute to the column

func (*Column) Primary added in v0.1.0 

func (c *Column) Primary() *Column

Primary adds the primary attribute to the column

func (*Column) Type added in v0.1.0 

func (c *Column) Type(dataType *DataType) *Column

Type adds a data type to the column

func (*Column) Unique added in v0.1.0 

func (c *Column) Unique() *Column

Unique adds the unique attribute to the column

func (*Column) Unsigned added in v0.1.0 

func (c *Column) Unsigned() *Column

Unsigned adds the unsigned attribute to the column

type DataSource added in v0.1.0 

type DataSource struct {
	Dialect  string
	Host     string
	Port     string
	Username string
	Password string
	Name     string
	Params   string
}

DataSource holds the necessary fields for a DSN (data source name)

func (*DataSource) String added in v0.1.0 

func (ds *DataSource) String() (string, error)

String returns the string representation of the data source

type DataType added in v0.1.0 

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

DataType represents a column type

func NewDataType added in v0.1.0 

func NewDataType(columnName string, name string, dialect string) *DataType

NewDataType creates a new DataType

func (*DataType) AddSuffixes added in v0.1.0 

func (dataType *DataType) AddSuffixes() *DataType

AddSuffixes adds suffixes to the column type

func (*DataType) AppendSufix added in v0.1.0 

func (dataType *DataType) AppendSufix(suffix string) *DataType

AppendSufix appends a suffix to the column type

func (*DataType) SetColumnName added in v0.1.0 

func (dataType *DataType) SetColumnName(columnName string)

SetColumnName sets the column name of the column

func (*DataType) SetDialet added in v0.1.0 

func (dataType *DataType) SetDialet(dialect string)

SetDialet sets the dialect of the column

func (*DataType) ToString added in v0.1.0 

func (dataType *DataType) ToString() string

ToString returns the string representation of the column type

func (*DataType) WithEnumValues added in v0.1.0 

func (dataType *DataType) WithEnumValues(enumValues []string) *DataType

WithEnumValues sets the enum values of the column

func (*DataType) WithLength added in v0.1.0 

func (dataType *DataType) WithLength(length uint) *DataType

WithLength sets the length of the column

func (*DataType) WithPrecision added in v0.1.0 

func (dataType *DataType) WithPrecision(precision uint) *DataType

WithPrecision sets the precision of the column

func (*DataType) WithScale added in v0.1.0 

func (dataType *DataType) WithScale(scale uint) *DataType

WithScale sets the scale of the column

type Migration 

type Migration struct {
	Version string
	Up      func(*sql.Tx) error
	Down    func(*sql.Tx) error
	// contains filtered or unexported fields
}

Migration represents a migration data type

type Migrator 

type Migrator struct {
	Versions   []string
	Migrations map[string]*Migration
	// contains filtered or unexported fields
}

Migrator is a struct that holds the migrations

func GetMigrator 

func GetMigrator() *Migrator

GetMigrator returns the migrator

func Init 

func Init(db *sql.DB, dialect string) (*Migrator, error)

Init populates the fields of Migrator and returns it

func (*Migrator) AddMigration 

func (m *Migrator) AddMigration(mg *Migration)

AddMigration adds a migration to the migrator

func (*Migrator) Down 

func (m *Migrator) Down(step int) error

Down migration rolls back the last batch of migrations

func (*Migrator) MigrationStatus 

func (m *Migrator) MigrationStatus() error

Status checks which migrations have run and which have not

func (*Migrator) Up 

func (m *Migrator) Up(step int) error

Up method runs the migrations which have not yet been run

type Schema added in v0.1.0 

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

Schema type is the schema definition

func Alter added in v0.1.0 

func Alter(tableName string, tableFunc func(t *Table)) *Schema

Alter provides callback to alter an existing table, and returns a schema

func Create 

func Create(tableName string, tableFunc func(t *Table)) *Schema

Create provides callback to create a new table, and returns a schema

func Drop added in v0.1.0 

func Drop(tableName string) *Schema

Drop returns a schema to drop a table

func NewSchema added in v0.1.0 

func NewSchema() *Schema

NewSchema creates a new schema based on the dialect provided in the environment variable DB_DRIVER

func (*Schema) Build added in v0.1.0 

func (s *Schema) Build() string

Build returns the SQL query for the schema

func (*Schema) String added in v0.1.0 

func (s *Schema) String() string

String returns the SQL query for the schema

type Table added in v0.1.0 

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

Table type is the table definition

func (*Table) AddColumn added in v0.1.0 

func (t *Table) AddColumn(name string, dataType *DataType) *Column

AddColumn adds a new column to the table

func (*Table) AlterColumn added in v0.1.0 

func (t *Table) AlterColumn(name string, dataType string) *Column

AlterColumn alters a column in the table

func (*Table) BigIncrements added in v0.1.0 

func (t *Table) BigIncrements(name string) *Column

BigIncrements adds an auto-incrementing column to the table with big integers

func (*Table) BigInt added in v0.1.2 

func (t *Table) BigInt(name string) *Column

BigInt adds a big integer column to the table

func (*Table) Binary added in v0.1.0 

func (t *Table) Binary(name string) *Column

Binary adds a binary column to the table

func (*Table) Boolean added in v0.1.0 

func (t *Table) Boolean(name string) *Column

Boolean adds a boolean column to the table

func (*Table) Char added in v0.1.0 

func (t *Table) Char(name string, length uint) *Column

Char adds a char column to the table

func (*Table) Date added in v0.1.0 

func (t *Table) Date(name string) *Column

Date adds a date column to the table

func (*Table) DateTime added in v0.1.0 

func (t *Table) DateTime(name string, precision uint) *Column

DateTime adds a date time column to the table

func (*Table) DateTimeTz added in v0.1.0 

func (t *Table) DateTimeTz(name string, precision uint) *Column

DateTimeTz adds a date time with timezone column to the table

func (*Table) Decimal added in v0.1.0 

func (t *Table) Decimal(name string, precision uint, scale uint) *Column

Decimal adds a decimal column to the table

func (*Table) Double added in v0.1.0 

func (t *Table) Double(name string, precision uint, scale uint) *Column

Double adds a double column to the table

func (*Table) DropColumn added in v0.1.0 

func (t *Table) DropColumn(name string) *Column

DropColumn drops a column from the table

func (*Table) DropForeignKey added in v0.1.0 

func (t *Table) DropForeignKey(name string)

DropForeignKey drops a foreign key from the table

func (*Table) DropIndex added in v0.1.0 

func (t *Table) DropIndex(indexName string)

DropIndex drops an index from the table

func (*Table) DropPrimaryKey added in v0.1.0 

func (t *Table) DropPrimaryKey()

DropPrimaryKey drops the primary key from the table

func (*Table) DropUniqueKey added in v0.1.1 

func (t *Table) DropUniqueKey(name string)

DropUniqueKey drops a unique constraint from the table

func (*Table) Enum added in v0.1.0 

func (t *Table) Enum(name string, values ...string) *Column

Enum adds an enum column to the table

func (*Table) Float added in v0.1.0 

func (t *Table) Float(name string, precision uint, scale uint) *Column

Float adds a float column to the table

func (*Table) ForeignKey added in v0.1.0 

func (t *Table) ForeignKey(columns ...string) *foreignKey

ForeignKey adds a foreign key to the table

func (*Table) HasConstraints added in v0.1.0 

func (t *Table) HasConstraints() bool

HasConstraints returns true if the table has constraints

func (*Table) Increments added in v0.1.0 

func (t *Table) Increments(name string) *Column

Increments adds an auto-incrementing column to the table

func (*Table) Index added in v0.1.0 

func (t *Table) Index(columns ...string)

Index adds an index to the table

func (*Table) Int added in v0.1.2 

func (t *Table) Int(name string) *Column

Int adds an integer column to the table

func (*Table) MediumInt added in v0.1.0 

func (t *Table) MediumInt(name string) *Column

MediumInt adds a medium integer column to the table

func (*Table) PrimaryKey added in v0.1.0 

func (t *Table) PrimaryKey(columns ...string)

PrimaryKey adds a primary key to the table

func (*Table) RenameColumn added in v0.1.0 

func (t *Table) RenameColumn(oldName string, newName string) *Column

RenameColumn renames a column in the table

func (*Table) SmallInt added in v0.1.0 

func (t *Table) SmallInt(name string) *Column

SmallInt adds a small integer column to the table

func (*Table) String added in v0.1.0 

func (t *Table) String(name string, length uint) *Column

String adds a varchar column to the table

func (*Table) Text added in v0.1.0 

func (t *Table) Text(name string) *Column

Text adds a text column to the table

func (*Table) Time added in v0.1.0 

func (t *Table) Time(name string, precision uint) *Column

Time adds a time column to the table

func (*Table) Timestamp added in v0.1.0 

func (t *Table) Timestamp(name string, precision uint) *Column

Timestamp adds a timestamp with timezone column to the table

func (*Table) TimestampTz added in v0.1.0 

func (t *Table) TimestampTz(name string, precision uint) *Column

Timestamp adds a timestamp with timezone column to the table

func (*Table) TinyInt added in v0.1.0 

func (t *Table) TinyInt(name string) *Column

TinyInt adds a tiny integer column to the table

func (*Table) UniqueKey added in v0.1.1 

func (t *Table) UniqueKey(columns ...string)

UniqueKey adds a unique constraint to the table

func (*Table) UnsignedBigInt added in v0.1.0 

func (t *Table) UnsignedBigInt(name string) *Column

UnsignedTinyInt adds an unsigned tiny integer column to the table

func (*Table) UnsignedInt added in v0.1.0 

func (t *Table) UnsignedInt(name string) *Column

UnsignedInt adds an unsigned integer column to the table

func (*Table) UnsignedMediumInt added in v0.1.0 

func (t *Table) UnsignedMediumInt(name string) *Column

UnsignedMediumInt adds an unsigned medium integer column to the table

func (*Table) UnsignedSmallInt added in v0.1.0 

func (t *Table) UnsignedSmallInt(name string) *Column

UnsignedSmallInt adds an unsigned small integer column to the table

func (*Table) UnsignedTinyInt added in v0.1.0 

func (t *Table) UnsignedTinyInt(name string) *Column

UnsignedTinyInt adds an unsigned tiny integer column to the table

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.