migrate

Documentation

Index

• Variables
• func Validate(dir Dir) error
• type Change
• type Dir
• type Driver
• type File
• type Formatter
• type HashFile
  • func HashSum(dir Dir) (HashFile, error)
  • func (s HashFile) MarshalText() ([]byte, error)
  • func (s HashFile) Sum() string
  • func (s *HashFile) UnmarshalText(b []byte) error
• type LocalDir
  • func NewLocalDir(path string) (*LocalDir, error)
  • func (d *LocalDir) Open(name string) (fs.File, error)
  • func (d *LocalDir) WriteFile(name string, b []byte) error
• type Plan
• type PlanApplier
• type Planner
  • func NewPlanner(drv Driver, dir Dir, opts ...PlannerOption) *Planner
  • func (p *Planner) Plan(ctx context.Context, name string, to StateReader) (*Plan, error)
  • func (p *Planner) WritePlan(plan *Plan) error
• type PlannerOption
  • func DisableChecksum() PlannerOption
  • func WithFormatter(fmt Formatter) PlannerOption
  • func WithStateReader(dsr StateReader) PlannerOption
• type StateReader
  • func Realm(r *schema.Realm) StateReader
  • func Schema(s *schema.Schema) StateReader
• type StateReaderFunc
  • func GlobStateReader(dir Dir, drv Driver, glob string) StateReaderFunc
  • func (f StateReaderFunc) ReadState(ctx context.Context) (*schema.Realm, error)
• type TemplateFormatter
  • func NewTemplateFormatter(templates ...*template.Template) (*TemplateFormatter, error)
  • func (t *TemplateFormatter) Format(plan *Plan) ([]File, error)

Variables

var (

	// DefaultFormatter is a default implementation for Formatter. Compatible with golang-migrate/migrate.
	DefaultFormatter = &TemplateFormatter{
		templates: []struct{ N, C *template.Template }{
			{
				N: template.Must(template.New("").Funcs(templateFuncs).Parse(
					"{{ now.Unix }}{{ with .Name }}_{{ . }}{{ end }}.up.sql",
				)),
				C: template.Must(template.New("").Funcs(templateFuncs).Parse(
					"{{ range .Changes }}{{ println (sem .Cmd) }}{{ end }}",
				)),
			},
			{
				N: template.Must(template.New("").Funcs(templateFuncs).Parse(
					"{{ now.Unix }}{{ with .Name }}_{{ . }}{{ end }}.down.sql",
				)),
				C: template.Must(template.New("").Funcs(templateFuncs).Parse(
					"{{ range rev .Changes }}{{ with .Reverse }}{{ println (sem .) }}{{ end }}{{ end }}",
				)),
			},
		},
	}
)

var ErrChecksumMismatch = errors.New("checksum mismatch")

ErrChecksumMismatch is returned from Validate if the hash sums don't match.

var ErrNoPlan = errors.New("sql/migrate: no plan for matched states")

ErrNoPlan is returned by Plan when there is no change between the two states.

Functions

func Validate

func Validate(dir Dir) error

Validate checks if the migration dir is in sync with its sum file. If they don't match ErrChecksumMismatch is returned.

Types

type Change

type Change struct {
	// Cmd or statement to execute.
	Cmd string

	// Args for placeholder parameters in the statement above.
	Args []interface{}

	// A Comment describes the change.
	Comment string

	// Reverse contains the "reversed statement" if
	// command is reversible.
	Reverse string

	// The Source that caused this change, or nil.
	Source schema.Change
}

A Change of migration.

type Dir

type Dir interface {
	fs.FS

	// WriteFile writes the data to the named file.
	WriteFile(string, []byte) error
}

Dir describes the methods needed for a Planner to manage migration files.

type Driver

type Driver interface {
	schema.Differ
	schema.ExecQuerier
	schema.Inspector
	PlanApplier
}

The Driver interface must be implemented by the different dialects to support database migration authoring/planning and applying. ExecQuerier, Inspector and Differ, provide basic schema primitives for inspecting database schemas, calculate the difference between schema elements, and executing raw SQL statements. The PlanApplier interface wraps the methods for generating migration plan for applying the actual changes on the database.

type File

type File interface {
	io.Reader
	// Name returns the name of the FormattedFile.
	Name() string
}

File represents a single migration file.

type Formatter

type Formatter interface {
	// Format formats the given Plan into one or more migration files.
	Format(*Plan) ([]File, error)
}

Formatter wraps the Format method.

type HashFile

type HashFile []struct{ N, H string }

HashFile represents the integrity sum file of the migration dir.

func HashSum

func HashSum(dir Dir) (HashFile, error)

HashSum reads the whole dir, sorts the files by name and creates a HashSum from its contents.

