package provider

import "github.com/pressly/goose/v3/internal/provider"

Index

Types

type MigrationResult 

type MigrationResult struct{}

MigrationResult represents the result of a single migration.

type MigrationStatus 

type MigrationStatus struct {
	// State represents the state of the migration. One of "untracked", "pending", "applied".
	//  - untracked: in the database, but not on the filesystem.
	//  - pending: on the filesystem, but not in the database.
	//  - applied: in both the database and on the filesystem.
	State string
	// AppliedAt is the time the migration was applied. Only set if state is applied or untracked.
	AppliedAt time.Time
	// Source is the migration source. Only set if the state is pending or applied.
	Source Source
}

MigrationStatus represents the status of a single migration.

type Provider 

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

Provider is a goose migration provider. Experimental: This API is experimental and may change in the future.

func NewProvider 

func NewProvider(dialect string, db *sql.DB, fsys fs.FS, opts ...ProviderOption) (*Provider, error)

NewProvider returns a new goose Provider.

The caller is responsible for matching the database dialect with the database/sql driver. For example, if the database dialect is "postgres", the database/sql driver could be github.com/lib/pq or github.com/jackc/pgx.

fsys is the filesystem used to read the migration files. Most users will want to use os.DirFS("path/to/migrations") to read migrations from the local filesystem. However, it is possible to use a different filesystem, such as embed.FS.

Functional options are used to configure the Provider. See ProviderOption for more information.

Unless otherwise specified, all methods on Provider are safe for concurrent use.

Experimental: This API is experimental and may change in the future.

func (*Provider) ApplyVersion 

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

ApplyVersion applies exactly one migration at the specified version. If there is no source for the specified version, this method returns [ErrNoCurrentVersion]. If the migration has been applied already, this method returns [ErrAlreadyApplied].

When direction is true, the up migration is executed, and when direction is false, the down migration is executed. Experimental: This API is experimental and may change in the future.

func (*Provider) Close 

func (p *Provider) Close() error

Close closes the database connection. Experimental: This API is experimental and may change in the future.

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 [ErrNoNextVersion]. Experimental: This API is experimental and may change in the future.

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 instance, if the current database version is 11, and the requested version is 9, only migrations 11 and 10 will be rolled back. Experimental: This API is experimental and may change in the future.

func (*Provider) GetDBVersion 

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

GetDBVersion returns the max version from the database, regardless of the applied order. For example, if migrations 1,4,2,3 were applied, this method returns 4. If no migrations have been applied, it returns 0. Experimental: This API is experimental and may change in the future.

func (*Provider) ListSources 

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

ListSources returns a list of all available migration sources the provider is aware of. Experimental: This API is experimental and may change in the future.

func (*Provider) Ping 

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

Ping attempts to ping the database to verify a connection is available. Experimental: This API is experimental and may change in the future.

func (*Provider) Status 

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

Status returns the status of all migrations, merging the list of migrations from the database and filesystem. The returned items are ordered by version, in ascending order. Experimental: This API is experimental and may change in the future.

func (*Provider) Up 

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

Up applies all pending migrations. If there are no new migrations to apply, this method returns empty list and nil error. Experimental: This API is experimental and may change in the future.

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 [ErrNoNextVersion]. Experimental: This API is experimental and may change in the future.

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 instance, if there are three new migrations (9,10,11) and the current database version is 8 with a requested version of 10, only versions 9 and 10 will be applied. Experimental: This API is experimental and may change in the future.

type ProviderOption 

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

ProviderOption is a configuration option for a goose provider.

func WithSessionLocker 

func WithSessionLocker(locker lock.SessionLocker) ProviderOption

WithSessionLocker enables locking using the provided SessionLocker.

If WithSessionLocker is not called, locking is disabled.

func WithTableName 

func WithTableName(name string) ProviderOption

WithTableName sets the name of the database table used to track history of applied migrations.

If WithTableName is not called, the default value is "goose_db_version".

func WithVerbose 

func WithVerbose() ProviderOption

WithVerbose enables verbose logging.

type Source 

type Source struct {
	// Type is the type of migration.
	Type SourceType
	// 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
}

Source represents a single migration source.

For SQL migrations, Fullpath will always be set. For Go migrations, Fullpath will will be set if the migration has a corresponding file on disk. It will be empty if the migration was registered manually. Experimental: This API is experimental and may change in the future.

type SourceType 

type SourceType string

SourceType represents the type of migration source. 

const (
	// SourceTypeSQL represents a SQL migration.
	SourceTypeSQL SourceType = "sql"
	// SourceTypeGo represents a Go migration.
	SourceTypeGo SourceType = "go"
)

Source Files

provider.go provider_options.go

Version
v3.15.1
Published
Oct 10, 2023
Platform
darwin/amd64
Imports
8 packages
Last checked
38 minutes ago –

Tools for package owners.