migration

package
v1.20220411.3 Latest Latest
Warning

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

 Go to latest Published: Apr 11, 2022 License: MIT Imports: 10 Imported by: 4

Documentation

Overview

Package migration provides helpers for writing rerunnable database migrations.

These are built around Suites, which are sets of Groups that execute within a transaction, those Groups are composed of Steps, which are a Guard and an Action.

Index

Constants

View Source 
const (
	StatApplied = "applied"
	StatFailed  = "failed"
	StatSkipped = "skipped"
	StatTotal   = "total"
)

Migration Stats

View Source 
const (
	// Flag is a logger event flag.
	Flag = "db.migration"
	// FlagStats is a logger event flag.
	FlagStats = "db.migration.stats"
)

Variables

This section is empty.

Functions

func GetContextLabels added in v1.20201204.1 

func GetContextLabels(ctx context.Context) []string

GetContextLabels gets a group from a context as a value.

func NoOp 

func NoOp(_ context.Context, _ *db.Connection, _ *sql.Tx) error

NoOp performs no action.

func Not added in v1.20201204.1 

func Not(proceed bool, err error) (bool, error)

Not inverts the output of a predicate.

func PredicateAny added in v1.20201204.1 

func PredicateAny(ctx context.Context, c *db.Connection, tx *sql.Tx, selectStatement string, params ...interface{}) (bool, error)

PredicateAny returns if a statement has results.

func PredicateColumnExists added in v1.20201204.1 

func PredicateColumnExists(ctx context.Context, c *db.Connection, tx *sql.Tx, tableName, columnName string) (bool, error)

PredicateColumnExists returns if a column exists on a table in the default schema of the given connection.

func PredicateColumnExistsInSchema added in v1.20201204.1 

func PredicateColumnExistsInSchema(ctx context.Context, c *db.Connection, tx *sql.Tx, schemaName, tableName, columnName string) (bool, error)

PredicateColumnExistsInSchema returns if a column exists on a table in a specific schema on the given connection.

func PredicateConstraintExists added in v1.20201204.1 

func PredicateConstraintExists(ctx context.Context, c *db.Connection, tx *sql.Tx, tableName, constraintName string) (bool, error)

PredicateConstraintExists returns if a constraint exists on a table in the default schema of the given connection.

func PredicateConstraintExistsInSchema added in v1.20201204.1 

func PredicateConstraintExistsInSchema(ctx context.Context, c *db.Connection, tx *sql.Tx, schemaName, tableName, constraintName string) (bool, error)

PredicateConstraintExistsInSchema returns if a constraint exists on a table in a specific schema on the given connection.

func PredicateIndexExists added in v1.20201204.1 

func PredicateIndexExists(ctx context.Context, c *db.Connection, tx *sql.Tx, tableName, indexName string) (bool, error)

PredicateIndexExists returns if a index exists on a table in the default schema of the given connection.

func PredicateIndexExistsInSchema added in v1.20201204.1 

func PredicateIndexExistsInSchema(ctx context.Context, c *db.Connection, tx *sql.Tx, schemaName, tableName, indexName string) (bool, error)

PredicateIndexExistsInSchema returns if a index exists on a table in a specific schema on the given connection.

func PredicateNone added in v1.20201204.1 

func PredicateNone(ctx context.Context, c *db.Connection, tx *sql.Tx, selectStatement string, params ...interface{}) (bool, error)

PredicateNone returns if a statement doesnt have results.

func PredicateRoleExists added in v1.20201204.1 

func PredicateRoleExists(ctx context.Context, c *db.Connection, tx *sql.Tx, roleName string) (bool, error)

PredicateRoleExists returns if a role exists or not.

func PredicateSchemaExists added in v1.20201204.1 

func PredicateSchemaExists(ctx context.Context, c *db.Connection, tx *sql.Tx, schemaName string) (bool, error)

PredicateSchemaExists returns if a schema exists or not.

func PredicateTableExists added in v1.20201204.1 

