migrate

package
v0.4.2 Latest Latest
Warning

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

 Go to latest Published: Jun 8, 2022 License: Apache-2.0 Imports: 16 Imported by: 82

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNoPendingFiles is returned when there are no pending migration files to execute on the managed database.
	ErrNoPendingFiles = errors.New("sql/migrate: execute: nothing to do")
	// ErrLockUnsupported is returned when the given driver does not implement the schema.Locker interface.
	ErrLockUnsupported = errors.New("sql/migrate: driver does not support locking")
)
View Source 
var (
	// ErrChecksumFormat is returned from Validate if the sum files format is invalid.
	ErrChecksumFormat = errors.New("checksum file format invalid")
	// ErrChecksumMismatch is returned from Validate if the hash sums don't match.
	ErrChecksumMismatch = errors.New("checksum mismatch")
	// ErrChecksumNotFound is returned from Validate if the hash file does not exist.
	ErrChecksumNotFound = errors.New("checksum file not found")
)
View Source 
var (

	// DefaultFormatter is a default implementation for Formatter.
	DefaultFormatter = &TemplateFormatter{
		templates: []struct{ N, C *template.Template }{
			{
				N: template.Must(template.New("").Funcs(templateFuncs).Parse(
					"{{ now }}{{ with .Name }}_{{ . }}{{ end }}.sql",
				)),
				C: template.Must(template.New("").Funcs(templateFuncs).Parse(
					`{{ range .Changes }}{{ with .Comment }}-- {{ println . }}{{ end }}{{ printf "%s;\n" .Cmd }}{{ end }}`,
				)),
			},
		},
	}
)
View Source 
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.

View Source 
var ErrNotClean = errors.New("sql/migrate: connected database is not clean")

ErrNotClean is returned when the connected dev-db is not in a clean state (aka it has schemas and tables). This check is done to ensure no data is lost by overriding it when working on the dev-dn.

Functions

func Validate added in v0.3.7 

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.

func WriteSumFile added in v0.3.8 

func WriteSumFile(dir Dir, sum HashFile) error

WriteSumFile writes the given HashFile to the Dir. If the file does not exist, it is created.

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 Executor added in v0.3.8 

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

Executor is responsible to manage and execute a set of migration files against a database.

func NewExecutor added in v0.3.8 

func NewExecutor(drv Driver, dir Dir, rrw RevisionReadWriter, opts ...ExecutorOption) (*Executor, error)

NewExecutor creates a new Executor with default values. // TODO(masseelch): Operator Version and other Meta

func (*Executor) Execute added in v0.3.8 

func (e *Executor) Execute(ctx context.Context, m File) (err error)

Execute executes the given migration file on the database.

func (*Executor) ExecuteN added in v0.4.2 

func (e *Executor) ExecuteN(ctx context.Context, n int) error

ExecuteN executes n pending migration files. If n<=0 all pending migration files are executed.

func (*Executor) Lock added in v0.4.2 

func (e *Executor) Lock(ctx context.Context) (schema.UnlockFunc, error)

Lock acquires a lock for the executor. It is considered a user error to not call Lock before the Pending and Execute methods.

func (*Executor) Pending added in v0.4.2 

func (e *Executor) Pending(ctx context.Context) ([]File, error)

Pending returns all pending (not applied) migration files in the migration directory.

func (*Executor) ReadState added in v0.4.1 

func (e *Executor) ReadState(ctx context.Context) (realm *schema.Realm, err error)

ReadState implements the StateReader interface.

It does so by calling Execute and inspecting the database thereafter.

type ExecutorOption added in v0.3.8 

type ExecutorOption func(*Executor) error

ExecutorOption allows configuring an Executor using functional arguments.

func WithLogger added in v0.4.1 

func WithLogger(log Logger) ExecutorOption

WithLogger sets the Logger of an Executor.

type File added in v0.3.4 

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

File represents a single migration file.

type Formatter added in v0.3.4 

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 added in v0.3.7 

type HashFile []struct{ N, H string }

HashFile represents the integrity sum file of the migration dir.

func HashSum added in v0.3.7 

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 added in v0.3.7 

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

MarshalText implements encoding.TextMarshaler.

func (HashFile) Sum added in v0.3.7 

func (f HashFile) Sum() string

Sum returns the checksum of the represented hash file.

func (*HashFile) UnmarshalText added in v0.3.7 

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

UnmarshalText implements encoding.TextUnmarshaler.

type LocalDir added in v0.3.4 

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

LocalDir implements Dir for a local path. It implements the Scanner interface compatible with migration files generated by the DefaultFormatter.

func NewLocalDir added in v0.3.4 

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) Desc added in v0.3.8 

func (d *LocalDir) Desc(f File) (string, error)

Desc implements Scanner.Desc.

func (*LocalDir) Files added in v0.3.8 

func (d *LocalDir) Files() ([]File, error)

Files implements Scanner.Files. It looks for all files with .sql suffix and orders them by filename-

func (*LocalDir) Open added in v0.3.4 

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

Open implements fs.FS.

func (*LocalDir) Stmts added in v0.3.8 

func (d *LocalDir) Stmts(f File) ([]string, error)

Stmts implements Scanner.Stmts. It reads migration file line-by-line and expects a statement to be one line only. // TODO(masseelch): add multi-line statement support

func (*LocalDir) Version added in v0.3.8 

func (d *LocalDir) Version(f File) (string, error)

Version implements Scanner.Version.

