roamer

package module
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Sep 30, 2022 License: MIT Imports: 16 Imported by: 0

README

roamer CI status Go Reference

roamer is a tool that makes handling database migrations easy. It's inspired by alembic and golang-migrate.

It's available as a command-line tool that can be used with any programming language or framework; however, if you're using Go, you can also embed roamer directly into your program.

Note While the command-line interface is mostly stable, the Go API should not be considered stable quite yet! It's possible that a future release of roamer might change the Go API; however, if that does happen, the breaking change would be released in a new minor version, following the Go module versioning policy.

Documentation

First, follow the installation instructions.

Then, you're encouraged to follow along with the guided example.

Also, if you want to provide instructions for other users on how to set up roamer with your project, you can link to the Connecting an existing project to your database wiki page.

Documentation

Index

Constants

This section is empty.

Variables

View Source
var DefaultConfig = Config{
	Environment: EnvironmentConfig{
		MigrationDirectory: "migrations/",
		MinimumVersion:     GetVersionString(),
	},
}

DefaultConfig contains the default configuration options, used when creating a new environment.

View Source
var DefaultLocalConfig = LocalConfig{
	Database: LocalDatabaseConfig{
		Driver: DriverTypeMySQL,
		DSN:    "user:password@tcp(localhost:3306)/dbname",
	},
}

DefaultLocalConfig contains the default configuration options, used when creating a new environment.

View Source
var ErrEnvironmentMissingConfig = errors.New("roamer: environment is missing roamer.toml file")

ErrEnvironmentMissingConfig is returned when the environment is missing a roamer.toml file.

View Source
var ErrEnvironmentMissingLocalConfig = errors.New("roamer: environment is missing local config file")

ErrEnvironmentMissingLocalConfig is returned when the environment is missing a local config file.

View Source
var ErrEnvironmentWasFile = errors.New("roamer: environment path is a file, not a folder! make sure you provide the *path* to your roamer.toml, not the actual file")

ErrEnvironmentWasFile is returned when you provide a file as your environment path.

View Source
var ErrMigrationNotFound = errors.New("roamer: could not find the requested migration")

ErrMigrationNotFound is returned when an attempt is made to get a migration that does not exist.

View Source
var ErrVersionTooOld = errors.New("roamer: this environment requires a newer version of roamer")

ErrVersionTooOld is returned when the environment requires a newer version of roamer.

Functions

func GetVersionString

func GetVersionString() string

GetVersionString returns the version string associated with this version of roamer.

Types

type AppliedMigration

type AppliedMigration struct {
	ID        string
	AppliedAt int
	Dirty     bool
}

An AppliedMigration represents a history entry, describing a migration that had been applied to the database.

type Config

type Config struct {
	Environment EnvironmentConfig
}

A Config struct defines some configuration parameters for roamer.

type Direction

type Direction int

A Direction describes the direction of a Migration or an Operation.

const (
	DirectionUp   Direction = 1
	DirectionDown Direction = -1
)

The available directions.

func (Direction) String

func (d Direction) String() string

String returns a string representation of the Direction.

type DriverType

type DriverType string

A DriverType describes the type of database being used with roamer.

const (
	DriverTypeMySQL   DriverType = "mysql"
	DriverTypeSQLite3 DriverType = "sqlite3"
)

The available driver types.

type Environment

type Environment struct {
	Config
	LocalConfig
	// contains filtered or unexported fields
}

An Environment is the context in which roamer operates. It contains migrations and configuration data. Do not create this struct manually; use the NewEnvironment function instead.

func NewEnvironment

func NewEnvironment(config Config, localConfig LocalConfig, db *sql.DB, fs http.FileSystem) (*Environment, error)

NewEnvironment creates a new environment, reading from the given config and http.FileSystem and using the given *sql.DB.

func NewEnvironmentFromDisk

func NewEnvironmentFromDisk(basePath string, localConfigName string) (*Environment, error)

NewEnvironmentFromDisk creates a new environment with the given path.

func (*Environment) ApplyMigration

func (e *Environment) ApplyMigration(migration Migration, direction Direction, stamp bool) error

ApplyMigration applies the migration to the database.

func (*Environment) BeginTransaction

func (e *Environment) BeginTransaction() (*sql.Tx, error)

BeginTransaction begins a new transaction, which can then be used to apply migrations.

func (*Environment) CreateMigration

func (e *Environment) CreateMigration(description string) error

CreateMigration creates a new migration with the given name.

func (*Environment) GetHistoryTableName