func PredicateTableExists(ctx context.Context, c *db.Connection, tx *sql.Tx, tableName string) (bool, error)

PredicateTableExists returns if a table exists in the default schema of the given connection.

func PredicateTableExistsInSchema added in v1.20201204.1 

func PredicateTableExistsInSchema(ctx context.Context, c *db.Connection, tx *sql.Tx, schemaName, tableName string) (bool, error)

PredicateTableExistsInSchema returns if a table exists in a specific schema on the given connection.

func WithLabel added in v1.20201204.1 

func WithLabel(ctx context.Context, label string) context.Context

WithLabel adds a label to the context

func WithSuite added in v1.20201204.1 

func WithSuite(ctx context.Context, suite *Suite) context.Context

WithSuite adds a suite as a value to a context.

Types

type Action added in v1.20201204.1 

type Action interface {
	Action(context.Context, *db.Connection, *sql.Tx) error
}

Action is a type that represents a migration action.

func Actions 

func Actions(actions ...Action) Action

Actions creates an Action with a single body func that executes all the variadic argument actions serially

func Exec added in v1.20201204.1 

func Exec(statement string, args ...interface{}) Action

Exec creates an Action that will run a statement with a given set of arguments. It can be used in lieu of Statements, when parameterization is needed

func Statements 

func Statements(statements ...string) Action

Statements returns a body func that executes the statments serially.

type ActionFunc added in v1.20210410.1 

type ActionFunc func(context.Context, *db.Connection, *sql.Tx) error

ActionFunc is a function that can be run during a migration step.

func (ActionFunc) Action added in v1.20210410.1 

func (a ActionFunc) Action(ctx context.Context, conn *db.Connection, tx *sql.Tx) error

Action implements actioner.

type Event 

type Event struct {
	Result string
	Body   string
	Labels []string
}

Event is a migration logger event.

func NewEvent 

func NewEvent(result, body string, labels ...string) *Event

NewEvent returns a new event.

func (Event) Decompose added in v1.20201204.1 

func (e Event) Decompose() map[string]interface{}

Decompose implements logger.JSONWritable.

func (Event) GetFlag added in v1.20201204.1 

func (e Event) GetFlag() string

GetFlag implements logger.Event.

func (Event) WriteText 

func (e Event) WriteText(tf logger.TextFormatter, wr io.Writer)

WriteText writes the migration event as text.

type Group 

type Group struct {
	Actions         []Action
	Tx              *sql.Tx
	SkipTransaction bool
}

Group is an series of migration actions. It uses normally transactions to apply these actions as an atomic unit, but this transaction can be bypassed by setting the SkipTransaction flag to true. This allows the use of CONCURRENT index creation and other operations that postgres will not allow within a transaction.

func NewGroup 

func NewGroup(options ...GroupOption) *Group

NewGroup creates a new Group from a given list of actionable.

func NewGroupWithAction added in v1.20201204.1 

func NewGroupWithAction(guard GuardFunc, action Action, options ...GroupOption) *Group

NewGroupWithAction returns a new group with a single action.

func (*Group) Action added in v1.20201204.1 

func (ga *Group) Action(ctx context.Context, c *db.Connection) (err error)

Action runs the groups actions within a transaction.

type GroupOption added in v1.20201204.1 

type GroupOption func(g *Group)

GroupOption is an option for migration Groups (Group)

func OptGroupActions added in v1.20201204.1 

func OptGroupActions(actions ...Action) GroupOption

OptGroupActions allows you to add actions to the NewGroup. If you want, multiple OptActions can be applied to the same NewGroup. They are additive.

func OptGroupSkipTransaction added in v1.20201204.1 

func OptGroupSkipTransaction() GroupOption

OptGroupSkipTransaction will allow this group to be run outside of a transaction. Use this to concurrently create indices and perform other actions that cannot be executed in a Tx

func OptGroupTx added in v1.20201204.1 

func OptGroupTx(tx *sql.Tx) GroupOption

