migrate

Documentation

Overview

Package migrate applies versioned SQL migrations to a Popcorn Web database.

Importing this package opts the migration engine into the binary. A host Go build links goose directly; a TinyGo build runs the pw command as a child process instead, because goose is host-only. Both selections expose the same API and behavior.

Index

• Constants
• func Replay(ctx context.Context, db *sql.DB, script string) error
• func Snapshot(ctx context.Context, options ...Option) (string, error)
• func SourceHash(options ...Option) (string, error)
• type Applied
• type Option
  • func WithDir(path string) Option
  • func WithFS(fsys fs.FS) Option
• type Result
  • func Up(ctx context.Context, dsn string, options ...Option) (Result, error)
• type State
  • func Status(ctx context.Context, dsn string, options ...Option) ([]State, error)

Constants

const DSNEnv = "PW_MIGRATE_DSN"

DSNEnv carries a database DSN to a delegated pw child process. A DSN is never passed as a process argument.

const DefaultDir = "migrations"

DefaultDir is the project-relative migration directory.

const Delegated = false

Delegated reports whether migration work runs in a pw child process.

Functions

func Replay

func Replay(ctx context.Context, db *sql.DB, script string) error

Replay executes a snapshot produced by Snapshot against an empty database. The script is plain SQL, so this works on every toolchain.

func Snapshot

func Snapshot(ctx context.Context, options ...Option) (string, error)

Snapshot applies every migration to a throwaway database and returns SQL that reproduces the migrated schema, data, and recorded versions.

func SourceHash

func SourceHash(options ...Option) (string, error)

SourceHash identifies a migration source tree so callers can cache a snapshot and invalidate it when any migration changes.

Types

type Applied

type Applied struct {
	Version   int64
	Path      string
	Direction string
	Duration  time.Duration
}

Applied describes one migration that ran.

type Option

type Option func(*settings) error

Option configures a migration source.

func WithDir

func WithDir(path string) Option

WithDir reads migrations from a directory.

func WithFS

func WithFS(fsys fs.FS) Option

WithFS reads migrations from an embedded or otherwise virtual tree.

type Result

type Result struct {
	Previous int64
	Current  int64
	Applied  []Applied
}

Result reports the version change produced by an action.

func Up

func Up(ctx context.Context, dsn string, options ...Option) (Result, error)

Up applies every pending migration to the configured database.

type State

type State struct {
	Version   int64
	Path      string
	Applied   bool
	AppliedAt time.Time
}

State is the recorded state of one migration source.

func Status

func Status(ctx context.Context, dsn string, options ...Option) ([]State, error)

Status reports every known migration and whether it is applied.