goose

package module
v4.0.0-...-3d10b39 Latest Latest
Warning

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

 Go to latest Published: Jul 5, 2023 License: MIT Imports: 22 Imported by: 0

README

goose Goose CI Go Reference

Goose is a database migration tool. Manage your database schema by creating incremental SQL changes or Go functions.

WORK IN PROGRESS ..

Credit

The gopher mascot was designed by Renée French / CC 3.0. For more info check out the Go Blog. Adapted by Ellen.

License

Licensed under MIT License

Documentation

Overview

Package goose contains the primitives for managing database migrations.

For more information about the goose package or cli see 

https://pressly.github.io/goose

and other reference material and blog posts on that site.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrVersionNotFound when a migration version is not found.
	ErrVersionNotFound = errors.New("version not found")

	// ErrNoMigration when there are no migrations to apply. It is returned by (*Provider).Down and
	// (*Provider).UpByOne.
	ErrNoMigration = errors.New("no migration to apply")

	// ErrAlreadyApplied when a migration has already been applied.
	ErrAlreadyApplied = errors.New("already applied")
)

Functions

func AddMigration 

func AddMigration(up, down GoMigration)

AddMigration adds a Go migration.

This function is intended to be called from a versioned Go migration file, and will panic at build time if a duplicate version is detected.

Example: 

func init() {
    goose.AddMigration(Up00002, Down00002)
}

func AddMigrationNoTx 

func AddMigrationNoTx(up, down GoMigrationNoTx)

AddMigrationNoTx adds a Go migration that will be run outside a transaction.

This function is intended to be called from a versioned Go migration file, and will panic at build time if a duplicate version is detected.

Example: 

func init() {
    goose.AddMigrationNoTx(Up00002, Down00002)
}

func Create 

func Create(
	dir string,
	sourceType SourceType,
	name string,
	opt *CreateOptions,
) (string, error)

Create creates a new migration file in the specified directory. If the directory does not exist, it will be created. This command always reads from and writes to the filesystem. The returned filename is the full path to the newly created migration file.

By default, the filename numeric component will be a timestamp in the format of YYYYMMDDHHMMSS. But if sequential is set to true, it will be the next available sequential number. Example: 00001_create_users_table.go.

The provided CreateOptions is optional and may be nil if defaults should be used.

func NumericComponent 

func NumericComponent(filename string) (int64, error)

NumericComponent parses the version from the migration file name.

XXX_descriptivename.ext where XXX specifies the version number and ext specifies the type of migration, either .sql or .go.

Types

type CreateOptions 

type CreateOptions struct {
	Sequential bool
	NoTx       bool
	Template   *template.Template
	// contains filtered or unexported fields
}

type Dialect 

type Dialect string

Dialect is the type of database dialect. 

const (
	DialectPostgres   Dialect = "postgres"
	DialectMySQL      Dialect = "mysql"
	DialectSQLite3    Dialect = "sqlite3"
	DialectMSSQL      Dialect = "mssql"
	DialectRedshift   Dialect = "redshift"
	DialectTiDB       Dialect = "tidb"
	DialectClickHouse Dialect = "clickhouse"
	DialectVertica    Dialect = "vertica"
)

func ParseDialect 

func ParseDialect(s string) (Dialect, error)

type FixResult 

type FixResult struct {
	OldPath string
	NewPath string
}

func Fix 

func Fix(dir string) ([]FixResult, error)

type GoMigration 

type GoMigration func(ctx context.Context, tx *sql.Tx) error

GoMigration is a Go migration func that is run within a transaction.

type GoMigrationNoTx 

type GoMigrationNoTx func(ctx context.Context, db *sql.DB) error

GoMigrationNoTx is a Go migration func that is run outside a transaction.

type LockMode 

type LockMode int
const (
	LockModeNone LockMode = iota
	LockModeAdvisorySession
)

func (LockMode) String 

func (l LockMode) String() string

type MigrationResult 

type MigrationResult struct {
	// Full path to the migration file.
	Fullpath string
	// Version is the parsed version from the migration file name.
	Version int64
	// Duration is the time it took to run the migration.
	Duration time.Duration
	// Direction is the direction the migration was applied (up or down).
	Direction string
	// Empty is true if the file was valid, but no statements to apply in the given direction. These
	// are still tracked as applied migrations, but typically have no effect on the database.
	//
	// For SQL migrations, this means the file contained no statements. For Go migrations, this
	// means the file contained nil up or down functions.
	Empty bool

	// Error is any error that occurred while running the migration.
	Error error
}

