v0.0.0-...-a6d4a70 Latest Latest

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

Go to latest
Published: Dec 19, 2019 License: ISC Imports: 15 Imported by: 0



Package godfish is a database migration library built to support a CLI tool, also called godfish. This documentation is available for development. To get the CLI and/or get help with it:

go get -u bitbucket.org/rafaelespinoza/godfish
godfish -h



View Source
const (

	// TimeFormat provides a consistent timestamp layout for migration
	// filenames. Formatting time in go works a little differently than in other
	// languages. Read more at: https://golang.org/pkg/time/#pkg-constants.
	TimeFormat = "20060102150405"


View Source
var (
	ErrNoVersionFound               = errors.New("no version found")
	ErrNoFilesFound                 = errors.New("no files found")
	ErrSchemaMigrationsDoesNotExist = errors.New("table \"schema_migrations\" does not exist")


func ApplyMigration

func ApplyMigration(driver Driver, directoryPath string, direction Direction, version string) (err error)

ApplyMigration runs a migration at directoryPath with the specified version and direction.

func Basename

func Basename(mig Migration) (string, error)

Basename generates a migration file's basename. The output format is: "${direction}-2006010215040506-${name}.sql".

func CreateSchemaMigrationsTable

func CreateSchemaMigrationsTable(driver Driver) (err error)

CreateSchemaMigrationsTable creates a table to track status of migrations on the database. Running any migration will create the table, so you don't usually need to call this function.

func DumpSchema

func DumpSchema(driver Driver) (err error)

DumpSchema describes the database structure and outputs to standard out.

func Info

func Info(driver Driver, directoryPath string, direction Direction, finishAtVersion string) (err error)

Info displays the outputs of various helper functions.

func Init

func Init(pathToFile string) (err error)

Init creates a configuration file at pathToFile unless it already exists.

func Migrate

func Migrate(driver Driver, directoryPath string, direction Direction, finishAtVersion string) (err error)

Migrate executes all migrations at directoryPath in the specified direction.


type AppliedVersions

type AppliedVersions interface {
	Close() error
	Next() bool
	Scan(dest ...interface{}) error

AppliedVersions represents an iterative list of migrations that have been run against the database and have been recorded in the schema migrations table. It's enough to convert a *sql.Rows struct when implementing the Driver interface since a *sql.Rows already satisfies this interface. See existing Driver implementations in this package for examples.

type DSNParams

type DSNParams interface {
	String() string

DSNParams describes a type which generates a data source name for connecting to a database. The output will be passed to the standard library's sql.Open method to connect to a database.

type Direction

type Direction uint8

Direction describes which way the change goes.

const (
	// DirUnknown is a fallback value for an invalid direction.
	DirUnknown Direction = iota
	// DirForward is like migrate up, typically the change you want to apply to
	// the DB.
	// DirReverse is like migrate down; used for rollbacks. Not all changes can
	// be rolled back.

func (Direction) String

func (d Direction) String() string

type Driver

type Driver interface {
	// Name should return the name of the driver: ie: postgres, mysql, etc
	Name() string

	// Connect should open a connection (a *sql.DB) to the database and save an
	// internal reference to that connection for later use. This library might
	// call this method multiple times, so use the internal reference if it's
	// present instead of reconnecting to the database.
	Connect() (*sql.DB, error)
	// Close should check if there's an internal reference to a database
	// connection (a *sql.DB) and if it's present, close it. Then reset the
	// internal reference to that connection to nil.
	Close() error
	// DSNParams returns data source name info, ie: how do I connect?
	DSNParams() DSNParams

	// AppliedVersions queries the schema migrations table for migration
	// versions that have been executed against the database.
	AppliedVersions() (AppliedVersions, error)
	// CreateSchemaMigrationsTable should create a table to record migration
	// versions once they've been applied. The version should be a timestamp as
	// a string, formatted as the TimeFormat variable in this package.
	CreateSchemaMigrationsTable() error
	// DumpSchema should output the database structure to stdout.
	DumpSchema() error
	// Execute runs the schema change and commits it to the database. The query
	// parameter is a SQL string and may contain placeholders for the values in
	// args. Input should be passed to conn so it could be sanitized, escaped.
	Execute(query string, args ...interface{}) error
	// UpdateSchemaMigrations records a timestamped version of a migration that
	// has been successfully applied by adding a new row to the schema
	// migrations table.
	UpdateSchemaMigrations(dir Direction, version string) error

A Driver describes what a database driver (anything at https://github.com/golang/go/wiki/SQLDrivers) should be able to do.

func NewDriver

func NewDriver(driverName string, dsnParams DSNParams) (driver Driver, err error)

NewDriver initializes a Driver implementation by name and connection parameters. An unrecognized name returns an error. The dsnParams should also provide whatever is needed by the Driver.

type Migration

type Migration interface {
	Direction() Direction
	Name() string
	Timestamp() time.Time

A Migration is a database change with a direction name and timestamp. Typically, a Migration with a DirForward Direction is paired with another migration of DirReverse that has the same name.

type MigrationParams

type MigrationParams struct {
	Forward    Migration
	Reverse    Migration
	Reversible bool
	Directory  *os.File

MigrationParams collects inputs needed to generate migration files. Setting Reversible to true will generate a migration file for each direction. Otherwise, it only generates a file in the forward direction. The Directory field refers to the path to the directory with the migration files.

func NewMigrationParams

func NewMigrationParams(name string, reversible bool, directory *os.File) (*MigrationParams, error)

NewMigrationParams constructs a MigrationParams that's ready to use. Passing in true for reversible means that a complementary SQL file will be made for rolling back. The directory parameter specifies which directory to output the files to.

func (*MigrationParams) GenerateFiles

func (m *MigrationParams) GenerateFiles() (err error)

GenerateFiles creates the migration files. If the migration is reversible it generates files in forward and reverse directions; otherwise is generates just one migration file in the forward direction. It closes each file handle when it's done.

type MigrationsConf

type MigrationsConf struct {
	DriverName  string `json:"driver_name"`
	PathToFiles string `json:"path_to_files"`

MigrationsConf is intended to lend customizations such as specifying the path to the migration files.

type PostgresParams

type PostgresParams struct {
	Encoding string // Encoding is the client encoding for the connection.
	Host     string // Host is the name of the host to connect to.
	Name     string // Name is the database name.
	Pass     string // Pass is the password to use for the connection.
	Port     string // Port is the connection port.
	User     string // User is the name of the user to connect as.

PostgresParams implements the DSNParams interface and defines keys, values needed to connect to a postgres database.

func (PostgresParams) String

func (p PostgresParams) String() string

String generates a data source name (or connection URL) based on the fields.

Jump to

Keyboard shortcuts

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