migration

README

Data Migration

Setup Migration App

To use data migration, first create a main method in your project.

For example

package main

import (
	appconfig "github.com/cisco-open/go-lanai/pkg/appconfig/init"
	"github.com/cisco-open/go-lanai/pkg/bootstrap"
	consul "github.com/cisco-open/go-lanai/pkg/consul/init"
	"github.com/cisco-open/go-lanai/pkg/data/cassandra"
	"github.com/cisco-open/go-lanai/pkg/data/cockroach"
	data "github.com/cisco-open/go-lanai/pkg/data/init"
	"github.com/cisco-open/go-lanai/pkg/migration"
	vault "github.com/cisco-open/go-lanai/pkg/vault/init"
	"github.com/cisco-open/example/internal/migrations/v4_0"
	"go.uber.org/fx"
	"time"
)

func init() {
	// choose modules
	appconfig.Use()
	consul.Use()
	vault.Use()
	data.Use()
	cockroach.Use()
	cassandra.Use()
	migration.Use()

	v4_0.Use()
}

func main() {
	// bootstrapping
	bootstrap.NewAppCmd(
		"migrate",
		nil,
		[]fx.Option{fx.StartTimeout(1 * time.Minute)},
	)
	bootstrap.Execute()
}

1. In the init() function, declare all the packages that you want to use for your migration step. Including the package where the migration steps are defined. In this case, this is v4_0.Use()

2. In the main() method, bootstrap the migration application.

Add Migration Step

Create a package and add the migration steps

For example

package v4_0

import (
	"github.com/cisco-open/go-lanai/pkg/bootstrap"
	"github.com/cisco-open/go-lanai/pkg/log"
	"github.com/cisco-open/go-lanai/pkg/migration"
	"github.com/gocql/gocql"
	"go.uber.org/fx"
	"gorm.io/gorm"
)

var logger = log.New("migration_v4_0_0_1")

func init() {
	bootstrap.AddOptions(
		fx.Invoke(registerMigrations),
	)
}

func Use() {}

func registerMigrations(r *migration.Registrar,  cassandraSession *gocql.Session, db *gorm.DB) {
	r.AddMigrations(
		migration.WithVersion("4.0.0.1").WithTag(migration.TagPreUpgrade).WithFile("internal/migrations/v4_0/create_tenant_table.sql", db).WithDesc("create table"),
		migration.WithVersion("4.0.0.2").WithTag(migration.TagPreUpgrade).WithFunc(MoveTenantData(cassandraSession, db)).WithDesc("move data from cassandra to cockroach"),
	)
}

1. Use the standard go-lanai provider mechanism to register the migration steps
2. migration step can be either from a sql file, or a go function.
3. if your migration is a go function, you can inject any component that your migration needs as long as they are available through the declaration in the init() method of your main function.

Documentation

Index

• Constants
• Variables
• func DefaultGormConfigurerProvider() fx.Annotated
• func Migrate(ctx context.Context, r *Registrar, v Versioner) error
• func Use()
• type AppliedMigration
• type GormVersioner
  • func (v *GormVersioner) CreateVersionTableIfNotExist(ctx context.Context) error
  • func (v *GormVersioner) GetAppliedMigrations(ctx context.Context) ([]AppliedMigration, error)
  • func (v *GormVersioner) RecordAppliedMigration(ctx context.Context, version Version, description string, success bool, ...) error
• type Migration
  • func WithVersion(version string) *Migration
  • func (m *Migration) Dot(i int) *Migration
  • func (m *Migration) WithDesc(d string) *Migration
  • func (m *Migration) WithFile(fs fs.FS, filePath string, db *gorm.DB) *Migration
  • func (m *Migration) WithFunc(f MigrationFunc) *Migration
  • func (m *Migration) WithTag(tags ...string) *Migration
• type MigrationFunc
• type MigrationVersion
  • func (v MigrationVersion) GetDescription() string
  • func (v MigrationVersion) GetInstalledOn() time.Time
  • func (v MigrationVersion) GetVersion() Version
  • func (v MigrationVersion) IsSuccess() bool
• type Registrar
  • func NewRegistrar() *Registrar
  • func (r *Registrar) AddMigrations(m ...*Migration)