MigrationResult is the result of a migration operation.

Note, the caller is responsible for checking the Error field for any errors that occurred while running the migration. If the Error field is not nil, the migration failed.

type MigrationStatus 

type MigrationStatus struct {
	Applied   bool
	AppliedAt time.Time
	Source    *Source
}

type Options 

type Options struct {
	// Required options.
	Dir        string
	TableName  string
	Filesystem fs.FS

	// Commonly modified options.
	Verbose  bool
	LockMode LockMode

	// Features.
	AllowMissing bool
	NoVersioning bool

	// Development.
	Debug            bool
	ExcludeFilenames []string
	// contains filtered or unexported fields
}

Options is a set of options to use when creating a new Provider.

Options can be created with DefaultOptions and then modified with SetX methods. For example: 

options := goose.DefaultOptions().SetDir("data/schema/migrations").SetVerbose(true)
goose.NewProvider(goose.DialectPostgres, db, options)

Each option X is documented on the SetX method.

func DefaultOptions 

func DefaultOptions() Options

func (Options) SetAllowMissing 

func (o Options) SetAllowMissing(b bool) Options

SetAllowMissing returns a new Options value with AllowMissing set to the given value. AllowMissing enables the ability to apply missing (out-of-order) migrations.

Example: migrations 1,6 are applied and then version 2,3,5 are introduced. If this option is true, then goose will apply 2,3,5 instead of raising an error. The final order of applied migrations will be: 1,6,2,3,5.

Default: false

func (Options) SetDebug 

func (o Options) SetDebug(b bool) Options

SetDebug returns a new Options value with Debug set to the given value. Debug enables additional debugging information and is not intended to be used by end users. This is useful for debugging goose itself. For debugging migrations, use SetVerbose.

Default: false

func (Options) SetDir 

func (o Options) SetDir(s string) Options

SetDir returns a new Options value with Dir set to the given value. Dir is the directory containing the migrations.

Default: ./migrations

func (Options) SetExcludeFilenames 

func (o Options) SetExcludeFilenames(filenames ...string) Options

SetExcludeFilenames returns a new Options value with ExcludeFilenames set to the given value. ExcludeFilenames is a list of filenames to exclude when reading (and parsing) migrations from the filesystem. This is useful for skipping migrations in tests or development.

The filename is the basename of the migration file. For example, if the migration path is ./migrations/to/apply/00001_foo.sql, then the filename to exclude should be 00001_foo.sql.

Default: include all migrations.

func (Options) SetFilesystem 

func (o Options) SetFilesystem(f fs.FS) Options

SetFilesystem returns a new Options value with Filesystem set to the given value. Filesystem is the filesystem to use for reading migrations.

Default: read from disk.

func (Options) SetLockMode 

func (o Options) SetLockMode(m LockMode) Options

SetLockMode returns a new Options value with LockMode set to the given value. LockMode is the locking mode to use when applying migrations. Locking is used to prevent multiple instances of goose from applying migrations concurrently.

IMPORTANT: Locking is currently only supported for postgres. If you'd like to see support for other databases, please file an issue.

Default: LockModeNone

func (Options) SetNoVersioning 

func (o Options) SetNoVersioning(b bool) Options

SetNoVersioning returns a new Options value with NoVersioning set to the given value. NoVersioning enables the ability to apply migrations without tracking the versions in the database schema table. Useful for seeding a database or running ad-hoc queries.

Default: false

func (Options) SetTableName 

func (o Options) SetTableName(s string) Options

SetTableName returns a new Options value with TableName set to the given value. TableName is the database schema table used to record migrations.

Default: goose_db_version

func (Options) SetVerbose 

func (o Options) SetVerbose(b bool) Options

SetVerbose returns a new Options value with Verbose set to the given value. Verbose prints additional information.

Default: false

type PartialError 

type PartialError struct {
	// Results contains the results of all migrations that were applied before the error occurred.
	Results []*MigrationResult
	// Failed contains the result of the migration that failed.
	Failed *MigrationResult
	// Err is the error that occurred while running the migration.
	Err error
}

PartialError is returned when a migration fails, but some migrations already got applied.

