Documentation ¶
Overview ¶
Package migrator is a library that makes it super simple to run database migrations.
Index ¶
- Constants
- Variables
- func NewErrCreatingHistoryTable(err error) error
- func NewErrInvalidMigrationID(migration string, err error) error
- func NewErrMissingRollbackFile(file string) error
- func NewErrReadingFile(file string, err error) error
- func NewErrRunningMigration(m Migration, err error) error
- func NewErrRunningRollback(r Rollback, err error) error
- func NewErrSearchingDir(dir string, err error) error
- type Configuration
- type DatabaseServicer
- type ErrCreatingHistoryTable
- type ErrInvalidMigrationID
- type ErrMissingRollbackFile
- type ErrReadingFile
- type ErrRunningMigration
- type ErrRunningRollback
- type ErrSearchingDir
- type LogServicer
- type Migration
- type Migrator
- type RanMigration
- type Rollback
Constants ¶
const ( // MySQLDatabaseType represents a MySQL database type. MySQLDatabaseType = iota // PostgreSQLDatabaseType represents a PostgreSQL database type. PostgreSQLDatabaseType )
Variables ¶
var ( // ErrConfigurationInvalid is an error that is raised when a configuration // property is invalid. ErrConfigurationInvalid = errors.New("configuration of Migrator is invalid") // ErrDbServicerNotInitialised is an error that is raised when the database // server on the cmd.Migration struct has not been initialised. ErrDbServicerNotInitialised = errors.New("database servicer not initialised") // ErrNoMigrationsInDir is an error that is raised when the migrations directory // does not have any migration scripts. ErrNoMigrationsInDir = errors.New("no migration files in configured migrations dir") // ErrNoRollbacksInDir is an error that is raised when the rollbacks directory does // not have any rollback scripts. ErrNoRollbacksInDir = errors.New("no rollback files in configured rollbacks dir") // ErrUnableToRetrieveRanMigrations is an error that is raised when the // migration history table cannot be queried. ErrUnableToRetrieveRanMigrations = errors.New("unable to retrieve ran migrations") // ErrCreatingDbTransaction is an error that is raised when the application // is unable to create a transaction in the database. ErrCreatingDbTransaction = errors.New("unable to create database transaction") // ErrNotLatestMigration is an error that is raised when the user // tries to rollback a migration which is not the latest migration. This // was explicitly designed in this way to ensure the user has knowledge // of every single migration that they are rolling back. ErrNotLatestMigration = errors.New("cannot rollback a not-latest migration") // ErrCommittingTransaction is an error that is raised when the application // is, for some reason, unable to commit the transaction to the database. ErrCommittingTransaction = errors.New("unable to commit database transaction") )
Functions ¶
func NewErrCreatingHistoryTable ¶
NewErrCreatingHistoryTable creates a new instance of the ErrCreatingHistoryTable struct.
func NewErrInvalidMigrationID ¶
NewErrInvalidMigrationID creates a new instance of the ErrInvalidMigrationId struct.
func NewErrMissingRollbackFile ¶
NewErrMissingRollbackFile creates a new instance of the ErrMissingRollbackFile struct.
func NewErrReadingFile ¶
NewErrReadingFile creates a new instance of the ErrReadingFile struct.
func NewErrRunningMigration ¶
NewErrRunningMigration creates a new instance of the ErrRunningMigration struct.
func NewErrRunningRollback ¶
NewErrRunningRollback creates a new instance of the ErrRunningRollback struct.
func NewErrSearchingDir ¶
NewErrSearchingDir creates a new instance of the ErrSearchingDir struct.
Types ¶
type Configuration ¶
type Configuration struct { // DatabaseConnectionString is the connection string where the migrations // will be ran against. DatabaseConnectionString string // MigrationsDir is the directory where the migration SQL scripts // are stored. MigrationsDir string // RollbacksDir is the directory where the rollback SQL scripts // are stored. RollbacksDir string // MigrationToRollback is the migration that needs to be rolled back. This // is useful when a development mistake may have been made. MigrationToRollback string }
Configuration is an object where the configuration of migrator is stored.
func (Configuration) Validate ¶
func (c Configuration) Validate() error
Validate validates the configuration object ensuring it is ready to be used within the Migrator application.
type DatabaseServicer ¶
type DatabaseServicer interface { // BeginTransaction creates a transaction in the implementing database // servicer. BeginTransaction() error // CommitTransaction ends the created transaction providing there is one // and commits it to the database. CommitTransaction() error // RanMigrations retrieves all previously ran migrations. RanMigrations() ([]RanMigration, error) // RemoveMigrationHistory removes the specified migration from the // history table. RemoveMigrationHistory(m Migration) error // RollbackTransaction ends the created transaction providing there is one // and rolls it back, ensuring there are no changes to the database made. RollbackTransaction() error // RollbackMigration rolls back the specified migration and removes it // from the RanMigrations table. RollbackMigration(m Migration) error // RunMigration runs the specified migration against the current database. RunMigration(m Migration) error // TryCreateHistoryTable creates the migration history table if it does // not already exist. The boolean return value indicates whether or not // the table had to be created. TryCreateHistoryTable() (bool, error) // WriteMigrationHistory writes that a migration has been ran into the // migration history table. WriteMigrationHistory(m Migration) error }
DatabaseServicer represents a service that runs the migrations.
type ErrCreatingHistoryTable ¶
type ErrCreatingHistoryTable struct {
// contains filtered or unexported fields
}
ErrCreatingHistoryTable is an error that is raised when the application is unable to create the migration history table.
func (ErrCreatingHistoryTable) Error ¶
func (e ErrCreatingHistoryTable) Error() string
Error yields the error string for the ErrCreatingHistoryTable struct.
type ErrInvalidMigrationID ¶
type ErrInvalidMigrationID struct {
// contains filtered or unexported fields
}
ErrInvalidMigrationID is an error that is raised when the index on a migration files does not successfully convert to an integer.
func (ErrInvalidMigrationID) Error ¶
func (e ErrInvalidMigrationID) Error() string
Error yields the error string for the ErrInvalidMigrationId struct.
type ErrMissingRollbackFile ¶
type ErrMissingRollbackFile struct {
// contains filtered or unexported fields
}
ErrMissingRollbackFile is an error that is raised when a migration file does not have a corresponding rollback file (in the format of ROLLBACK-{original file name}).
func (ErrMissingRollbackFile) Error ¶
func (e ErrMissingRollbackFile) Error() string
Error yields the error string for the ErrMissingRollbackFile error struct.
type ErrReadingFile ¶
type ErrReadingFile struct {
// contains filtered or unexported fields
}
ErrReadingFile is an error that is raised when the application is unable to read a migration/rollback file.
func (ErrReadingFile) Error ¶
func (e ErrReadingFile) Error() string
Error yields the error string for the ErrReadingFile struct.
type ErrRunningMigration ¶
type ErrRunningMigration struct {
// contains filtered or unexported fields
}
ErrRunningMigration is an error that is raised when the application fails to run a migration.
func (ErrRunningMigration) Error ¶
func (e ErrRunningMigration) Error() string
Error yields the error string for the ErrRunningMigration struct.
type ErrRunningRollback ¶
type ErrRunningRollback struct {
// contains filtered or unexported fields
}
ErrRunningRollback is an error that is raised when the application fails to run a rollback.
func (ErrRunningRollback) Error ¶
func (e ErrRunningRollback) Error() string
Error yields the error string for the ErrRunningRollback struct.
type ErrSearchingDir ¶
type ErrSearchingDir struct {
// contains filtered or unexported fields
}
ErrSearchingDir is an error that is raised when the searching of a directory fails.
func (ErrSearchingDir) Error ¶
func (e ErrSearchingDir) Error() string
Error yields the error string for the ErrSearchingDir error struct.
type LogServicer ¶
type LogServicer interface { // Printf formats a string with a set of parameters before printing it to // the output. Printf(format string, v ...interface{}) }
LogServicer abstracts common logging functions so we do not have to call the log.Logger implementation directly.
type Migration ¶
type Migration struct { // ID represents where the migration is in the order of those to be // completed. ID int // FileName is the file name of the migration. FileName string // FileContents is the contents of the migration to run. FileContents []byte // Rollback is the rollback file for the current migration. There must // always be one; otherwise an error will occur. Rollback Rollback }
Migration is a representation of a migration that needs to run.
type Migrator ¶
type Migrator struct { // Config is the configuration object of the Config Configuration // DatabaseServicer is the service that performs all database operations. DatabaseServicer DatabaseServicer // LogServicer is the service that will perform all logging routines. // This abstraction exists only to decouple the application from the // implementation of log.Logger. LogServicer LogServicer }
Migrator is the main application to be tested.
func NewMigrator ¶
func NewMigrator(c Configuration, db DatabaseServicer, l LogServicer) (Migrator, error)
NewMigrator initialises a set up migrator that can be used without having to manually construct dependencies. You must inject a LogServicer implementation into this function. You will be able to use most logging libraries with it.
type RanMigration ¶
type RanMigration struct { // ID is the identifier of the migration that was ran. ID int // FileName is the name of the migration. FileName string // Ran is when the migration was ran into the database. Ran time.Time }
RanMigration is a representation of a migration that was previously ran into the database.