Add status command to show the current state of a database wrt. migrations.

Previously we prevent the user migrating the database in either
direction if there were missing or out-of-order migrations. However,
going down should always be safe (assuming proper down scripts were
written) and often going down is the proper way to resolve out-of-order
migrations. Going down should always be done thoughtfully (it is highly
likely to lead to data loss), and really should not be done in a
production setting.

However, in a development environment, it is not unusual to get into
states where you have missing scripts. For example, if there are test
scripts that apply test data to a development environment on top of the
formal application schema, you may need to back out the test migrations
before creating new application migrations to avoid getting into an
"inconsistent state." Consider the following migrations:

- 1-initial-schema
- 2-add-feature-x
- T1-test-user-data

If you then add *3-add-feature-y*, you will  be in an inconsistent
state, as the expected ordering from db_migrate's point of view will be:

- 1-initial-schema
- 2-add-feature-x
- 3-add-feature-y
- T1-test-user-data

With the previous behavior db_migrate refuses to do anything and you
must manually back-out the test migrations before applying the new
migration. With the new behavior you can easily go down to back out the
test migrations automatically before going back up with the new migrations.

As an aside:

Another way to avoid this is to name test migrations in such a way that
they stay inline with the changes they are built on top of:

- 1-initial-schema
- 1.1-test-user-data
- 2-add-feature-x
- 2.1-feature-x-test-data

But sometimes the previous pattern is preferable, as it allows you to
have test migrations that evolve and match the "current state of test
data" rather than a developer needing to layer the contents of multiple
migrations to get a clear picture of the test data. This same issue
applies to non-test migrations, but db_migrate exists to solve the
use-case where you generally prefer to have traversible, immutable
layers that are used to manage production database schema migrations
downtown.

db_migrate.nimble

@@ -1,7 +1,7 @@
 # Package
 
 bin           = @["db_migrate"]
-version       = "0.3.0"
+version       = "0.4.1"
 author        = "Jonathan Bernard"
 description   = "Simple tool to handle database migrations."
 license       = "BSD"
@@ -9,4 +9,4 @@ srcDir        = "src/main/nim"
 
 # Dependencies
 
-requires: @["nim >= 1.4.0", "docopt >= 0.1.0"]
+requires: @["nim >= 2.0.0", "docopt >= 0.1.0", "db_connector"]

src/main/nim/db_migrate.nim

@@ -3,8 +3,10 @@
 ##
 ## Simple tool to manage database migrations.
 
-import algorithm, db_postgres, docopt, json, logging, os, sequtils, sets,
-  strutils, tables, times
+import std/[algorithm, json, logging, os, sequtils, sets, strutils, tables,
+            times]
+import db_connector/db_postgres
+import docopt
 
 type
   DbMigrateConfig* = object
@@ -89,6 +91,9 @@ proc diffMigrations*(
     run: seq[string],
     notRun, missing: seq[MigrationEntry] ] =
 
+  debug "diffMigrations: inspecting database and configured directories " &
+    "for migrations"
+
   # Query the database to find out what migrations have been run.
   var migrationsRun = initHashSet[string]()
 