func (HashFile) MarshalText

func (s HashFile) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (HashFile) Sum

func (s HashFile) Sum() string

Sum returns the checksum of the represented hash file.

func (*HashFile) UnmarshalText

func (s *HashFile) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type LocalDir

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

LocalDir implements Dir for a local path.

func NewLocalDir

func NewLocalDir(path string) (*LocalDir, error)

NewLocalDir returns a new the Dir used by a Planner to work on the given local path.

func (*LocalDir) Open

func (d *LocalDir) Open(name string) (fs.File, error)

Open implements fs.FS.

func (*LocalDir) WriteFile

func (d *LocalDir) WriteFile(name string, b []byte) error

WriteFile implements Dir.WriteFile.

type Plan

type Plan struct {
	// Name of the plan. Provided by the user or auto-generated.
	Name string

	// Reversible describes if the changeset is reversible.
	Reversible bool

	// Transactional describes if the changeset is transactional.
	Transactional bool

	// Changes defines the list of changeset in the plan.
	Changes []*Change
}

A Plan defines a planned changeset that its execution brings the database to the new desired state. Additional information is calculated by the different drivers to indicate if the changeset is transactional (can be rolled-back) and reversible (a down file can be generated to it).

type PlanApplier

type PlanApplier interface {
	// PlanChanges returns a migration plan for applying the given changeset.
	PlanChanges(context.Context, string, []schema.Change) (*Plan, error)

	// ApplyChanges is responsible for applying the given changeset.
	// An error may return from ApplyChanges if the driver is unable
	// to execute a change.
	ApplyChanges(context.Context, []schema.Change) error
}

PlanApplier wraps the methods for planning and applying changes on the database.

type Planner

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

Planner can plan the steps to take to migrate from one state to another. It uses the enclosed FS to write those changes to versioned migration files.

func NewPlanner

func NewPlanner(drv Driver, dir Dir, opts ...PlannerOption) *Planner

NewPlanner creates a new Planner.

func (*Planner) Plan

func (p *Planner) Plan(ctx context.Context, name string, to StateReader) (*Plan, error)

Plan calculates the migration Plan required for moving the current state (from) state to the next state (to). A StateReader can be a directory, static schema elements or a Driver connection.

func (*Planner) WritePlan

func (p *Planner) WritePlan(plan *Plan) error

WritePlan writes the given Plan to the Dir based on the configured Formatter.

type PlannerOption

type PlannerOption func(*Planner)

PlannerOption allows managing a Planner using functional arguments.

func DisableChecksum

func DisableChecksum() PlannerOption

DisableChecksum disables the hash-sum functionality for the migration directory.

func WithFormatter

func WithFormatter(fmt Formatter) PlannerOption

WithFormatter sets the Formatter of a Planner.

func WithStateReader

func WithStateReader(dsr StateReader) PlannerOption

WithStateReader sets the StateReader of a Planner.

type StateReader

type StateReader interface {
	ReadState(ctx context.Context) (*schema.Realm, error)
}

StateReader wraps the method for reading a database/schema state. The types below provides a few builtin options for reading a state from a migration directory, a static object (e.g. a parsed file).

In next Go version, the State will be replaced with the following union type `interface { Realm | Schema }`.

func Realm

func Realm(r *schema.Realm) StateReader

Realm returns a state reader for the static Realm object.

func Schema

func Schema(s *schema.Schema) StateReader

Schema returns a state reader for the static Schema object.

type StateReaderFunc

type StateReaderFunc func(ctx context.Context) (*schema.Realm, error)

The StateReaderFunc type is an adapter to allow the use of ordinary functions as state readers.

func GlobStateReader

func GlobStateReader(dir Dir, drv Driver, glob string) StateReaderFunc

GlobStateReader creates a StateReader that loads all files from Dir matching glob in lexicographic order and uses the Driver to create a migration state.

func (StateReaderFunc) ReadState

func (f StateReaderFunc) ReadState(ctx context.Context) (*schema.Realm, error)

ReadState calls f(ctx).

type TemplateFormatter

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

TemplateFormatter implements Formatter by using templates.

func NewTemplateFormatter

func NewTemplateFormatter(templates ...*template.Template) (*TemplateFormatter, error)

NewTemplateFormatter creates a new Formatter working with the given templates.

migrate.NewTemplateFormatter(
	template.Must(template.New("").Parse("{{now.Unix}}{{.Name}}.sql")),                 // name template
	template.Must(template.New("").Parse("{{range .Changes}}{{println .Cmd}}{{end}}")), // content template
)

func (*TemplateFormatter) Format

func (t *TemplateFormatter) Format(plan *Plan) ([]File, error)

Format implements the Formatter interface.