OptGroupTx sets a transaction on the group.

type GuardFunc 

type GuardFunc func(context.Context, *db.Connection, *sql.Tx, Action) error

GuardFunc is a control for migration steps. It should internally evaluate if the action should be called. The action is typically given separately so these two components can be composed.

func Always added in v1.20201204.1 

func Always() GuardFunc

Always always runs a step.

func ColumnExists 

func ColumnExists(tableName, columnName string) GuardFunc

ColumnExists returns a guard that ensures a column exists

func ColumnExistsInSchema added in v1.20201204.1 

func ColumnExistsInSchema(schemaName, tableName, columnName string) GuardFunc

ColumnExistsInSchema returns a guard that ensures a column exists

func ColumnNotExists 

func ColumnNotExists(tableName, columnName string) GuardFunc

ColumnNotExists returns a guard that ensures a column does not exist

func ColumnNotExistsInSchema added in v1.20201204.1 

func ColumnNotExistsInSchema(schemaName, tableName, columnName string) GuardFunc

ColumnNotExistsInSchema returns a guard that ensures a column does not exist

func ConstraintExists 

func ConstraintExists(tableName, constraintName string) GuardFunc

ConstraintExists returns a guard that ensures a constraint exists

func ConstraintExistsInSchema added in v1.20201204.1 

func ConstraintExistsInSchema(schemaName, tableName, constraintName string) GuardFunc

ConstraintExistsInSchema returns a guard that ensures a constraint exists

func ConstraintNotExists 

func ConstraintNotExists(tableName, constraintName string) GuardFunc

ConstraintNotExists returns a guard that ensures a constraint does not exist

func ConstraintNotExistsInSchema added in v1.20201204.1 

func ConstraintNotExistsInSchema(schemaName, tableName, constraintName string) GuardFunc

ConstraintNotExistsInSchema returns a guard that ensures a constraint does not exist

func Guard 

func Guard(description string, predicate GuardPredicateFunc) GuardFunc

Guard returns a function that determines if a step in a group should run.

func IfExists 

func IfExists(statement string, args ...interface{}) GuardFunc

IfExists only runs the statement if the given item exists.

func IfNotExists 

func IfNotExists(statement string, args ...interface{}) GuardFunc

IfNotExists only runs the statement if the given item doesn't exist.

func IndexExists 

func IndexExists(tableName, indexName string) GuardFunc

IndexExists returns a guard that ensures an index exists

func IndexExistsInSchema added in v1.20201204.1 

func IndexExistsInSchema(schemaName, tableName, indexName string) GuardFunc

IndexExistsInSchema returns a guard that ensures an index exists

func IndexNotExists 

func IndexNotExists(tableName, indexName string) GuardFunc

IndexNotExists returns a guard that ensures an index does not exist

func IndexNotExistsInSchema added in v1.20201204.1 

func IndexNotExistsInSchema(schemaName, tableName, indexName string) GuardFunc

IndexNotExistsInSchema returns a guard that ensures an index does not exist

func RoleExists 

func RoleExists(roleName string) GuardFunc

RoleExists returns a guard that ensures a role (user) exists

func RoleNotExists 

func RoleNotExists(roleName string) GuardFunc

RoleNotExists returns a guard that ensures a role (user) does not exist

func SchemaExists added in v1.20201204.1 

func SchemaExists(schemaName string) GuardFunc

SchemaExists is a guard function for asserting that a schema exists

func SchemaNotExists added in v1.20201204.1 

func SchemaNotExists(schemaName string) GuardFunc

SchemaNotExists is a guard function for asserting that a schema does not exist

func TableExists 

func TableExists(tableName string) GuardFunc

TableExists returns a guard that ensures a table exists

func TableExistsInSchema added in v1.20201204.1 

func TableExistsInSchema(schemaName, tableName string) GuardFunc

TableExistsInSchema returns a guard that ensures a table exists

func TableNotExists 

func TableNotExists(tableName string) GuardFunc