func (e *Environment) GetHistoryTableName() string

GetHistoryTableName gets the name of the table roamer is using to track history.

func (*Environment) GetLastAppliedMigration

func (e *Environment) GetLastAppliedMigration() (*AppliedMigration, error)

GetLastAppliedMigration gets the last migration that has been applied to the database, returning nil if nothing has been applied.

func (*Environment) GetMigrationByID

func (e *Environment) GetMigrationByID(id string) (Migration, error)

GetMigrationByID gets the migration with the given ID.

func (*Environment) ListAllMigrations

func (e *Environment) ListAllMigrations() ([]Migration, error)

ListAllMigrations gets all of the migrations defined in the migrations directory.

func (*Environment) ListAppliedMigrations

func (e *Environment) ListAppliedMigrations() ([]AppliedMigration, error)

ListAppliedMigrations gets all of the migrations that have been applied to the database.

func (*Environment) NewOperation

func (e *Environment) NewOperation(from *Migration, to *Migration) (*Operation, error)

NewOperation creates a new operation, with the given endpoints, in the environment.

func (*Environment) ResolveIDOrOffset

func (e *Environment) ResolveIDOrOffset(idOrOffset string) (*Migration, error)

ResolveIDOrOffset looks up and returns the requested migration. It handles absolute IDs, absolute offsets (such as @2), and relative offsets (such as @+1).

func (*Environment) VerifyExist

func (e *Environment) VerifyExist() (bool, error)

VerifyExist checks that that all applied migrations exist on disk.

func (*Environment) VerifyNoDirty

func (e *Environment) VerifyNoDirty() (bool, error)

VerifyNoDirty checks that the environment has no dirty migrations.

func (*Environment) VerifyOrder

func (e *Environment) VerifyOrder() (bool, error)

VerifyOrder checks that the order of migrations on disk matches the order in the history.

func (*Environment) VerifySafeToApply

func (e *Environment) VerifySafeToApply() (bool, error)

VerifySafeToApply checks that it is safe to apply migrations, running all other verification checks.

type EnvironmentConfig

type EnvironmentConfig struct {
	// MigrationDirectory defines where the migrations directory is, relative to the location of the config file.
	MigrationDirectory string

	// MinimumVersion defines the minimum version of roamer required for this environment.
	MinimumVersion string
}

An EnvironmentConfig struct defines configuration parameters related to the environment's setup.

type InvalidInputError

type InvalidInputError struct {
	Input string
}

InvalidInputError is reported when invalid input is provided to roamer.

func (InvalidInputError) Error

func (e InvalidInputError) Error() string

Error returns a string representation of the InvalidInputError.

type LocalConfig

type LocalConfig struct {
	Database LocalDatabaseConfig
}

A LocalConfig struct defines several local configuration parameters for roamer. This is mainly used for describing a database connection

type LocalDatabaseConfig

type LocalDatabaseConfig struct {
	Driver DriverType
	DSN    string
}

A LocalDatabaseConfig struct defines configuration parameters for the database connection.

type Migration

type Migration struct {
	ID          string
	Description string

	Index int
	// contains filtered or unexported fields
}

A Migration represents a distinct operation performed on a database.

type OffsetBoundError

type OffsetBoundError struct {
	Input string
}

OffsetBoundError is reported when an offset is provided to roamer that goes out of bounds.

func (OffsetBoundError) Error

func (e OffsetBoundError) Error() string

Error returns a string representation of the OffsetBoundError.

type Operation

type Operation struct {
	From *Migration
	To   *Migration

	Direction
	Distance int

	Stamp bool

	PreMigrationCallback func(*Migration, Direction)
	// contains filtered or unexported fields
}

An Operation describes a series of migrations, bringing the database up or down to a new state.

func (*Operation) DistanceString

func (o *Operation) DistanceString() string

DistanceString returns a string repesentation of the distance spanned by the Operation.

func (*Operation) Run

func (o *Operation) Run() error

Run runs the given operation.

type OperationError

type OperationError struct {
	Migration *Migration
	Inner     error
}

An OperationError is returned when there's an error while applying a certain migration.

func (OperationError) Error

func (e OperationError) Error() string

Error returns a string representation of the OperationError.

type UndecodedConfigError

type UndecodedConfigError struct {
	Filename  string
	Undecoded []toml.Key
}

UndecodedConfigError is reported when there are entries in a config file that could not be understood.

func (UndecodedConfigError) Error

func (e UndecodedConfigError) Error() string

Error returns a string representation of the UndecodedConfigError.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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