wanderer

Documentation

Overview

Package wanderer provides the development kit for working with database migrations. This feature allows teams to run and version database migrations with no conflicts in tandem with the supervisor.

Note: The wanderer is part of Blacksmith Enterprise Edition and can not be leveraged when using Blacksmith Standard Edition.

Index

• Variables
• type Driver
• type Meta
• type Migration
• type Options
• type Toolkit
• type Transition
• type Wanderer
• type WhereMigrations
• type WhereTransitions
• type WithMigrate
• type WithMigrations

Variables

var Defaults = &Options{}

Defaults are the defaults options set for the wanderer. When not set, these values will automatically be applied.

var InterfaceWanderer = "wanderer"

InterfaceWanderer is the string representation for the wanderer interface.

var StatusAcknowledged = "acknowledged"

StatusAcknowledged is used to mark a migration as acknowledged. This is used when registering new migrations into the wanderer.

var StatusDiscarded = "discarded"

StatusDiscarded is used to mark a migration as discarded. If a rollbacked migration is marked as discarded it can not be run again.

var StatusExecutingDown = "executing(down)"

StatusExecutingDown is used to inform a migration is executing its "down" logic.

var StatusExecutingUp = "executing(up)"

StatusExecutingUp is used to inform a migration is executing its "up" logic.

var StatusFailedDown = "failed(down)"

StatusFailedDown is used to inform a migration has failed to run its "up" logic.

var StatusFailedUp = "failed(up)"

StatusFailedUp is used to inform a migration has failed to run its "up" logic.

var StatusSucceededDown = "succeeded(down)"

StatusSucceededDown is used to inform a migration has succeeded its "down" logic. In other words, the migration has successfully been rollbacked.

var StatusSucceededUp = "succeeded(up)"

StatusSucceededUp is used to inform a migration has succeeded its "up" logic.

Types

type Driver

type Driver string

Driver is a custom type allowing the user to only pass supported drivers when configuring the wanderer adapter.

var DriverPostgreSQL Driver = "postgres"

DriverPostgreSQL is used to leverage PostgreSQL as the wanderer adapter.

type Meta

type Meta struct {

	// Count is the number of entries found that match the constraints applied to
	// the query (without the limit).
	Count uint16 `json:"count"`

	// Pagination is the pagination details based on the count, offset, and limit.
	Pagination *rest.Pagination `json:"pagination"`

	// Where is the constraints applied to the query to find migrations or transitions.
	// This is included in the meta because the wanderer can set defaults or override
	// some constraints (such as a maximum limit). This allows to be aware of the
	// constraints actually applied to the query.
	Where *WhereMigrations `json:"where"`
}

Meta includes information about the query's result returned by the wanderer when looking for entries (migrations or transitions).

type Migration

type Migration struct {

	// ID is the unique identifier of the migration. It must be a valid KSUID.
	//
	// Example: "1UYc8EebLqCAFMOSkbYZdJwNLAJ"
	ID string `json:"id"`

	// Version is the 14 character timestamp when the migration has been created.
	// The name of the version is of the form YYYYMMDDHHMISS, which is a UTC
	// timestamp identifying the migration.
	//
	// Example: "20060102150405"
	Version time.Time `json:"version"`

	// Scope is the string representation of the scope of the migration.
	//
	// Examples: "source:crm", "source/trigger:crm/register"
	Scope string `json:"scope"`

	// Name is the name of the migration to run or rollback. This is a part of the
	// migration's filename.
	//
	// Example: "add_rbac"
	Name string `json:"name"`

	// Direction indicates which direction is being run at the moment when running
	// or rolling back migrations. It shall be one of "up" or "down".
	Direction string `json:"-"`

	// Transitions is an array of the migration's transitions. It is used to keep
	// track of successes, failures, and errors so the wanderer is aware of the
	// migration's status.
	//
	// Note: It is up to the adapter to only return the latest migration's transition
	// since this is the only one that really matters in this context.
	Transitions [1]*Transition `json:"transitions"`

	// CreatedAt is a timestamp of the migration creation date into the wanderer
	// datastore.
	CreatedAt time.Time `json:"created_at,omitempty"`
}

Migration contains the details about a specific migration, including its up and down details.

type Options

type Options struct {

	// From is used to set the desired driver for the wanderer adapter.
	From Driver `json:"from,omitempty"`

	// Connection is the connection string to connect to the wanderer.
	Connection string `json:"-"`
}

Options is the options a user can pass to use the wanderer adapter.

type Toolkit

type Toolkit struct {

	// Logger gives access to the logrus Logger passed in options when creating the
	// Blacksmith application.
	Logger *logrus.Logger

	// WD is the rooted path name corresponding to the current directory. It can be
	// used to read a migration file in a directory.
	WD string
}

Toolkit contains a suite of utilities and data to help the adapter successfully run the wanderer functions.

type Transition