func (*LocalDir) WriteFile added in v0.3.5 

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

WriteFile implements Dir.WriteFile.

type LocalFile added in v0.3.8 

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

LocalFile is used by LocalDir to implement the Scanner interface.

func (LocalFile) Name added in v0.3.8 

func (f LocalFile) Name() string

Name implements File.Name.

func (LocalFile) Read added in v0.3.8 

func (f LocalFile) Read(buf []byte) (int, error)

Read implements io.Reader.

type LogDone added in v0.4.2 

type LogDone struct{}

LogDone is sent if the execution is done.

type LogEntry added in v0.4.1 

type LogEntry interface {
	// contains filtered or unexported methods
}

LogEntry marks several types of logs to be passed to a Logger.

type LogExecution added in v0.4.1 

type LogExecution struct {
	// From what version.
	From string
	// To what version.
	To string
	// Migration Files to be executed.
	Files []string
}

LogExecution is sent once when execution of multiple migration files has been started. It holds the filenames of the pending migration files.

type LogFile added in v0.4.1 

type LogFile struct {
	// Version executed.
	Version string
	// Desc of migration executed.
	Desc string
}

LogFile is sent if a new migration file is executed.

type LogStmt added in v0.4.1 

type LogStmt struct {
	SQL string
}

LogStmt is sent if a new SQL statement is executed.

type Logger added in v0.4.1 

type Logger interface {
	Log(LogEntry)
}

A Logger logs migration execution.

type NopRevisionReadWriter added in v0.4.2 

type NopRevisionReadWriter struct{}

NopRevisionReadWriter is a RevisionsReadWriter that does nothing. It is useful for one-time replay of the migration directory.

func (NopRevisionReadWriter) ReadRevisions added in v0.4.2 

func (NopRevisionReadWriter) ReadRevisions(context.Context) (Revisions, error)

ReadRevisions implements RevisionsReadWriter.ReadRevisions,

func (NopRevisionReadWriter) WriteRevision added in v0.4.2 

func (NopRevisionReadWriter) WriteRevision(context.Context, *Revision) error

WriteRevision implements RevisionsReadWriter.WriteRevision,

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 added in v0.3.4 

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 added in v0.3.7 

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

NewPlanner creates a new Planner.

func (*Planner) Plan added in v0.3.4 

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 added in v0.3.4 

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

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

type PlannerOption added in v0.3.7 

type PlannerOption func(*Planner)

PlannerOption allows managing a Planner using functional arguments.

func DisableChecksum added in v0.3.7 

func DisableChecksum() PlannerOption

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

func WithFormatter added in v0.3.7 

func WithFormatter(fmt Formatter) PlannerOption

WithFormatter sets the Formatter of a Planner.

type Revision added in v0.3.8 

type Revision struct {
	// Version of the migration.
	Version string
	// Description of this migration.
	Description string
	// ExecutionState of this migration. One of ["ongoing", "ok", "error"].
	ExecutionState string
	// ExecutedAt denotes when this migration was started to be executed.
	ExecutedAt time.Time
	// ExecutionTime denotes the time it took for this migration to be applied on the database.
	ExecutionTime time.Duration
	// Error holds information about a migration error (if occurred).
	// If the error is from the application level, it is prefixed with "Go:\n".
	// If the error is raised from the database, Error contains both the failed statement and the database error
	// following the "SQL:\n<sql>\n\nError:\n<err>" format.
	Error string
	// Hash is the check-sum of this migration as stated by the migration directories HashFile.
	Hash string
	// OperatorVersion holds a string representation of the Atlas operator managing this database migration.
	OperatorVersion string
	// Meta holds additional custom meta-data given for this migration.
	Meta map[string]string
}

A Revision denotes an applied migration in a deployment. Used to track migration executions state of a database.

type RevisionReadWriter added in v0.3.8 

type RevisionReadWriter interface {
	ReadRevisions(context.Context) (Revisions, error)
	WriteRevision(context.Context, *Revision) error
}

A RevisionReadWriter reads and writes information about a Revisions to a persistent storage. If the implementation happens provide an "Init() error" method, it will be called once before attempting to read or write.

Atlas drivers provide a sql based implementation of this interface by default.

type Revisions added in v0.3.8 

type Revisions []*Revision

Revisions is an ordered set of Revision structs.

type Scanner added in v0.3.8 

type Scanner interface {
	// Files returns a set of files from the given Dir to be executed on a database.
	Files() ([]File, error)
	// Stmts returns a set of SQL statements from the given File to be executed on a database.
	Stmts(File) ([]string, error)
	// Version returns the version of the migration File.
	Version(File) (string, error)
	// Desc returns the description of the migration File.
	Desc(File) (string, error)
}

Scanner wraps several methods to interpret a migration Dir.

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 Conn added in v0.3.8 

func Conn(drv Driver, opts *schema.InspectRealmOption) StateReader

Conn returns a StateReader for a Driver.

func Realm 

func Realm(r *schema.Realm) StateReader

Realm returns a StateReader for the static Realm object.

func Schema 

func Schema(s *schema.Schema) StateReader

Schema returns a StateReader 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 (StateReaderFunc) ReadState 

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

ReadState calls f(ctx).

type TemplateFormatter added in v0.3.4 

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

TemplateFormatter implements Formatter by using templates.

func NewTemplateFormatter added in v0.3.4 

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 added in v0.3.4 

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

Format implements the Formatter interface.

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.