TableNotExists returns a guard that ensures a table does not exist

func TableNotExistsInSchema added in v1.20201204.1 

func TableNotExistsInSchema(schemaName, tableName string) GuardFunc

TableNotExistsInSchema returns a guard that ensures a table exists

type GuardPredicateFunc added in v1.20201204.1 

type GuardPredicateFunc func(context.Context, *db.Connection, *sql.Tx) (bool, error)

GuardPredicateFunc is a function that can act as a guard

type StatsEvent 

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

StatsEvent is a migration logger event.

func NewStatsEvent 

func NewStatsEvent(applied, skipped, failed, total int) *StatsEvent

NewStatsEvent returns a new stats event.

func (StatsEvent) Decompose added in v1.20201204.1 

func (se StatsEvent) Decompose() map[string]interface{}

Decompose implements logger.JSONWritable.

func (StatsEvent) GetFlag added in v1.20201204.1 

func (se StatsEvent) GetFlag() string

GetFlag implements logger.Event.

func (StatsEvent) WriteText 

func (se StatsEvent) WriteText(tf logger.TextFormatter, wr io.Writer)

WriteText writes the event to a text writer.

type Step 

type Step struct {
	Guard GuardFunc
	Body  Action
}

Step is a guarded action. The GuardFunc will decide whether to execute this Action

func NewStep 

func NewStep(guard GuardFunc, action Action) *Step

NewStep returns a new Step, given a GuardFunc and an Action

func (*Step) Action added in v1.20201204.1 

func (ga *Step) Action(ctx context.Context, c *db.Connection, tx *sql.Tx) error

Action implements the Actionable interface and runs the body if the provided guard passes.

type Suite 

type Suite struct {
	Log    logger.Log
	Groups []*Group

	Applied int
	Skipped int
	Failed  int
	Total   int
}

Suite is a migration suite.

func GetContextSuite added in v1.20201204.1 

func GetContextSuite(ctx context.Context) *Suite

GetContextSuite gets a suite from a context as a value.

func New 

func New(options ...SuiteOption) *Suite

New returns a new suite of groups.

func NewWithActions added in v1.20201204.1 

func NewWithActions(actions ...Action) *Suite

NewWithActions returns a new suite, with a new group, made up of given actions.

func (*Suite) Apply 

func (s *Suite) Apply(ctx context.Context, c *db.Connection) (err error)

Apply applies the suite.

func (*Suite) Applyf added in v1.20201204.1 

func (s *Suite) Applyf(ctx context.Context, format string, args ...interface{})

Applyf writes an applied step message.

func (*Suite) Error added in v1.20201204.1 

func (s *Suite) Error(ctx context.Context, err error) error

Error

func (*Suite) Errorf added in v1.20201204.1 

func (s *Suite) Errorf(ctx context.Context, format string, args ...interface{})

Errorf writes an error for a given step.

func (*Suite) Results added in v1.20201204.1 

func (s *Suite) Results() (applied, skipped, failed, total int)

Results provides a window into the results of this migration

func (*Suite) Skipf added in v1.20201204.1 

func (s *Suite) Skipf(ctx context.Context, format string, args ...interface{})

Skipf skips a given step.

func (*Suite) Write added in v1.20201204.1 

func (s *Suite) Write(ctx context.Context, result, body string)

func (*Suite) WriteStats added in v1.20201204.1 

func (s *Suite) WriteStats(ctx context.Context)

WriteStats writes the stats if a logger is configured.

type SuiteOption added in v1.20201204.1 

type SuiteOption func(s *Suite)

SuiteOption is an option for migration Suites

func OptGroups added in v1.20201204.1 

func OptGroups(groups ...*Group) SuiteOption

OptGroups allows you to add groups to the Suite. If you want, multiple OptGroups can be applied to the same Suite. They are additive.

func OptLog added in v1.20201204.1 

func OptLog(log logger.Log) SuiteOption

OptLog allows you to add a logger to the Suite.

Source Files

View all Source files

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.