add Migrate.Run

migrate.go

@@ -170,7 +170,7 @@ func newCommon() *Migrate {
 }
 
 // Close closes the the source and the database.
-func (m *Migrate) Close() (sourceErr error, databaseErr error) {
+func (m *Migrate) Close() (source error, database error) {
 	databaseSrvClose := make(chan error)
 	sourceSrvClose := make(chan error)
 
@@ -276,6 +276,38 @@ func (m *Migrate) Drop() error {
 	return m.unlock()
 }
 
+// Run runs any migration provided by you against the database.
+// It does not check any currently active version in database.
+// Usually you don't need this function at all. Use Migrate,
+// Steps, Up or Down instead.
+func (m *Migrate) Run(migration ...*Migration) error {
+	if len(migration) == 0 {
+		return ErrNoChange
+	}
+
+	if err := m.lock(); err != nil {
+		return err
+	}
+
+	ret := make(chan interface{}, m.PrefetchMigrations)
+
+	go func() {
+		defer close(ret)
+		for _, migr := range migration {
+			if m.PrefetchMigrations > 0 && migr.Body != nil {
+				m.logVerbosePrintf("Start buffering %v\n", migr.StringLong())
+			} else {
+				m.logVerbosePrintf("Scheduled %v\n", migr.StringLong())
+			}
+
+			ret <- migr
+			go migr.Buffer()
+		}
+	}()
+
+	return m.unlockErr(m.runMigrations(ret))
+}
+
 // Version returns the currently active migration version.
 // If no migration has been applied, yet, it will return ErrNilVersion.
 func (m *Migrate) Version() (uint, error) {

migrate_test.go

@@ -424,6 +424,28 @@ func TestVersion(t *testing.T) {
 	}
 }
 
+func TestRun(t *testing.T) {
+	m, _ := New("stub://", "stub://")
+
+	mx, err := NewMigration(nil, "", 1, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if err := m.Run(mx); err != nil {
+		t.Fatal(err)
+	}
+
+	v, err := m.Version()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if v != 2 {
+		t.Errorf("expected version 2, got %v", v)
+	}
+}
+
 func TestRead(t *testing.T) {
 	m, _ := New("stub://", "stub://")
 	m.sourceDrv.(*sStub.Stub).Migrations = sourceStubMigrations

migration.go

@@ -24,6 +24,7 @@ type Migration struct {
 
 	// TargetVersion is the migration version after this migration
 	// has been applied to the database.
+	// Can be -1, implying that this is a NilVersion.
 	TargetVersion int
 
 	// Body holds an io.ReadCloser to the source.
@@ -58,6 +59,7 @@ type Migration struct {
 // NewMigration returns a new Migration and sets the body, identifier,
 // version and targetVersion. Body can be nil, which turns this migration
 // into a "NilMigration". If no identifier is provided, it will default to "<empty>".
+// targetVersion can be -1, implying it is a NilVersion.
 //
 // What is a NilMigration?
 // Usually each migration version coming from source is expected to have an
@@ -66,7 +68,13 @@ type Migration struct {
 // the user wants to migrate up to a version that doesn't have the actual Up
 // migration, in that case we still want to apply the version, but with an empty
 // body. We are calling that a NilMigration, a migration with an empty body.
-func NewMigration(body io.ReadCloser, identifier string, version uint, targetVersion int) (*Migration, error) {
+//
+// What is a NilVersion?
+// NilVersion is a const(-1). When running down migrations and we are at the
+// last down migration, there is no next down migration, the targetVersion should
+// be nil. Nil in this case is represented by -1 (because type int).
+func NewMigration(body io.ReadCloser, identifier string,
+	version uint, targetVersion int) (*Migration, error) {
 	tnow := time.Now()
 	m := &Migration{
 		Identifier:    identifier,

migration_test.go

@@ -37,3 +37,20 @@ func ExampleNewMigration_nilMigration() {
 	// Output:
 	// 1486686016/u <empty>
 }
+
+func ExampleNewMigration_nilVersion() {
+	// Create a dummy migration body, this is coming from the source usually.
+	body := ioutil.NopCloser(strings.NewReader("dumy migration that deletes users table"))
+
+	// Create a new Migration that represents version 1486686016.
+	// This is the last available down migration, so the migration version
+	// will be -1, meaning NilVersion once this migration ran.
+	migr, err := NewMigration(body, "drop_users_table", 1486686016, -1)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Print(migr.StringLong())
+	// Output:
+	// 1486686016/d drop_users_table
+}