Documentation ¶
Overview ¶
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
Index ¶
- Constants
- Variables
- func ApplyMigration(driver Driver, directoryPath string, direction Direction, version string) (err error)
- func Basename(mig Migration) (string, error)
- func CreateSchemaMigrationsTable(driver Driver) (err error)
- func DumpSchema(driver Driver) (err error)
- func Info(driver Driver, directoryPath string, direction Direction, ...) (err error)
- func Init(pathToFile string) (err error)
- func Migrate(driver Driver, directoryPath string, direction Direction, ...) (err error)
- type AppliedVersions
- type DSNParams
- type Direction
- type Driver
- type Migration
- type MigrationParams
- type MigrationsConf
- type PostgresParams
Constants ¶
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" )
Variables ¶
Functions ¶
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 ¶
Basename generates a migration file's basename. The output format is: "${direction}-2006010215040506-${name}.sql".
func CreateSchemaMigrationsTable ¶
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 ¶
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.
Types ¶
type AppliedVersions ¶
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. DirForward // DirReverse is like migrate down; used for rollbacks. Not all changes can // be rolled back. DirReverse )
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.
type Migration ¶
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 ¶
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.