func (*PartialError) Error 

func (e *PartialError) Error() string

type Provider 

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

Provider is a goose migration provider.

func NewProvider 

func NewProvider(dbDialect Dialect, db *sql.DB, opt Options) (*Provider, error)

NewProvider creates a new goose migration provider.

func (*Provider) ApplyVersion 

func (p *Provider) ApplyVersion(ctx context.Context, version int64, direction bool) (_ *MigrationResult, retErr error)

ApplyVersion applies exactly one migration at the specified version. If a migration cannot be found for the specified version, this method returns ErrNoCurrentVersion. If the migration has been applied already, this method returns ErrAlreadyApplied.

If the direction is true, the migration will be applied. If the direction is false, the migration will be rolled back.

It is safe for concurrent use.

func (*Provider) Close 

func (p *Provider) Close() error

Close closes the database connection.

func (*Provider) Down 

func (p *Provider) Down(ctx context.Context) (*MigrationResult, error)

Down rolls back the most recently applied migration. If there are no migrations to apply, this method returns ErrNoMigrations.

If using out-of-order migrations, this method will roll back the most recently applied migration that was applied out-of-order. ???

func (*Provider) DownTo 

func (p *Provider) DownTo(ctx context.Context, version int64) ([]*MigrationResult, error)

DownTo rolls back all migrations down to but not including the specified version.

For example, suppose we are currently at migrations 11 and the requested version is 9. In this scenario only migrations 11 and 10 will be rolled back.

It is safe for concurrent use.

func (*Provider) GetDBVersion 

func (p *Provider) GetDBVersion(ctx context.Context) (_ int64, retErr error)

GetDBVersion retrieves the max version applied to the database, regardless of when it was applied. If no migrations have been applied, it returns 0.

It is safe for concurrent use.

func (*Provider) ListSources 

func (p *Provider) ListSources() []*Source

func (*Provider) Ping 

func (p *Provider) Ping(ctx context.Context) error

Ping attempts to ping the database to verify a connection is available.

func (*Provider) Redo 

func (p *Provider) Redo(ctx context.Context) ([]*MigrationResult, error)

Redo rolls back the most recently applied migration, then runs it again.

Important, it is not safe to run this function concurrently with other goose functions.

func (*Provider) Status 

func (p *Provider) Status(ctx context.Context, opts *StatusOptions) (_ []*MigrationStatus, retErr error)

Status returns the status of all migrations. The returned slice is ordered by ascending version.

The provided StatusOptions is optional and may be nil if defaults should be used.

It is safe for concurrent use.

func (*Provider) Up 

func (p *Provider) Up(ctx context.Context) ([]*MigrationResult, error)

Up applies all available migrations. If there are no migrations to apply, this method returns empty list and nil error.

It is safe for concurrent use.

func (*Provider) UpByOne 

func (p *Provider) UpByOne(ctx context.Context) (*MigrationResult, error)

UpByOne applies the next available migration. If there are no migrations to apply, this method returns ErrNoMigrations.

It is safe for concurrent use.

func (*Provider) UpTo 

func (p *Provider) UpTo(ctx context.Context, version int64) ([]*MigrationResult, error)

UpTo applies all available migrations up to and including the specified version. If there are no migrations to apply, this method returns empty list and nil error.

For example, suppose there are 3 new migrations available 9, 10, 11. The current database version is 8 and the requested version is 10. In this scenario only versions 9 and 10 will be applied.

It is safe for concurrent use.

type Source 

type Source struct {
	// Full path to the migration file.
	//
	// Example: /path/to/migrations/001_create_users_table.sql
	Fullpath string
	// Version is the version of the migration.
	Version int64
	// Type is the type of migration.
	Type SourceType
}

Source represents a single migration source file on disk.

func Collect 

func Collect(dir string, excludes []string) ([]*Source, error)

Collect returns a slice of Sources found in the given directory.

type SourceType 

type SourceType int
const (
	SourceTypeGo SourceType = iota + 1
	SourceTypeSQL
)

func (SourceType) String 

func (t SourceType) String() string

type StatusOptions 

type StatusOptions struct {
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
goose
examples
go-migrations
go-migrations/migrations
internal
check
cli
dialectadapter
dialectadapter/dialectquery
migration
migrationstats
migrationstats/migrationstatsos
normalizedsn
sqlparser
testdb

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.