@@ -98,7 +103,9 @@ proc diffMigrations*(
   # Inspect the filesystem to see what migrations are available.
   var migrationsAvailable = newTable[string, MigrationEntry]()
   for sqlDir in config.sqlDirs:
+    debug "Looking in " & sqlDir
     for filePath in walkFiles(joinPath(sqlDir, "*.sql")):
+      debug "Saw migration file: " & filePath
       var migrationName = filePath.extractFilename
       migrationName.removeSuffix("-up.sql")
       migrationName.removeSuffix("-down.sql")
@@ -125,11 +132,18 @@ proc diffMigrations*(
       missingMigrations.add(migrationsNotRun)
       migrationsNotRun = newSeq[MigrationEntry]()
 
-  return (available: migrationsAvailable,
+  result = (available: migrationsAvailable,
           run: toSeq(migrationsRun.items).sorted(system.cmp),
           notRun: migrationsNotRun,
           missing: missingMigrations)
 
+  debug "diffMigration: Results" &
+    "\n\tavailable: " & $toSeq(result[0].keys) &
+    "\n\trun:       " & $result[1] &
+    "\n\tnotRun:    " & $(result[2].mapIt(it.name)) &
+    "\n\tmissing:   " & $(result[3].mapIt(it.name))
+
+
 proc readStatements*(filename: string): seq[SqlQuery] =
   result = @[]
   var stmt: string = ""
@@ -157,7 +171,7 @@ proc up*(
 
   # Apply each of the migrations.
   for migration in toRun:
-    info migration.name
+    info "Applying up script for " & migration.name
 
     if not migration.upPath.fileExists:
       pgConn.rollbackWithErr "Can not find UP file for " & migration.name &
@@ -188,7 +202,7 @@ proc down*(
   pgConn.exec(sql"BEGIN")
 
   for migration in migrationsToDown:
-    info migration.name
+    info "Applying down script for " & migration.name
 
     if not migration.downPath.fileExists:
       pgConn.rollbackWithErr "Can not find DOWN file for " & migration.name &
@@ -215,6 +229,7 @@ Usage:
   db_migrate [options] up [<count>]
   db_migrate [options] down [<count>]
   db_migrate [options] init <schema-name>
+  db_migrate [options] status
   db_migrate (-V | --version)
   db_migrate (-h | --help)
 
@@ -235,7 +250,7 @@ Options:
 """
 
   # Parse arguments
-  let args = docopt(doc, version = "db-migrate (Nim) 0.3.0\nhttps://git.jdb-software.com/jdb/db-migrate")
+  let args = docopt(doc, version = "db-migrate (Nim) 0.4.1\nhttps://git.jdb-software.com/jdb/db-migrate")
 
   let exitErr = proc(msg: string): void =
     fatal("db_migrate: " & msg)
@@ -293,12 +308,12 @@ Options:
 
     let (available, run, notRun, missing) = diffMigrations(pgConn, config)
 
-    # Make sure we have no gaps (database is in an unknown state)
-    if missing.len > 0:
-      exitErr "Database is in an inconsistent state. Migrations have been " &
-        "run that are not sequential."
-
     if args["up"]:
+      # Make sure we have no gaps (database is in an unknown state)
+      if missing.len > 0:
+        exitErr "Database is in an inconsistent state. Migrations have been " &
+          "run that are not sequential."
+
       try:
         let count = if args["<count>"]: parseInt($args["<count>"]) else: high(int)
         let toRun = if count < notRun.len: notRun[0..<count] else: notRun
@@ -317,9 +332,29 @@ Options:
       except DbError:
         exitErr "Unable to migrate database: " & getCurrentExceptionMsg()
 
+    elif args["status"]:
+
+      info "Database Migration Status" &
+        "\n\nSQL Migration Folders: " & join(config.sqlDirs.mapIt("\n  " & it), "") &
+        "\n\nMigrations: " &
+        "\n  available: " & join(
+          toSeq(available.keys)
+            .sorted(system.cmp)
+            .mapIt("\n    " & it),
+          "") &
+        "\n  run:       " & join(run.mapIt("\n    " & it), "") &
+        "\n  notRun:    " & join(notRun.mapIt("\n    " & it.name), "") &
+        "\n  missing:   " & join(missing.mapIt("\n    " & it.name), "") &
+        "\n"
+
     elif args["init"]: discard
 
     let newResults = diffMigrations(pgConn, config)
+
+    if newResults.missing.len > 0:
+      exitErr "Database is in an inconsistent state. Migrations have been " &
+        "run that are not sequential."
+
     if newResults.notRun.len > 0:
       info "Database is behind by " & $(newResults.notRun.len) & " migrations."
     else: info "Database is up to date."