Documentation ¶
Overview ¶
Package migrate reads migrations from sources and runs them against files. Sources are defined by the `source.Driver` and files by the `file.Driver` interface. The driver interfaces are kept "dumb", all migration logic is kept in this package.
Index ¶
- Variables
- func FilterCustomQuery(u *nurl.URL) *nurl.URL
- type ErrDirty
- type ErrShortLimit
- type Logger
- type Migrate
- func New(sourceURL, fileURL string) (*Migrate, error)
- func NewWithFileInstance(sourceURL string, fileName string, fileInstance file.Driver) (*Migrate, error)
- func NewWithInstance(sourceName string, sourceInstance source.Driver, fileName string, ...) (*Migrate, error)
- func NewWithSourceInstance(sourceName string, sourceInstance source.Driver, fileURL string) (*Migrate, error)
- func (m *Migrate) Close() (source error, file error)
- func (m *Migrate) Down() error
- func (m *Migrate) Drop() error
- func (m *Migrate) Force(version int) error
- func (m *Migrate) Migrate(version uint) error
- func (m *Migrate) Run(migration ...*Migration) error
- func (m *Migrate) Steps(n int) error
- func (m *Migrate) Up() error
- func (m *Migrate) Version() (version uint, dirty bool, err error)
- type Migration
- type MultiErrordeprecated
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrNoChange = errors.New("no change") ErrNilVersion = errors.New("no migration") ErrInvalidVersion = errors.New("version must be >= -1") ErrLocked = errors.New("file locked") ErrLockTimeout = errors.New("timeout: can't acquire file lock") )
var DefaultBufferSize = uint(100000)
DefaultBufferSize sets the in memory buffer size (in Bytes) for every pre-read migration (see DefaultPrefetchMigrations).
var DefaultLockTimeout = 15 * time.Second
DefaultLockTimeout sets the max time a file driver has to acquire a lock.
var DefaultPrefetchMigrations = uint(10)
DefaultPrefetchMigrations sets the number of migrations to pre-read from the source. This is helpful if the source is remote, but has little effect for a local source (i.e. file system). Please note that this setting has a major impact on the memory usage, since each pre-read migration is buffered in memory. See DefaultBufferSize.
Functions ¶
Types ¶
type ErrShortLimit ¶
type ErrShortLimit struct {
Short uint
}
ErrShortLimit is an error returned when not enough migrations can be returned by a source for a given limit.
func (ErrShortLimit) Error ¶
func (e ErrShortLimit) Error() string
Error implements the error interface.
type Logger ¶
type Logger interface { // Printf is like fmt.Printf Printf(format string, v ...interface{}) // Verbose should return true when verbose logging output is wanted Verbose() bool }
Logger is an interface so you can pass in your own logging implementation.
type Migrate ¶
type Migrate struct { // Log accepts a Logger interface Log Logger // GracefulStop accepts `true` and will stop executing migrations // as soon as possible at a safe break point, so that the file // is not corrupted. GracefulStop chan bool // PrefetchMigrations defaults to DefaultPrefetchMigrations, // but can be set per Migrate instance. PrefetchMigrations uint // LockTimeout defaults to DefaultLockTimeout, // but can be set per Migrate instance. LockTimeout time.Duration // contains filtered or unexported fields }
func New ¶
New returns a new Migrate instance from a source URL and a file URL. The URL scheme is defined by each driver.
Example ¶
// Read migrations from /home/c2pc/migrations and connect to a local config.yml file. m, err := New("file:///home/c2pc/migrations", "file://./config.yml") if err != nil { log.Fatal(err) } // Migrate all the way up ... if err := m.Up(); err != nil && err != ErrNoChange { log.Fatal(err) }
Output:
func NewWithFileInstance ¶
func NewWithFileInstance(sourceURL string, fileName string, fileInstance file.Driver) (*Migrate, error)
NewWithFileInstance returns a new Migrate instance from a source URL and an existing file instance. The source URL scheme is defined by each driver. Use any string that can serve as an identifier during logging as fileName. You are responsible for closing the underlying file client if necessary.
Example ¶
// Create and use an existing file instance. f, err := os.Open("./config.yml") if err != nil { log.Fatal(err) } defer func() { if err := f.Close(); err != nil { log.Fatal(err) } }() // Create driver instance from file. // Check each driver if it supports the WithInstance function. // `import "github.com/c2pc/migrate/file/yaml"` instance, err := dStub.WithInstance(f, &dStub.Config{}) if err != nil { log.Fatal(err) } // Read migrations from /home/c2pc/migrations and connect to a local config.yml file. m, err := NewWithFileInstance("file:///home/c2pc/migrations", "yaml", instance) if err != nil { log.Fatal(err) } // Migrate all the way up ... if err := m.Up(); err != nil { log.Fatal(err) }
Output:
func NewWithInstance ¶
func NewWithInstance(sourceName string, sourceInstance source.Driver, fileName string, fileInstance file.Driver) (*Migrate, error)
NewWithInstance returns a new Migrate instance from an existing source and file instance. Use any string that can serve as an identifier during logging as sourceName and fileName. You are responsible for closing down the underlying source and file client if necessary.
Example ¶
// See NewWithFileInstance and NewWithSourceInstance for an example.
Output:
func NewWithSourceInstance ¶
func NewWithSourceInstance(sourceName string, sourceInstance source.Driver, fileURL string) (*Migrate, error)
NewWithSourceInstance returns a new Migrate instance from an existing source instance and a file URL. The file URL scheme is defined by each driver. Use any string that can serve as an identifier during logging as sourceName. You are responsible for closing the underlying source client if necessary.
Example ¶
di := &DummyInstance{"think any client required for a source here"} // Create driver instance from DummyInstance di. // Check each driver if it support the WithInstance function. // `import "github.com/c2pc/migrate/source/stub"` instance, err := sStub.WithInstance(di, &sStub.Config{}) if err != nil { log.Fatal(err) } // Read migrations from Stub and connect to a local config.yml file. m, err := NewWithSourceInstance(srcDrvNameStub, instance, "yaml://./config.yml") if err != nil { log.Fatal(err) } // Migrate all the way up ... if err := m.Up(); err != nil { log.Fatal(err) }
Output:
func (*Migrate) Down ¶
Down looks at the currently active migration version and will migrate all the way down (applying all down migrations).
func (*Migrate) Force ¶
Force sets a migration version. It does not check any currently active version in file. It resets the dirty state to false.
func (*Migrate) Migrate ¶
Migrate looks at the currently active migration version, then migrates either up or down to the specified version.
func (*Migrate) Run ¶
Run runs any migration provided by you against the file. It does not check any currently active version in file. Usually you don't need this function at all. Use Migrate, Steps, Up or Down instead.
func (*Migrate) Steps ¶
Steps looks at the currently active migration version. It will migrate up if n > 0, and down if n < 0.
type Migration ¶
type Migration struct { // Identifier can be any string to help identifying // the migration in the source. Identifier string // Version is the version of this migration. Version uint // TargetVersion is the migration version after this migration // has been applied to the file. // Can be -1, implying that this is a NilVersion. TargetVersion int // Body holds an io.ReadCloser to the source. Body io.ReadCloser // BufferedBody holds an buffered io.Reader to the underlying Body. BufferedBody io.Reader // BufferSize defaults to DefaultBufferSize BufferSize uint // Scheduled is the time when the migration was scheduled/ queued. Scheduled time.Time // StartedBuffering is the time when buffering of the migration source started. StartedBuffering time.Time // FinishedBuffering is the time when buffering of the migration source finished. FinishedBuffering time.Time // FinishedReading is the time when the migration source is fully read. FinishedReading time.Time // BytesRead holds the number of Bytes read from the migration source. BytesRead int64 // contains filtered or unexported fields }
Migration holds information about a migration. It is initially created from data coming from the source and then used when run against the file.
func NewMigration ¶
func NewMigration(body io.ReadCloser, identifier string, version uint, targetVersion int) (*Migration, error)
NewMigration returns a new Migration and sets the body, identifier, version and targetVersion. Body can be nil, which turns this migration into a "NilMigration". If no identifier is provided, it will default to "<empty>". targetVersion can be -1, implying it is a NilVersion.
What is a NilMigration? Usually each migration version coming from source is expected to have an Up and Down migration. This is not a hard requirement though, leading to a situation where only the Up or Down migration is present. So let's say the user wants to migrate up to a version that doesn't have the actual Up migration, in that case we still want to apply the version, but with an empty body. We are calling that a NilMigration, a migration with an empty body.
What is a NilVersion? NilVersion is a const(-1). When running down migrations and we are at the last down migration, there is no next down migration, the targetVersion should be nil. Nil in this case is represented by -1 (because type int).
Example ¶
// Create a dummy migration body, this is coming from the source usually. body := io.NopCloser(strings.NewReader("dumy migration that creates config file")) // Create a new Migration that represents version 1486686016. // Once this migration has been applied to the file, the new // migration version will be 1486689359. migr, err := NewMigration(body, "config", 1486686016, 1486689359) if err != nil { log.Fatal(err) } fmt.Print(migr.LogString())
Output: 1486686016/u config
Example (NilMigration) ¶
// Create a new Migration that represents a NilMigration. // Once this migration has been applied to the file, the new // migration version will be 1486689359. migr, err := NewMigration(nil, "", 1486686016, 1486689359) if err != nil { log.Fatal(err) } fmt.Print(migr.LogString())
Output: 1486686016/u <empty>
Example (NilVersion) ¶
// Create a dummy migration body, this is coming from the source usually. body := io.NopCloser(strings.NewReader("dumy migration that deletes config file")) // Create a new Migration that represents version 1486686016. // This is the last available down migration, so the migration version // will be -1, meaning NilVersion once this migration ran. migr, err := NewMigration(body, "drop_config", 1486686016, -1) if err != nil { log.Fatal(err) } fmt.Print(migr.LogString())
Output: 1486686016/d drop_config
func (*Migration) Buffer ¶
Buffer buffers Body up to BufferSize. Calling this function blocks. Call with goroutine.
type MultiError
deprecated
type MultiError struct {
Errs []error
}
MultiError holds multiple errors.
Deprecated: Use github.com/hashicorp/go-multierror instead
func NewMultiError
deprecated
func NewMultiError(errs ...error) MultiError
NewMultiError returns an error type holding multiple errors.
Deprecated: Use github.com/hashicorp/go-multierror instead
func (MultiError) Error ¶
func (m MultiError) Error() string
Error implements error. Multiple errors are concatenated with 'and's.
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
Package file provides the Driver interface.
|
Package file provides the Driver interface. |
testing
Package testing has the file tests.
|
Package testing has the file tests. |
internal
|
|
Package source provides the Source interface.
|
Package source provides the Source interface. |
godoc_vfs
Package godoc_vfs contains a driver that reads migrations from a virtual file system.
|
Package godoc_vfs contains a driver that reads migrations from a virtual file system. |
iofs
Package iofs provides the Go 1.16+ io/fs#FS driver.
|
Package iofs provides the Go 1.16+ io/fs#FS driver. |
testing
Package testing has the source tests.
|
Package testing has the source tests. |
Package testing is used in driver tests and should only be used by migrate tests.
|
Package testing is used in driver tests and should only be used by migrate tests. |