Help us shape the future of Go! Take the 2026 Go Developer Survey

source

package
v4.20.2 Latest Latest
Warning

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

Go to latest
Published: Dec 24, 2025 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package source provides the Source interface. All source drivers must implement this interface, register themselves, optionally provide a `WithInstance` function and pass the tests in package source/testing.

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	DefaultParse = Parse
	DefaultRegex = Regex
)
View Source
var (
	ErrParse = fmt.Errorf("no match")
)
View Source
var Regex = regexp.MustCompile(`^([0-9]+)_(.*)\.(` + string(Down) + `|` + string(Up) + `)\.(.*)$`)

Regex matches the following pattern:

123_name.up.ext
123_name.down.ext

Functions

func List

func List() []string

List lists the registered drivers

func Register

func Register(name string, driver Driver)

Register globally registers a driver.

Types

type Direction

type Direction string

Direction is either up or down.

const (
	Down Direction = "down"
	Up   Direction = "up"
)

type Driver

type Driver interface {
	// Open returns a new driver instance configured with parameters
	// coming from the URL string. Migrate will call this function
	// only once per instance.
	Open(url string) (Driver, error)

	// Close closes the underlying source instance managed by the driver.
	// Migrate will call this function only once per instance.
	Close() error

	// First returns the very first migration version available to the driver.
	// Migrate will call this function multiple times.
	// If there is no version available, it must return os.ErrNotExist.
	First() (version uint, err error)

	// Prev returns the previous version for a given version available to the driver.
	// Migrate will call this function multiple times.
	// If there is no previous version available, it must return os.ErrNotExist.
	Prev(version uint) (prevVersion uint, err error)

	// Next returns the next version for a given version available to the driver.
	// Migrate will call this function multiple times.
	// If there is no next version available, it must return os.ErrNotExist.
	Next(version uint) (nextVersion uint, err error)

	// ReadUp returns the UP migration body and an identifier that helps
	// finding this migration in the source for a given version.
	// If there is no up migration available for this version,
	// it must return os.ErrNotExist.
	// Do not start reading, just return the ReadCloser!
	ReadUp(version uint) (r io.ReadCloser, identifier string, err error)

	// ReadDown returns the DOWN migration body and an identifier that helps
	// finding this migration in the source for a given version.
	// If there is no down migration available for this version,
	// it must return os.ErrNotExist.
	// Do not start reading, just return the ReadCloser!
	ReadDown(version uint) (r io.ReadCloser, identifier string, err error)
}

Driver is the interface every source driver must implement.

How to implement a source driver?

  1. Implement this interface.
  2. Optionally, add a function named `WithInstance`. This function should accept an existing source instance and a Config{} struct and return a driver instance.
  3. Add a test that calls source/testing.go:Test()
  4. Add own tests for Open(), WithInstance() (when provided) and Close(). All other functions are tested by tests in source/testing. Saves you some time and makes sure all source drivers behave the same way.
  5. Call Register in init().

Guidelines:

  • All configuration input must come from the URL string in func Open() or the Config{} struct in WithInstance. Don't os.Getenv().
  • Drivers are supposed to be read only.
  • Ideally don't load any contents (into memory) in Open or WithInstance.
Example
// see source/stub for an example

// source/stub/stub.go has the driver implementation
// source/stub/stub_test.go runs source/testing/test.go:Test

func Open

func Open(url string) (Driver, error)

Open returns a new driver instance.

type ErrDuplicateMigration

type ErrDuplicateMigration struct {
	Migration
	os.FileInfo
}

ErrDuplicateMigration is an error type for reporting duplicate migration files.

func (ErrDuplicateMigration) Error

func (e ErrDuplicateMigration) Error() string

Error implements error interface.

type Migration

type Migration struct {
	// Version is the version of this migration.
	Version uint

	// Identifier can be any string that helps identifying
	// this migration in the source.
	Identifier string

	// Direction is either Up or Down.
	Direction Direction

	// Raw holds the raw location path to this migration in source.
	// ReadUp and ReadDown will use this.
	Raw string
}

Migration is a helper struct for source drivers that need to build the full directory tree in memory. Migration is fully independent from migrate.Migration.

func Parse

func Parse(raw string) (*Migration, error)

Parse returns Migration for matching Regex pattern.

type Migrations

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

Migrations wraps Migration and has an internal index to keep track of Migration order.

func NewMigrations

func NewMigrations() *Migrations

func (*Migrations) Append

func (i *Migrations) Append(m *Migration) (ok bool)

func (*Migrations) Down

func (i *Migrations) Down(version uint) (m *Migration, ok bool)

func (*Migrations) First

func (i *Migrations) First() (version uint, ok bool)

func (*Migrations) Next

func (i *Migrations) Next(version uint) (nextVersion uint, ok bool)

func (*Migrations) Prev

func (i *Migrations) Prev(version uint) (prevVersion uint, ok bool)

func (*Migrations) Up

func (i *Migrations) Up(version uint) (m *Migration, ok bool)

Directories

Path Synopsis
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.
Package iofs provides the Go 1.16+ io/fs#FS driver.
Package iofs provides the Go 1.16+ io/fs#FS driver.
Package testing has the source tests.
Package testing has the source tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL