more documentation, typos fixes, and small code fixes

Author: braindev

README.md

@@ -4,7 +4,17 @@ A basic database migration library.  Status: ALPHA - API may change
 
 The algorithm used works as follows:
 
-To migrate
+To apply one/all migration(s)
+
+- find all possible migrations
+- find all previously applied migrations
+- apply the next or all the migrations (depending on if one migration is to be applied or all should be applied) in alphanumeric order by migration version that have not been previously applied
+
+To rollback one version
+
+- find all possible migrations
+- find all previously applied migrations
+- find the highest migration version already applied that is in the list of all possible migrations
 
 ### Installation
 
@@ -15,7 +25,7 @@ To migrate
 ```go
 // error handling omitted
 db, err := sql.Open("postgres", "postgres://user@localhost/test?sslmode=disable")
-adaptor, err := adaptor.NewPostgres(db)
+adapter, err := adapter.NewPostgres(db)
 storage := storage.NewFileStorage("/path/to/migrations/directory")
 /*
 assume a directory with with the following:
@@ -25,33 +35,33 @@ assume a directory with with the following:
   0002_another_migration_name_apply.sql
   0002_another_migration_name_rollback.sql
 */
-m, err := dbmigrate.New(adaptor, storage)
+m, err := dbmigrate.New(adapter, storage)
 err = m.ApplyAll()
-# or
+// or
 err = m.ApplyOne()
-# or
+// or
 err = m.RollbackLatest()
 ```
 
-Both migration storage and database adaptors are pluggable.  Their interfaces are simple:
+Both migration storage and database adapters are pluggable.  Their interfaces are simple:
 
 ```go
 type Storage interface {
 	GetMigrationPairs() ([]MigrationPair, error)
 }
 ```
 
-[Included Storage Adaptors](./storage/README.md)
+[Included Storage Adapters](./storage/README.md)
 
 ```go
-type VendorAdaptor interface {
+type VendorAdapter interface {
 	GetAppliedMigrationsOrderedAsc() ([]string, error)
 	ApplyMigration(pair MigrationPair) error
 	RollbackMigration(pair MigrationPair) error
 }
 ```
 
-[Included Database Adaptors](./adaptor/README.md)
+[Included Database Adapters](./adapter/README.md)
 
 ### Goals
 
@@ -72,8 +82,8 @@ type VendorAdaptor interface {
 
 ### TODO
 
-- Add more database adaptors?
+- Add more database adapters?
 - Add more storage options?
 - More tests
 - Force migration at a specific version?
-- Add a changelog
+- Add a changelog

adapter/README.md

@@ -0,0 +1,31 @@
+# DB Migrate Database Adapters
+
+### Postgres Usage
+
+```go
+import "bitbucket.org/braindev/dbmigrate/adapter"
+
+// NewPostgres(db *sql.DB) (*PostgresAdapter, error)
+pgadapter, err := adapter.NewPostgres(db)
+```
+
+### MySQL Usage
+
+```go
+import "bitbucket.org/braindev/dbmigrate/adapter"
+
+// NewMySQL(db *sql.DB) (*MySQLAdapter, error)
+mysqladapter, err := adapter.NewMySQL(db)
+```
+
+### Custom Adapter
+
+To create a custom adapter implement the following interface:
+
+```go
+type VendorAdapter interface {
+	GetAppliedMigrationsOrderedAsc() ([]string, error)
+	ApplyMigration(pair MigrationPair) error
+	RollbackMigration(pair MigrationPair) error
+}
+```

adaptor/mysql.go renamed to adapter/mysql.go

@@ -1,27 +1,27 @@
-package adaptor
+package adapter
 
 import (
 	"database/sql"
 
 	"bitbucket.org/braindev/dbmigrate"
 )
 
-// MySQLAdaptor is a PostgreSQL DBMigrate adaptor
-type MySQLAdaptor struct {
+// MySQLAdapter is a PostgreSQL DBMigrate adapter
+type MySQLAdapter struct {
 	db *sql.DB
 }
 
-// NewMySQL creates a new PostgresAdaptor
-func NewMySQL(db *sql.DB) (*MySQLAdaptor, error) {
-	a := &MySQLAdaptor{
+// NewMySQL creates a new PostgresAdapter
+func NewMySQL(db *sql.DB) (*MySQLAdapter, error) {
+	a := &MySQLAdapter{
 		db: db,
 	}
 	return a, a.createMigrationsTable()
 }
 
 // GetAppliedMigrationsOrderedAsc returns an ordered slice of string versions
 // of migrations that have been previously applied
-func (a *MySQLAdaptor) GetAppliedMigrationsOrderedAsc() ([]string, error) {
+func (a *MySQLAdapter) GetAppliedMigrationsOrderedAsc() ([]string, error) {
 	const query = "SELECT `version` FROM `dbmigrations` ORDER BY `version` ASC"
 	rows, err := a.db.Query(query)
 	if err != nil {
@@ -42,14 +42,14 @@ func (a *MySQLAdaptor) GetAppliedMigrationsOrderedAsc() ([]string, error) {
 
 // createMigrationsTable conditionally creates the migrations table if it
 // doesn't yet exist
-func (a *MySQLAdaptor) createMigrationsTable() error {
+func (a *MySQLAdapter) createMigrationsTable() error {
 	const query = "CREATE TABLE IF NOT EXISTS `dbmigrations`(`version` varchar NOT NULL PRIMARY KEY)"
 	_, err := a.db.Exec(query)
 	return err
 }
 
 // ApplyMigration applies the specified migration
-func (a *MySQLAdaptor) ApplyMigration(pair dbmigrate.MigrationPair) error {
+func (a *MySQLAdapter) ApplyMigration(pair dbmigrate.MigrationPair) error {
 	_, err := a.db.Exec(pair.ApplyBody)
 	if err != nil {
 		return err
@@ -59,11 +59,11 @@ func (a *MySQLAdaptor) ApplyMigration(pair dbmigrate.MigrationPair) error {
 }
 
 // RollbackMigration rolls back the specifified migration
-func (a *MySQLAdaptor) RollbackMigration(pair dbmigrate.MigrationPair) error {
+func (a *MySQLAdapter) RollbackMigration(pair dbmigrate.MigrationPair) error {
 	_, err := a.db.Exec(pair.RollbackBody)
 	if err != nil {
 		return err
 	}
 	_, err = a.db.Exec("DELETE FROM `dbmigrations` WHERE `version` = ?", pair.Version)
-	return nil
+	return err
 }

adaptor/postgres.go renamed to adapter/postgres.go

@@ -1,27 +1,27 @@
-package adaptor
+package adapter
 
 import (
 	"database/sql"
 
 	"bitbucket.org/braindev/dbmigrate"
 )
 
-// PostgresAdaptor is a PostgreSQL DBMigrate adaptor
-type PostgresAdaptor struct {
+// PostgresAdapter is a PostgreSQL DBMigrate adapter
+type PostgresAdapter struct {
 	db *sql.DB
 }
 
-// NewPostgres creates a new PostgresAdaptor
-func NewPostgres(db *sql.DB) (*PostgresAdaptor, error) {
-	a := &PostgresAdaptor{
+// NewPostgres creates a new PostgresAdapter
+func NewPostgres(db *sql.DB) (*PostgresAdapter, error) {
+	a := &PostgresAdapter{
 		db: db,
 	}
 	return a, a.createMigrationsTable()
 }
 
 // GetAppliedMigrationsOrderedAsc returns an ordered slice of string versions
 // of migrations that have been previously applied
-func (a *PostgresAdaptor) GetAppliedMigrationsOrderedAsc() ([]string, error) {
+func (a *PostgresAdapter) GetAppliedMigrationsOrderedAsc() ([]string, error) {
 	const query = `SELECT "version" FROM "dbmigrations" ORDER BY "version" ASC`
 	rows, err := a.db.Query(query)
 	if err != nil {
@@ -42,14 +42,14 @@ func (a *PostgresAdaptor) GetAppliedMigrationsOrderedAsc() ([]string, error) {
 
 // createMigrationsTable conditionally creates the migrations table if it
 // doesn't yet exist
-func (a *PostgresAdaptor) createMigrationsTable() error {
+func (a *PostgresAdapter) createMigrationsTable() error {
 	const query = `CREATE TABLE IF NOT EXISTS "dbmigrations"("version" varchar NOT NULL PRIMARY KEY)`
 	_, err := a.db.Exec(query)
 	return err
 }
 
 // ApplyMigration applies the specified migration
-func (a *PostgresAdaptor) ApplyMigration(pair dbmigrate.MigrationPair) error {
+func (a *PostgresAdapter) ApplyMigration(pair dbmigrate.MigrationPair) error {
 	_, err := a.db.Exec(pair.ApplyBody)
 	if err != nil {
 		return err
@@ -59,11 +59,11 @@ func (a *PostgresAdaptor) ApplyMigration(pair dbmigrate.MigrationPair) error {
 }
 
 // RollbackMigration rolls back the specifified migration
-func (a *PostgresAdaptor) RollbackMigration(pair dbmigrate.MigrationPair) error {
+func (a *PostgresAdapter) RollbackMigration(pair dbmigrate.MigrationPair) error {
 	_, err := a.db.Exec(pair.RollbackBody)
 	if err != nil {
 		return err
 	}
 	_, err = a.db.Exec(`DELETE FROM "dbmigrations" WHERE "version" = $1`, pair.Version)
-	return nil
+	return err
 }

adaptor/README.md

@@ -5,9 +5,9 @@ import (
 	"sort"
 )
 
-// VendorAdaptor is the set of functionality needed to implement a compatibility with a database
+// VendorAdapter is the set of functionality needed to implement a compatibility with a database
 // vendor
-type VendorAdaptor interface {
+type VendorAdapter interface {
 	GetAppliedMigrationsOrderedAsc() ([]string, error)
 	ApplyMigration(pair MigrationPair) error
 	RollbackMigration(pair MigrationPair) error
@@ -18,7 +18,7 @@ type Storage interface {
 	GetMigrationPairs() ([]MigrationPair, error)
 }
 
-// MigrationPair stores the a pair of apply/rollback migrations
+// MigrationPair stores a pair of apply/rollback migrations
 type MigrationPair struct {
 	Version      string
 	Name         string
@@ -31,7 +31,7 @@ type DBMigrate struct {
 	sortedMigrationPairs []MigrationPair
 	migrationPairs       map[string]MigrationPair
 	allVersions          []string
-	adaptor              VendorAdaptor
+	adapter              VendorAdapter
 	storage              Storage
 	verbose              bool // TODO
 }
@@ -43,9 +43,9 @@ func (a migrationPairs) Swap(i, j int)      { a[i], a[j] = a[j], a[i] }
 func (a migrationPairs) Less(i, j int) bool { return a[i].Version < a[j].Version }
 
 // New returns an initialized DBMigrate instance.
-func New(adaptor VendorAdaptor, storage Storage) (*DBMigrate, error) {
+func New(adapter VendorAdapter, storage Storage) (*DBMigrate, error) {
 	dbMigrate := DBMigrate{
-		adaptor: adaptor,
+		adapter: adapter,
 		storage: storage,
 	}
 	if migrationPairs, err := storage.GetMigrationPairs(); err == nil {
@@ -76,7 +76,7 @@ func (dbMigrate *DBMigrate) ApplyOne() error {
 }
 
 func (dbMigrate *DBMigrate) apply(all bool) error {
-	appliedVersions, err := dbMigrate.adaptor.GetAppliedMigrationsOrderedAsc()
+	appliedVersions, err := dbMigrate.adapter.GetAppliedMigrationsOrderedAsc()
 	if err != nil {
 		return err
 	}
@@ -93,7 +93,7 @@ func (dbMigrate *DBMigrate) apply(all bool) error {
 
 	for _, version := range versionsToApply {
 		fmt.Println("Applying migration", dbMigrate.migrationPairs[version].Name)
-		err = dbMigrate.adaptor.ApplyMigration(dbMigrate.migrationPairs[version])
+		err = dbMigrate.adapter.ApplyMigration(dbMigrate.migrationPairs[version])
 		if err != nil {
 			return err
 		}
@@ -107,14 +107,14 @@ func (dbMigrate *DBMigrate) apply(all bool) error {
 
 // RollbackLatest rolls back the latest applied migration
 func (dbMigrate *DBMigrate) RollbackLatest() error {
-	appliedVersions, err := dbMigrate.adaptor.GetAppliedMigrationsOrderedAsc()
+	appliedVersions, err := dbMigrate.adapter.GetAppliedMigrationsOrderedAsc()
 	if err != nil {
 		return err
 	}
 	for i := len(dbMigrate.sortedMigrationPairs) - 1; i >= 0; i-- {
 		if stringInSlice(dbMigrate.sortedMigrationPairs[i].Version, appliedVersions) {
 			fmt.Println("rolling back migration", dbMigrate.sortedMigrationPairs[i].Name)
-			err = dbMigrate.adaptor.RollbackMigration(dbMigrate.sortedMigrationPairs[i])
+			err = dbMigrate.adapter.RollbackMigration(dbMigrate.sortedMigrationPairs[i])
 			if err != nil {
 				return err
 			}