README
¶
Updater
Semantic updater and migrator for GoLang executables.
Why? 
Updater aims to unify semantic migrations and executable updates using GitHub repositories in GoLang. You can seamlessly update executables and run any SQL database migrations that depend on the specific version of the application. Callbacks can be passed to each migration allowing you to edit environment variables, or a directory structure.
Installation
go get -u github.com/ainsleyclark/updater
Example
Adding a migration
Migrations are stored in memory, so you can call AddMigration from anywhere with a version number, SQL statement
(optional) and CallBack functions (optional). When Update() is called, migrations will run from the the base
version right up until the remote GitHub version.
func init() {
err := updater.AddMigration(&updater.Migration{
Version: "v0.0.2", // The version of the migration
SQL: strings.NewReader("UPDATE my_table SET 'title' WHERE id = 1"),
CallBackUp: func() error { return nil }, // Runs on up of migration.
CallBackDown: func() error { return nil }, // Runs on error of migration.
Stage: updater.Patch, // Can be Patch, Major or Minor.
})
if err != nil {
log.Fatal(err)
}
}
Creating the updater
To create an updater, simply call updater.New() with options Updater.Options{} The zip file is parsed with the
current version.
u, err := updater.New(updater.Options{
GithubURL: "https://github.com/ainsleyclark/my-repo", // The URL of the Git Repos
Version: "v0.0.1", // The currently running version
Verify: false, // Updates will be verified by checking the new exec with -version
DB: nil, // Pass in an sql.DB for a migration
})
if err != nil {
log.Fatal(err)
}
status, err := u.Update(fmt.Sprintf("my-repo_v0.0.2_%s_%s.zip", runtime.GOOS, runtime.GOARCH))
if err != nil {
return
}
fmt.Println(status)
Credits
Shout out to go-rocket-update for providing an excellent API for self updating executables.
Documentation
¶
Index ¶
Constants ¶
const ( // Major signals backward-incompatible public API changes. // This release carries no guarantee that it will be // backward compatible with preceding major versions. Major = "major" // Minor signals backward-compatible public API changes. // This release guarantees backward compatibility and // stability. Minor = "minor" // Patch signals changes that don't affect the module's // public API or its dependencies. This release // guarantees backward compatibility and // stability. Patch = "patch" )
const ( // Unknown update status (something went wrong) Unknown Status = iota // DatabaseError is returned by update when a database // connection could not be established or there was // an error processing the transaction. DatabaseError = 1 // ExecutableError is returned by update when there was // a error updating the executable from GitHub. ExecutableError = 2 // CallBackError is returned by update when there was // a error with one of the migration callbacks. CallBackError = 3 // UpToDate status is used to define when the application // is already up to date. UpToDate = 5 // Updated is the success status code returned by Update // when everything passed. Updated = 6 )
Variables ¶
var ( // ErrCallBackMismatch is returned by AddMigration when // there has been a mismatch in the amount of callbacks // passed. Each migration should have two callbacks, // one up and one down, or none at all. ErrCallBackMismatch = errors.New("both CallBackUp and CallBackDown must be set") )
var ( // ErrRepositoryURL is the error returned by Validate when // a malformed repository is used. ErrRepositoryURL = errors.New("error checking repo url") )
var ( // ErrVersionMisMatch is returned by verifyInstallation if // the new downloaded version did not output the same // version parsed to Update(). ErrVersionMisMatch = errors.New("version mismatch in updated executable") )
Functions ¶
func AddMigration ¶
AddMigration adds a migration to the update registry which will be called when Update() is run. The version and Stage must be attached to the migration.
Types ¶
type CallBackFn ¶
type CallBackFn func() error
CallBackFn is the function type when migrations are running up or down.
type Migration ¶
type Migration struct {
// The main version of the migration such as "v0.0.1"
Version string
// The migration file, byte value of the SQL migration.
SQL io.Reader
// CallBackUp is a function called when the migration
// is going up, this can be useful when manipulating
// files and directories for the current version.
CallBackUp CallBackFn
// CallBackUp is a function called when the migration
// is going down, this is only called if an update
// failed. And must be provided if CallBackUp is
// defined.
CallBackDown CallBackFn
// Stage defines the release stage of the migration such as
// Major, Minor or Patch,
Stage Stage
}
Migration represents a singular migration for a single version.
func GetMigration ¶
GetMigration Retrieves a migration from the registry by looking up the version. An error will be returned on failed lookup.
type MigrationRegistry ¶ added in v0.0.2
type MigrationRegistry []*Migration
MigrationRegistry contains a slice of pointers to each migration.
func AllMigrations ¶ added in v0.0.2
func AllMigrations() MigrationRegistry
AllMigrations returns all migrations in the registry.
func (MigrationRegistry) Len ¶ added in v0.0.2
func (m MigrationRegistry) Len() int
func (MigrationRegistry) Less ¶ added in v0.0.2
func (m MigrationRegistry) Less(i, j int) bool
func (MigrationRegistry) Sort ¶ added in v0.0.2
func (m MigrationRegistry) Sort()
Sort MigrationRegistry is a type that implements the sort.Interface interface so that versions can be sorted.
func (MigrationRegistry) Swap ¶ added in v0.0.2
func (m MigrationRegistry) Swap(i, j int)
type Options ¶
type Options struct {
// The URL of the GitHub Repository to obtain the
// executable from.
GithubURL string
// The currently running version.
Version string
// If set to true, updates will be verified by checking the
// newly downloaded executable version number using the
// -version flag.
Verify bool
// SQL database to apply migrations, migrations will not
// be run if sql.DB is nil.
DB *sql.DB
// contains filtered or unexported fields
}
Options define the core arguments parsed to the migrator.
type Patcher ¶
type Patcher interface {
Update(archive string) (Status, error)
HasUpdate() (bool, error)
LatestVersion() (string, error)
}
Patcher describes the set of methods used for determining if the application has any updates, retrieving the latest version and running migrations.
type Stage ¶
type Stage string
Stage represents the the different version stages that can be defined in a migration such as a Patch, Minor or Major.
type Status ¶
type Status int
Status defines the status codes returned by the Update() function used for debugging any issues with updating the application.
type Updater ¶
type Updater struct {
// contains filtered or unexported fields
}
Updater represents the library for updating golang executables and running migrations.
func New ¶
New returns a new Updater with the options passed. If validation failed on the options an error will be returned.
func (*Updater) HasUpdate ¶
HasUpdate determines if there is an update for the program. Returns a error if there are no releases or tags for the repo.
func (*Updater) LatestVersion ¶
LatestVersion retrieves the most up to date version of the program. Returns a error if there are no releases // or tags for the repo.
Source Files