feat: add check command to check pending migrations

The check command checks for pending migrations and returns an error if
there are any.

This allows a user to use it in a script where the user doesn't want to
run the migrations but still ensure that there are none pending before
continuing.

For example, when using a Kubernetes Job to perform migrations while a
Deployment runs the service itself, a user may want to prevent the
Deployment from starting fully before the migrations have completed.

Author: taisph

internal/cli/commands.go

@@ -18,6 +18,7 @@ var (
 	errInvalidSequenceWidth     = errors.New("Digits must be positive")
 	errIncompatibleSeqAndFormat = errors.New("The seq and format options are mutually exclusive")
 	errInvalidTimeFormat        = errors.New("Time format may not be empty")
+	errPendingMigrations        = errors.New("There are pending migrations")
 )
 
 func nextSeqVersion(matches []string, seqDigits int) (string, error) {
@@ -222,6 +223,20 @@ func versionCmd(m *migrate.Migrate) error {
 	return nil
 }
 
+func checkCmd(m *migrate.Migrate) error {
+	pending, err := m.Check()
+	if err != nil {
+		return err
+	}
+
+	log.Printf("%v pending migration(s)\n", pending)
+	if pending > 0 {
+		return errPendingMigrations
+	}
+
+	return nil
+}
+
 // numDownMigrationsFromArgs returns an int for number of migrations to apply
 // and a bool indicating if we need a confirm before applying
 func numDownMigrationsFromArgs(applyAll bool, args []string) (int, bool, error) {

internal/cli/main.go

@@ -92,6 +92,7 @@ Commands:
   %s
   %s
   version      Print current migration version
+  check        Check if database has pending migrations
 
 Source drivers: `+strings.Join(source.List(), ", ")+`
 Database drivers: `+strings.Join(database.List(), ", ")+"\n", createUsage, gotoUsage, upUsage, downUsage, dropUsage, forceUsage)
@@ -371,6 +372,15 @@ Database drivers: `+strings.Join(database.List(), ", ")+"\n", createUsage, gotoU
 			log.fatalErr(err)
 		}
 
+	case "check":
+		if migraterErr != nil {
+			log.fatalErr(migraterErr)
+		}
+
+		if err := checkCmd(migrater); err != nil {
+			log.fatalErr(err)
+		}
+
 	default:
 		printUsageAndExit()
 	}

migrate.go

@@ -395,6 +395,44 @@ func (m *Migrate) Version() (version uint, dirty bool, err error) {
 	return suint(v), d, nil
 }
 
+// Check returns number of pending migrations.
+func (m *Migrate) Check() (pending int, err error) {
+	// Disable prefetch as we'll only be checking and not applying migrations.
+	m.PrefetchMigrations = 0
+
+	curVersion, dirty, err := m.databaseDrv.Version()
+	if err != nil {
+		return 0, err
+	}
+
+	if dirty {
+		return 0, ErrDirty{curVersion}
+	}
+
+	pending = 0
+
+	ret := make(chan interface{}, m.PrefetchMigrations)
+	go m.readUp(curVersion, -1, ret)
+
+	for r := range ret {
+		if m.stop() {
+			break
+		}
+
+		switch r := r.(type) {
+		case error:
+			if r != ErrNoChange {
+				return 0, r
+			}
+
+		case *Migration:
+			pending += 1
+		}
+	}
+
+	return pending, nil
+}
+
 // read reads either up or down migrations from source `from` to `to`.
 // Each migration is then written to the ret channel.
 // If an error occurs during reading, that error is written to the ret channel, too.

migrate_test.go

@@ -945,6 +945,43 @@ func TestVersion(t *testing.T) {
 	}
 }
 
+func TestCheck(t *testing.T) {
+	m, _ := New("stub://", "stub://")
+	m.sourceDrv.(*sStub.Stub).Migrations = sourceStubMigrations
+
+	pending, err := m.Check()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if pending != 5 {
+		t.Fatalf("expected 5 pending, got %v", pending)
+	}
+
+	if err := m.Steps(3); err != nil {
+		t.Fatal(err)
+	}
+
+	pending, err = m.Check()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if pending != 2 {
+		t.Fatalf("expected 2 pending, got %v", pending)
+	}
+
+	if err := m.Up(); err != nil {
+		t.Fatal(err)
+	}
+
+	pending, err = m.Check()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if pending != 0 {
+		t.Fatalf("expected 0 pending, got %v", pending)
+	}
+}
+
 func TestRun(t *testing.T) {
 	m, _ := New("stub://", "stub://")