type Transition struct {

	// ID is the unique identifier of the transition. It must be a valid KSUID.
	//
	// Example: "1UYc8EebLqCAFMOSkbYZdJwNLAJ"
	ID string `json:"id"`

	// StateBefore is the state of the migration before running it. This shall be
	// nil when acknowledging the migration.
	StateBefore *string `json:"state_before"`

	// StateAfter is the state of the migration after running the new transition.
	StateAfter string `json:"state_after"`

	// Error keeps track of encountered if any.
	Error error `json:"error"`

	// CreatedAt is a timestamp of the transition creation date into the wanderer
	// datastore.
	CreatedAt time.Time `json:"created_at,omitempty"`

	// MigrationID is the ID of the migration that is being run by the transition.
	MigrationID string `json:"migration_id"`
}

Transition is used to keep track of the status of migrations.

type Wanderer

type Wanderer interface {

	// String returns the string representation of the adapter.
	//
	// Example: "postgres"
	String() string

	// Options returns the options originally passed to the Options struct. This
	// can be used to validate and override user's options if necessary.
	Options() *Options

	// AddMigrations inserts a list of migrations into the wanderer given the data
	// passed in params. It returns an error if any occurred.
	AddMigrations(*Toolkit, []*Migration) error

	// FindMigration returns a migration given the migration ID passed in params.
	FindMigration(*Toolkit, string) (*Migration, error)

	// FindMigrations returns a list of migrations matching the constraints passed
	// in params. It also returns meta information about the query, such as pagination
	// and the constraints really applied to it.
	FindMigrations(*Toolkit, *WhereMigrations) ([]*Migration, *Meta, error)

	// AddTransitions inserts a list of transitions into the datastore to update
	// their related migration status. We insert new transitions instead of updating
	// the migration itself to keep track of the migration's history.
	AddTransitions(*Toolkit, []*Transition) error

	// FindTransition returns a transition given the transition ID passed in params.
	FindTransition(*Toolkit, string) (*Transition, error)

	// FindTransitions returns a list of transitions matching the constraints passed
	// in params. It also returns meta information about the query, such as pagination
	// and the constraints really applied to it.
	FindTransitions(*Toolkit, *WhereMigrations) ([]*Transition, *Meta, error)
}

Wanderer is the interface used to persist the migrations in a datastore to keep track of migrations states.

type WhereMigrations

type WhereMigrations struct {

	// VersionBefore makes sure the entries returned by the query are related to a
	// migration versioned before this instant.
	VersionedBefore *time.Time `json:"versioned_before,omitempty"`

	// VersionAfter makes sure the entries returned by the query are related to a
	// migration versioned after this instant.
	VersionedAfter *time.Time `json:"versioned_after,omitempty"`

	// ScopeIn makes sure the entries returned by the query is related to any of
	// the scope kind present in the slice.
	ScopeIn []string `json:"scope_in,omitempty"`

	// ScopeNotIn makes sure the entries returned by the query is not related to
	// any of the scope present in the slice.
	ScopeNotIn []string `json:"scope_notin,omitempty"`

	// AndWhereTransitions lets you define additional constraints related to the
	// transitions for the migrations you are looking for.
	AndWhereTransitions *WhereTransitions `json:"transitions,omitempty"`

	// Offset specifies the number of entries to skip before starting to return entries
	// from the query.
	Offset uint16 `json:"offset"`

	// Limit specifies the number of entries to return after the offset clause has
	// been processed.
	Limit uint16 `json:"limit"`
}

WhereMigrations is used to set constraints on the migrations when looking for entries into the wanderer.

type WhereTransitions

type WhereTransitions struct {

	// MigrationID allows to find every entries related to a specific migration ID.
	//
	// Note: When set, other constraints are not applied (except parent offset and
	// limit).
	MigrationID string `json:"migration.id,omitempty"`

	// StatusIn makes sure the entries returned by the query have any of the status
	// present in the slice.
	StatusIn []string `json:"status_in,omitempty"`

	// StatusNotIn makes sure the entries returned by the query do not have any of
	// the status present in the slice.
	StatusNotIn []string `json:"status_notin,omitempty"`
}

WhereTransitions is used to set constraints on transitions when looking for entries into the wanderer.

type WithMigrate

type WithMigrate interface {

	// Migrate is the migration logic for running every migrations for a source or
	// a destination. The function gives access only to the migration that need to
	// run with the appropriate direction "up" or "down".
	//
	// Note: It is implemented by the sqlike module, offering production-ready tools
	// to integrate Blacksmith applications with SQL-like databases. See Go module
	// at https://pkg.go.dev/github.com/nunchistudio/blacksmith-modules/sqlike for
	// more details.
	Migrate(*Toolkit, *Migration) error
}

WithMigrate can be implemented by sources and destinations to benefit custom data and database schema migrations.

Note: Feature only available in Blacksmith Enterprise Edition.

type WithMigrations

type WithMigrations interface {

	// Migrations returns a slice of migrations regardless their status. The wanderer
	// will then be able to process and keep track of each and every one of them.
	//
	// Note: It is implemented by the sqlike module, offering production-ready tools
	// to integrate Blacksmith applications with SQL-like databases. See Go module
	// at https://pkg.go.dev/github.com/nunchistudio/blacksmith-modules/sqlike for
	// more details.
	Migrations(*Toolkit) ([]*Migration, error)
}

WithMigrations must be implemented by sources (and / or by their triggers) and destinations (and / or by their actions) already implementing the WithMigrate interface.

Note: Feature only available in Blacksmith Enterprise Edition.