• type Version
  • func (v Version) Equals(o Version) bool
  • func (v Version) GormDataType() string
  • func (v Version) Lt(other Version) bool
  • func (v *Version) Scan(src interface{}) error
  • func (v Version) String() string
  • func (v Version) Value() (driver.Value, error)
• type Versioner
  • func NewGormVersioner(db *gorm.DB) Versioner

Constants

const (
	TagPreUpgrade  = "pre_upgrade"
	TagPostUpgrade = "post_upgrade"
)

Variables

var Module = &bootstrap.Module{
	Name:       "migration",
	Precedence: bootstrap.CommandLineRunnerPrecedence,
	Options: []fx.Option{
		fx.Provide(NewRegistrar),
		fx.Provide(NewGormVersioner),
		fx.Provide(provideMigrationRunner()),
	},
}

Functions

func DefaultGormConfigurerProvider

func DefaultGormConfigurerProvider() fx.Annotated

func Migrate

func Migrate(ctx context.Context, r *Registrar, v Versioner) error

func Use

func Use()

Types

type AppliedMigration

type AppliedMigration interface {
	GetVersion() Version
	GetDescription() string
	IsSuccess() bool
	GetInstalledOn() time.Time //TODO: other information
}

type GormVersioner

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

func (*GormVersioner) CreateVersionTableIfNotExist

func (v *GormVersioner) CreateVersionTableIfNotExist(ctx context.Context) error

func (*GormVersioner) GetAppliedMigrations

func (v *GormVersioner) GetAppliedMigrations(ctx context.Context) ([]AppliedMigration, error)

func (*GormVersioner) RecordAppliedMigration

func (v *GormVersioner) RecordAppliedMigration(ctx context.Context, version Version, description string, success bool, installedOn time.Time, executionTime time.Duration) error

type Migration

type Migration struct {
	Version     Version
	Description string
	Func        MigrationFunc
	Tags        utils.StringSet
}

func WithVersion

func WithVersion(version string) *Migration

func (*Migration) Dot

func (m *Migration) Dot(i int) *Migration

func (*Migration) WithDesc

func (m *Migration) WithDesc(d string) *Migration

func (*Migration) WithFile

func (m *Migration) WithFile(fs fs.FS, filePath string, db *gorm.DB) *Migration

func (*Migration) WithFunc

func (m *Migration) WithFunc(f MigrationFunc) *Migration

func (*Migration) WithTag

func (m *Migration) WithTag(tags ...string) *Migration

type MigrationFunc

type MigrationFunc func(ctx context.Context) error

type MigrationVersion

type MigrationVersion struct {
	Version       Version `gorm:"primaryKey"`
	Description   string
	ExecutionTime time.Duration
	InstalledOn   time.Time
	Success       bool
}

func (MigrationVersion) GetDescription

func (v MigrationVersion) GetDescription() string

func (MigrationVersion) GetInstalledOn

func (v MigrationVersion) GetInstalledOn() time.Time

func (MigrationVersion) GetVersion

func (v MigrationVersion) GetVersion() Version

func (MigrationVersion) IsSuccess

func (v MigrationVersion) IsSuccess() bool

type Registrar

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

func NewRegistrar

func NewRegistrar() *Registrar

func (*Registrar) AddMigrations

func (r *Registrar) AddMigrations(m ...*Migration)

type Version

type Version []int

func (Version) Equals

func (v Version) Equals(o Version) bool

func (Version) GormDataType

func (v Version) GormDataType() string

func (Version) Lt

func (v Version) Lt(other Version) bool

func (*Version) Scan

func (v *Version) Scan(src interface{}) error

func (Version) String

func (v Version) String() string

func (Version) Value

func (v Version) Value() (driver.Value, error)

type Versioner

type Versioner interface {
	CreateVersionTableIfNotExist(ctx context.Context) error
	GetAppliedMigrations(ctx context.Context) ([]AppliedMigration, error)
	RecordAppliedMigration(ctx context.Context, version Version, description string, success bool, installedOn time.Time, executionTime time.Duration) error
}

func NewGormVersioner

func NewGormVersioner(db *gorm.DB) Versioner