Documentation ¶
Index ¶
- Constants
- Variables
- func ArchiveDir(dir Dir) ([]byte, error)
- func ArchiveDirTo(w io.Writer, dir Dir) error
- func FileStmts(drv Driver, f File) ([]string, error)
- func FilesLastIndex[F File](files []F, f func(F) bool) int
- func LogIntro(l Logger, revs []*Revision, files []File)
- func LogNoPendingFiles(l Logger, revs []*Revision)
- func NewVersion() string
- func Validate(dir Dir) error
- func WriteSumFile(dir Dir, sum HashFile) error
- type Change
- type CheckpointDir
- type CheckpointFile
- type ChecksumError
- type CleanChecker
- type Dir
- type Driver
- type ExecOrder
- type Executor
- func (e *Executor) Execute(ctx context.Context, m File) (err error)
- func (e *Executor) ExecuteN(ctx context.Context, n int) (err error)
- func (e *Executor) ExecuteTo(ctx context.Context, version string) (err error)
- func (e *Executor) Pending(ctx context.Context) ([]File, error)
- func (e *Executor) Replay(ctx context.Context, r StateReader, opts ...ReplayOption) (_ *schema.Realm, err error)
- func (e *Executor) ValidateDir(context.Context) error
- type ExecutorOption
- type File
- type Formatter
- type HashFile
- type HistoryChangedError
- type HistoryNonLinearError
- type LocalDir
- func (d *LocalDir) CheckpointFiles() ([]File, error)
- func (d *LocalDir) Checksum() (HashFile, error)
- func (d *LocalDir) Files() ([]File, error)
- func (d *LocalDir) FilesFromCheckpoint(name string) ([]File, error)
- func (d *LocalDir) Open(name string) (fs.File, error)
- func (d *LocalDir) Path() string
- func (d *LocalDir) WriteCheckpoint(name, tag string, b []byte) error
- func (d *LocalDir) WriteFile(name string, b []byte) error
- type LocalFile
- func (f *LocalFile) AddDirective(name string, args ...string)
- func (f *LocalFile) Bytes() []byte
- func (f *LocalFile) CheckpointTag() (string, error)
- func (f *LocalFile) Desc() string
- func (f *LocalFile) Directive(name string) (ds []string)
- func (f *LocalFile) IsCheckpoint() bool
- func (f *LocalFile) Name() string
- func (f *LocalFile) StmtDecls() ([]*Stmt, error)
- func (f *LocalFile) Stmts() ([]string, error)
- func (f *LocalFile) Version() string
- type LogCheck
- type LogChecks
- type LogChecksDone
- type LogDone
- type LogEntry
- type LogError
- type LogExecution
- type LogFile
- type LogStmt
- type Logger
- type MemDir
- func (d *MemDir) CheckpointFiles() ([]File, error)
- func (d *MemDir) Checksum() (HashFile, error)
- func (d *MemDir) Close() error
- func (d *MemDir) CopyFiles(fs []File) error
- func (d *MemDir) Files() ([]File, error)
- func (d *MemDir) FilesFromCheckpoint(name string) ([]File, error)
- func (d *MemDir) Open(name string) (fs.File, error)
- func (d *MemDir) Reset()
- func (d *MemDir) SyncWrites(fs ...func(string, []byte) error)
- func (d *MemDir) WriteCheckpoint(name, tag string, b []byte) error
- func (d *MemDir) WriteFile(name string, data []byte) error
- type MissingMigrationError
- type NopLogger
- type NopRevisionReadWriter
- func (NopRevisionReadWriter) DeleteRevision(context.Context, string) error
- func (NopRevisionReadWriter) Ident() *TableIdent
- func (NopRevisionReadWriter) ReadRevision(context.Context, string) (*Revision, error)
- func (NopRevisionReadWriter) ReadRevisions(context.Context) ([]*Revision, error)
- func (NopRevisionReadWriter) WriteRevision(context.Context, *Revision) error
- type NotCleanError
- type Plan
- type PlanApplier
- type PlanMode
- type PlanOption
- type PlanOptions
- type Planner
- func (p *Planner) Checkpoint(ctx context.Context, name string) (*Plan, error)
- func (p *Planner) CheckpointSchema(ctx context.Context, name string) (*Plan, error)
- func (p *Planner) Plan(ctx context.Context, name string, to StateReader) (*Plan, error)
- func (p *Planner) PlanSchema(ctx context.Context, name string, to StateReader) (*Plan, error)
- func (p *Planner) WriteCheckpoint(plan *Plan, tag string) error
- func (p *Planner) WritePlan(plan *Plan) error
- type PlannerOption
- func PlanFormat(fmt Formatter) PlannerOption
- func PlanWithChecksum(b bool) PlannerOption
- func PlanWithDiffOptions(opts ...schema.DiffOption) PlannerOption
- func PlanWithIndent(indent string) PlannerOption
- func PlanWithMode(m PlanMode) PlannerOption
- func PlanWithSchemaQualifier(q string) PlannerOption
- type Reason
- type ReplayOption
- type RestoreFunc
- type Revision
- type RevisionReadWriter
- type RevisionType
- type Scanner
- type ScannerOptions
- type Snapshoter
- type StateReader
- type StateReaderFunc
- type Stmt
- type StmtScanner
- type TableIdent
- type TemplateFormatter
Constants ¶
const HashFileName = "atlas.sum"
HashFileName of the migration directory integrity sum file.
Variables ¶
var ( // ErrNotCheckpoint is returned when calling CheckpointFile methods on a non-checkpoint file. ErrNotCheckpoint = errors.New("not a checkpoint file") // ErrCheckpointNotFound is returned when a checkpoint file is not found in the directory. ErrCheckpointNotFound = errors.New("no checkpoint found") )
var ( // ErrChecksumFormat is returned from Validate if the sum files format is invalid. ErrChecksumFormat = errors.New("checksum file format invalid") // ErrChecksumMismatch is returned when unmarshalling from a sum file and the files sum entries 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") )
var ( // WithFormatter calls PlanFormat. // Deprecated: use PlanFormat instead. WithFormatter = PlanFormat // DisableChecksum calls PlanWithChecksum(false). // Deprecated: use PlanWithoutChecksum instead. DisableChecksum = func() PlannerOption { return PlanWithChecksum(false) } )
var ( // ErrNoPendingFiles is returned if there are no pending migration files to execute on the managed database. ErrNoPendingFiles = errors.New("sql/migrate: no pending migration files") // ErrSnapshotUnsupported is returned if there is no Snapshoter given. ErrSnapshotUnsupported = errors.New("sql/migrate: driver does not support taking a database snapshot") // ErrCleanCheckerUnsupported is returned if there is no CleanChecker given. ErrCleanCheckerUnsupported = errors.New("sql/migrate: driver does not support checking if database is clean") // ErrRevisionNotExist is returned if the requested revision is not found in the storage. ErrRevisionNotExist = errors.New("sql/migrate: revision not found") )
var ( // DefaultFormatter is a default implementation for Formatter. DefaultFormatter = TemplateFormatter{ { N: template.Must(template.New("").Funcs(templateFuncs).Parse( "{{ with .Version }}{{ . }}{{ else }}{{ now }}{{ end }}{{ with .Name }}_{{ . }}{{ end }}.sql", )), C: template.Must(template.New("").Funcs(templateFuncs).Parse( `{{ range .Changes }}{{ with .Comment }}{{ printf "-- %s%s\n" (slice . 0 1 | upper ) (slice . 1) }}{{ end }}{{ printf "%s;\n" .Cmd }}{{ end }}`, )), }, } )
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 ArchiveDir ¶ added in v0.10.0
ArchiveDir returns a tar archive of the given directory.
func ArchiveDirTo ¶ added in v0.22.0
ArchiveDirTo writes a tar archive of the given directory to the given writer.
func FileStmts ¶ added in v0.16.0
FileStmts is like FileStmtDecls but returns only the statement text without the extra info.
func FilesLastIndex ¶ added in v0.6.0
FilesLastIndex returns the index of the last file satisfying f(i), or -1 if none do.
func LogIntro ¶ added in v0.6.0
LogIntro gathers some meta information from the migration files and stored revisions to log some general information prior to actual execution.
func LogNoPendingFiles ¶ added in v0.11.0
LogNoPendingFiles starts a new LogExecution and LogDone to indicate that there are no pending files to be executed.
func NewVersion ¶ added in v0.25.0
func NewVersion() string
NewVersion generates a new migration version.
func Validate ¶ added in v0.3.7
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
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 []any // A Comment describes the change. Comment string // Reverse contains the "reversed" statement(s) if // the command is reversible. Reverse any // string | []string // The Source that caused this change, or nil. Source schema.Change }
A Change of migration.
func (*Change) ReverseStmts ¶ added in v0.9.0
ReverseStmts returns the reverse statements of a Change, if any.
type CheckpointDir ¶ added in v0.13.2
type CheckpointDir interface { Dir // WriteCheckpoint writes the given checkpoint file to the migration directory. WriteCheckpoint(name, tag string, content []byte) error // CheckpointFiles returns a set of checkpoint files stored in this Dir, // ordered by name. CheckpointFiles() ([]File, error) // FilesFromCheckpoint returns the files to be executed on a database from // the given checkpoint file, including it. An ErrCheckpointNotFound if the // checkpoint file is not found in the directory. FilesFromCheckpoint(string) ([]File, error) }
CheckpointDir wraps the functionality used to interact with a migration directory that support checkpoints.
type CheckpointFile ¶ added in v0.13.2
type CheckpointFile interface { File // IsCheckpoint returns true if the file is a checkpoint file. IsCheckpoint() bool // CheckpointTag returns the tag of the checkpoint file, if defined. The tag // can be derived from the file name, internal metadata or directive comments. // // An ErrNotCheckpoint is returned if the file is not a checkpoint file. CheckpointTag() (string, error) }
CheckpointFile wraps the functionality used to interact with files returned from a CheckpointDir.
type ChecksumError ¶ added in v0.19.1
type ChecksumError struct {
Line, Total, Pos int // line number in file of the mismatch, total number of lines, pos in file
File string // filename of the mismatch
Reason Reason // reason of a mismatch by filename
}
ChecksumError indicates a mismatch between a directories files and its sum.
func (*ChecksumError) Error ¶ added in v0.19.1
func (err *ChecksumError) Error() string
Error implements the error interface.
func (*ChecksumError) Is ¶ added in v0.19.1
func (err *ChecksumError) Is(target error) bool
Is exists for backwards compatability reasons.
type CleanChecker ¶ added in v0.6.0
type CleanChecker interface { // CheckClean checks if the connected realm or schema does not contain any resources besides the // revision history table. A NotCleanError is returned in case the connection is not-empty. CheckClean(context.Context, *TableIdent) error }
CleanChecker wraps the single CheckClean method.
type Dir ¶
type Dir interface { fs.FS // WriteFile writes the data to the named file. WriteFile(string, []byte) error // Files returns a set of files stored in this Dir to be executed on a database. Files() ([]File, error) // Checksum returns a HashFile of the migration directory. Checksum() (HashFile, error) }
Dir wraps the functionality used to interact with a migration directory.
func UnarchiveDir ¶ added in v0.10.0
UnarchiveDir extracts the tar archive into the given directory.
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 ExecOrder ¶ added in v0.16.0
type ExecOrder uint
ExecOrder defines the execution order to use.
const ( // ExecOrderLinear is the default execution order mode. // It expects a linear history and fails if it encounters files that were // added out of order. For example, a new file was added with version lower // than the last applied revision. ExecOrderLinear ExecOrder = iota // ExecOrderLinearSkip is a softer version of ExecOrderLinear. // This means that if a new file is added with a version lower than the last // applied revision, it will be skipped. ExecOrderLinearSkip // ExecOrderNonLinear executes migration files that were added out of order. ExecOrderNonLinear )
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.
func (*Executor) Execute ¶ added in v0.3.8
Execute executes the given migration file on the database. If it sees a file, that has been partially applied, it will continue with the next statement in line.
func (*Executor) ExecuteN ¶ added in v0.4.2
ExecuteN executes n pending migration files. If n<=0 all pending migration files are executed.
func (*Executor) ExecuteTo ¶ added in v0.8.0
ExecuteTo executes all pending migration files up to and including version.
func (*Executor) Pending ¶ added in v0.4.2
Pending returns all pending (not fully applied) migration files in the migration directory.
func (*Executor) Replay ¶ added in v0.6.0
func (e *Executor) Replay(ctx context.Context, r StateReader, opts ...ReplayOption) (_ *schema.Realm, err error)
Replay the migration directory and invoke the state to get back the inspection result.
type ExecutorOption ¶ added in v0.3.8
ExecutorOption allows configuring an Executor using functional arguments.
func WithAllowDirty ¶ added in v0.6.0
func WithAllowDirty(b bool) ExecutorOption
WithAllowDirty defines if we can start working on a non-clean database in the first migration execution.
func WithBaselineVersion ¶ added in v0.6.0
func WithBaselineVersion(v string) ExecutorOption
WithBaselineVersion allows setting the baseline version of the database on the first migration. Hence, all versions up to and including this version are skipped.
func WithExecOrder ¶ added in v0.16.0
func WithExecOrder(o ExecOrder) ExecutorOption
WithExecOrder sets the execution order to use.
func WithLogger ¶ added in v0.4.1
func WithLogger(log Logger) ExecutorOption
WithLogger sets the Logger of an Executor.
func WithOperatorVersion ¶ added in v0.6.4
func WithOperatorVersion(v string) ExecutorOption
WithOperatorVersion sets the operator version to save on the revisions when executing migration files.
type File ¶ added in v0.3.4
type File interface { // Name returns the name of the migration file. Name() string // Desc returns the description of the migration File. Desc() string // Version returns the version of the migration File. Version() string // Bytes returns the read content of the file. Bytes() []byte // Stmts returns the set of SQL statements this file holds. Stmts() ([]string, error) // StmtDecls returns the set of SQL statements this file holds alongside its preceding comments. StmtDecls() ([]*Stmt, error) }
File represents a single migration file.
func FilesFromLastCheckpoint ¶ added in v0.13.2
FilesFromLastCheckpoint returns a set of files created after the last checkpoint, if exists, to be executed on a database (on the first time). Note, if the Dir is not a CheckpointDir, or no checkpoint file was found, all files are returned.
func SkipCheckpointFiles ¶ added in v0.13.2
SkipCheckpointFiles returns a filtered set of files that are not checkpoint files.
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 NewHashFile ¶ added in v0.9.0
NewHashFile computes and returns a HashFile from the given directory's files.
func (HashFile) MarshalText ¶ added in v0.3.7
MarshalText implements encoding.TextMarshaler.
func (HashFile) SumByName ¶ added in v0.7.1
SumByName returns the hash for a migration file by its name.
func (*HashFile) UnmarshalText ¶ added in v0.3.7
UnmarshalText implements encoding.TextUnmarshaler.
type HistoryChangedError ¶ added in v0.6.0
HistoryChangedError is returned if between two execution attempts already applied statements of a file have changed.
func (HistoryChangedError) Error ¶ added in v0.6.0
func (e HistoryChangedError) Error() string
type HistoryNonLinearError ¶ added in v0.16.0
type HistoryNonLinearError struct { // OutOfOrder are the files that were added out of order. OutOfOrder []File // Pending are valid files that are still pending for execution. Pending []File }
HistoryNonLinearError is returned if the migration history is not linear. Means, a file was added out of order. The executor can be configured to ignore this error and continue execution. See WithExecOrder for details.
func (HistoryNonLinearError) Error ¶ added in v0.16.0
func (e HistoryNonLinearError) Error() string
type LocalDir ¶ added in v0.3.4
type LocalDir struct {
// contains filtered or unexported fields
}
LocalDir implements Dir for a local migration directory with default Atlas formatting.
func NewLocalDir ¶ added in v0.3.4
NewLocalDir returns a new the Dir used by a Planner to work on the given local path.
func (*LocalDir) CheckpointFiles ¶ added in v0.13.2
CheckpointFiles implements CheckpointDir.CheckpointFiles.
func (*LocalDir) Checksum ¶ added in v0.6.2
Checksum implements Dir.Checksum. By default, it calls Files() and creates a checksum from them.
func (*LocalDir) Files ¶ added in v0.3.8
Files implements Dir.Files. It looks for all files with .sql suffix and orders them by filename.
func (*LocalDir) FilesFromCheckpoint ¶ added in v0.13.2
FilesFromCheckpoint implements CheckpointDir.FilesFromCheckpoint.
func (*LocalDir) WriteCheckpoint ¶ added in v0.13.2
WriteCheckpoint is like WriteFile, but marks the file as a checkpoint file.
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 NewLocalFile ¶ added in v0.4.3
NewLocalFile returns a new local file.
func (*LocalFile) AddDirective ¶ added in v0.13.2
AddDirective adds a new directive to the file.
func (*LocalFile) CheckpointTag ¶ added in v0.13.2
CheckpointTag returns the tag of the checkpoint file, if defined.
func (*LocalFile) Directive ¶ added in v0.9.1
Directive returns the (global) file directives that match the provided name. File directives are located at the top of the file and should not be associated with any statement. Hence, double new lines are used to separate file directives from its content.
func (*LocalFile) IsCheckpoint ¶ added in v0.13.2
IsCheckpoint reports whether the file is a checkpoint file.
func (*LocalFile) StmtDecls ¶ added in v0.6.4
StmtDecls returns the all statement declarations exist in the local file.
type LogChecks ¶ added in v0.19.0
LogChecks is sent before the execution of a group of check statements.
type LogChecksDone ¶ added in v0.19.0
type LogChecksDone struct {
Error error // Optional error.
}
LogChecksDone is sent after the execution of a group of checks together with some text message and error if the group failed.
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 []File }
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 { // The File being executed. File File // Version executed. // Deprecated: Use File.Version() instead. Version string // Desc of migration executed. // Deprecated: Use File.Desc() instead. Desc string // Skip holds the number of stmts of this file that will be skipped. // This happens, if a migration file was only applied partially and will now continue to be applied. Skip int }
LogFile is sent if a new migration file is executed.
type LogStmt ¶ added in v0.4.1
type LogStmt struct { SQL string // SQL statement. Stmt *Stmt // Scanned statement with extra information. }
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 MemDir ¶ added in v0.9.0
type MemDir struct {
// contains filtered or unexported fields
}
MemDir provides an in-memory Dir implementation.
func OpenMemDir ¶ added in v0.9.1
OpenMemDir opens an in-memory directory and registers it in the process namespace with the given name. Hence, calling OpenMemDir with the same name will return the same directory. The directory is deleted when the last reference of it is closed.
func (*MemDir) CheckpointFiles ¶ added in v0.13.2
CheckpointFiles implements CheckpointDir.CheckpointFiles.
func (*MemDir) CopyFiles ¶ added in v0.26.0
CopyFiles copies all files to the MemDir and update the atlas.sum file, or create it if it does not exist.
func (*MemDir) Files ¶ added in v0.9.0
Files returns a set of files stored in-memory to be executed on a database.
func (*MemDir) FilesFromCheckpoint ¶ added in v0.13.2
FilesFromCheckpoint implements CheckpointDir.FilesFromCheckpoint.
func (*MemDir) Reset ¶ added in v0.12.1
func (d *MemDir) Reset()
Reset the in-memory directory to its initial state.
func (*MemDir) SyncWrites ¶ added in v0.12.1
SyncWrites allows syncing writes from in-memory directory the underlying storage.
func (*MemDir) WriteCheckpoint ¶ added in v0.13.2
WriteCheckpoint is like WriteFile, but marks the file as a checkpoint file.
type MissingMigrationError ¶ added in v0.7.1
type MissingMigrationError struct{ Version, Description string }
MissingMigrationError is returned if a revision is partially applied but the matching migration file is not found in the migration directory.
func (MissingMigrationError) Error ¶ added in v0.7.1
func (e MissingMigrationError) Error() string
Error implements error.
type NopLogger ¶ added in v0.6.0
type NopLogger struct{}
NopLogger is a Logger that does nothing. It is useful for one-time replay of the migration directory.
type NopRevisionReadWriter ¶ added in v0.4.2
type NopRevisionReadWriter struct{}
NopRevisionReadWriter is a RevisionReadWriter that does nothing. It is useful for one-time replay of the migration directory.
func (NopRevisionReadWriter) DeleteRevision ¶ added in v0.7.1
func (NopRevisionReadWriter) DeleteRevision(context.Context, string) error
DeleteRevision implements RevisionsReadWriter.DeleteRevision.
func (NopRevisionReadWriter) Ident ¶ added in v0.6.0
func (NopRevisionReadWriter) Ident() *TableIdent
Ident implements RevisionsReadWriter.TableIdent.
func (NopRevisionReadWriter) ReadRevision ¶ added in v0.6.0
ReadRevision implements RevisionsReadWriter.ReadRevision.
func (NopRevisionReadWriter) ReadRevisions ¶ added in v0.4.2
func (NopRevisionReadWriter) ReadRevisions(context.Context) ([]*Revision, 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 NotCleanError ¶ added in v0.5.0
type NotCleanError struct { Reason string // reason why the database is considered not clean State *schema.Realm // the state the dev-connection is in }
NotCleanError 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-db.
func (*NotCleanError) Error ¶ added in v0.5.0
func (e *NotCleanError) Error() string
type Plan ¶
type Plan struct {
// Version and Name of the plan. Provided by the user or auto-generated.
Version, 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, ...PlanOption) (*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, ...PlanOption) error }
PlanApplier wraps the methods for planning and applying changes on the database.
type PlanMode ¶ added in v0.12.1
type PlanMode uint8
PlanMode defines the plan mode to use.
const ( PlanModeUnset PlanMode = iota // Driver default. PlanModeInPlace // Changes are applied in place (e.g. 'schema diff'). PlanModeDeferred // Changes are planned for future applying (e.g. 'migrate diff'). PlanModeDump // Schema creation dump (e.g. 'schema inspect'). PlanModeUnsortedDump // Schema creation demo without sorting dependencies. )
List of migration planning modes.
type PlanOption ¶ added in v0.6.0
type PlanOption func(*PlanOptions)
PlanOption allows configuring a drivers' plan using functional arguments.
type PlanOptions ¶ added in v0.6.0
type PlanOptions struct { // PlanWithSchemaQualifier allows setting a custom schema to prefix // tables and other resources. An empty string indicates no qualifier. SchemaQualifier *string // Indent is the string to use for indentation. // If empty, no indentation is used. Indent string // Mode represents the migration planning mode to be used. If not specified, the driver picks its default. // This is useful to indicate to the driver whether the context is a live database, an empty one, or the // versioned migration workflow. Mode PlanMode }
PlanOptions holds the migration plan options to be used by PlanApplier.
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 Dir to 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) Checkpoint ¶ added in v0.13.2
Checkpoint calculate the current state of the migration directory by executing its files, and return a migration (checkpoint) Plan that represents its states.
func (*Planner) CheckpointSchema ¶ added in v0.13.2
CheckpointSchema is like Checkpoint but limits its scope to the schema connection. Note, the operation fails in case the connection was not set to a schema.
func (*Planner) Plan ¶ added in v0.3.4
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) PlanSchema ¶ added in v0.6.0
PlanSchema is like Plan but limits its scope to the schema connection. Note, the operation fails in case the connection was not set to a schema.
func (*Planner) WriteCheckpoint ¶ added in v0.13.2
WriteCheckpoint writes the given Plan as a checkpoint file 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 PlanFormat ¶ added in v0.6.0
func PlanFormat(fmt Formatter) PlannerOption
PlanFormat sets the Formatter of a Planner.
func PlanWithChecksum ¶ added in v0.6.0
func PlanWithChecksum(b bool) PlannerOption
PlanWithChecksum allows setting if the hash-sum functionality for the migration directory is enabled or not.
func PlanWithDiffOptions ¶ added in v0.11.0
func PlanWithDiffOptions(opts ...schema.DiffOption) PlannerOption
PlanWithDiffOptions allows setting custom diff options.
func PlanWithIndent ¶ added in v0.10.0
func PlanWithIndent(indent string) PlannerOption
PlanWithIndent allows generating SQL statements with indentation. An empty string indicates no indentation.
func PlanWithMode ¶ added in v0.12.1
func PlanWithMode(m PlanMode) PlannerOption
PlanWithMode allows setting a custom plan mode.
func PlanWithSchemaQualifier ¶ added in v0.6.0
func PlanWithSchemaQualifier(q string) PlannerOption
PlanWithSchemaQualifier allows setting a custom schema to prefix tables and other resources. An empty string indicates no prefix.
Note, this options require the changes to be scoped to one schema and returns an error otherwise.
type ReplayOption ¶ added in v0.8.0
type ReplayOption func(*replayConfig)
ReplayOption configures a migration directory replay behavior.
func ReplayToVersion ¶ added in v0.8.0
func ReplayToVersion(v string) ReplayOption
ReplayToVersion configures the last version to apply when replaying the migration directory.
type RestoreFunc ¶ added in v0.5.0
RestoreFunc is returned by the Snapshoter to explicitly restore the database state.
type Revision ¶ added in v0.3.8
type Revision struct { Version string `json:"Version"` // Version of the migration. Description string `json:"Description"` // Description of this migration. Type RevisionType `json:"Type"` // Type of the migration. Applied int `json:"Applied"` // Applied amount of statements in the migration. Total int `json:"Total"` // Total amount of statements in the migration. ExecutedAt time.Time `json:"ExecutedAt"` // ExecutedAt is the starting point of execution. ExecutionTime time.Duration `json:"ExecutionTime"` // ExecutionTime of the migration. Error string `json:"Error,omitempty"` // Error of the migration, if any occurred. ErrorStmt string `json:"ErrorStmt,omitempty"` // ErrorStmt is the statement that raised Error. Hash string `json:"-"` // Hash of migration file. PartialHashes []string `json:"-"` // PartialHashes is the hashes of applied statements. OperatorVersion string `json:"OperatorVersion"` // OperatorVersion that executed this migration. }
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 { // Ident returns an object identifies this history table. Ident() *TableIdent // ReadRevisions returns all revisions. ReadRevisions(context.Context) ([]*Revision, error) // ReadRevision returns a revision by version. // Returns ErrRevisionNotExist if the version does not exist. ReadRevision(context.Context, string) (*Revision, error) // WriteRevision saves the revision to the storage. WriteRevision(context.Context, *Revision) error // DeleteRevision deletes a revision by version from the storage. DeleteRevision(context.Context, string) error }
A RevisionReadWriter wraps the functionality for reading and writing migration revisions in a database table.
type RevisionType ¶ added in v0.6.0
type RevisionType uint
RevisionType defines the type of the revision record in the history table.
const ( // RevisionTypeUnknown represents an unknown revision type. // This type is unexpected and exists here to only ensure // the type is not set to the zero value. RevisionTypeUnknown RevisionType = 0 // RevisionTypeBaseline represents a baseline revision. Note that only // the first record can represent a baseline migration and most of its // fields are set to the zero value. RevisionTypeBaseline RevisionType = 1 << (iota - 1) // RevisionTypeExecute represents a migration that was executed. RevisionTypeExecute // RevisionTypeResolved represents a migration that was resolved. A migration // script that was script executed and then resolved should set its Type to // RevisionTypeExecute | RevisionTypeResolved. RevisionTypeResolved )
func (RevisionType) Has ¶ added in v0.8.0
func (r RevisionType) Has(f RevisionType) bool
Has returns if the given flag is set.
func (RevisionType) MarshalText ¶ added in v0.8.0
func (r RevisionType) MarshalText() ([]byte, error)
MarshalText implements encoding.TextMarshaler.
func (RevisionType) String ¶ added in v0.8.0
func (r RevisionType) String() string
String implements fmt.Stringer.
type Scanner ¶ added in v0.3.8
type Scanner struct { ScannerOptions // contains filtered or unexported fields }
Scanner scanning SQL statements from migration and schema files.
type ScannerOptions ¶ added in v0.16.0
type ScannerOptions struct { // MatchBegin enables matching for BEGIN ... END statements block. MatchBegin bool // MatchBeginAtomic enables matching for BEGIN ATOMIC ... END statements block. MatchBeginAtomic bool // MatchDollarQuote enables the PostgreSQL dollar-quoted string syntax. MatchDollarQuote bool // BackslashEscapes enables backslash-escaped strings. By default, only MySQL/MariaDB uses backslash as // an escape character. https://dev.mysql.com/doc/refman/8.4/en/sql-mode.html#sqlmode_no_backslash_escapes BackslashEscapes bool // EscapedStringExt enables the supported for PG extension for escaped strings and adopted by its flavors. // See: https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-STRINGS-ESCAPE. EscapedStringExt bool }
ScannerOptions controls the behavior of the scanner.
type Snapshoter ¶ added in v0.5.0
type Snapshoter interface { // Snapshot takes a snapshot of the current database state and returns a function that can be called to restore // that state. Snapshot should return an error, if the current state can not be restored completely, e.g. if // there is a table already containing some rows. Snapshot(context.Context) (RestoreFunc, error) }
Snapshoter wraps the Snapshot method.
type StateReader ¶
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).
func Realm ¶
func Realm(r *schema.Realm) StateReader
Realm returns a StateReader for the static Realm object.
func RealmConn ¶ added in v0.6.0
func RealmConn(drv Driver, opts *schema.InspectRealmOption) StateReader
RealmConn returns a StateReader for a Driver connected to a database.
func Schema ¶
func Schema(s *schema.Schema) StateReader
Schema returns a StateReader for the static Schema object.
func SchemaConn ¶ added in v0.6.0
func SchemaConn(drv Driver, name string, opts *schema.InspectOptions) StateReader
SchemaConn returns a StateReader for a Driver connected to a schema.
type StateReaderFunc ¶
The StateReaderFunc type is an adapter to allow the use of ordinary functions as state readers.
type Stmt ¶ added in v0.6.4
type Stmt struct { Pos int // statement position Text string // statement text Comments []string // associated comments }
Stmt represents a scanned statement text along with its position in the file and associated comments group.
func FileStmtDecls ¶ added in v0.16.0
FileStmtDecls scans atlas-format file statements using the Driver implementation, if implemented.
type StmtScanner ¶ added in v0.16.0
StmtScanner interface for scanning SQL statements from migration and schema files and can be optionally implemented by drivers.
type TableIdent ¶ added in v0.6.0
TableIdent describes a table identifier returned by the revisions table.
type TemplateFormatter ¶ added in v0.3.4
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.
func (TemplateFormatter) FormatFile ¶ added in v0.26.0
func (t TemplateFormatter) FormatFile(p *Plan) (File, error)
FormatFile is like Format, but expects and returns a single file.