Add "--check-heads" option to "current" command

alembic/command.py

@@ -681,11 +681,16 @@ def branches(config: Config, verbose: bool = False) -> None:
             )
 
 
-def current(config: Config, verbose: bool = False) -> None:
+def current(
+    config: Config, check_heads: bool = False, verbose: bool = False
+) -> None:
     """Display the current revision for a database.
 
     :param config: a :class:`.Config` instance.
 
+    :param check_heads: Check if all head revisions are applied to the
+        database.  Exit with an error if this is not the case.
+
     :param verbose: output in verbose mode.
 
     """
@@ -698,6 +703,10 @@ def display_version(rev, context):
                 "Current revision(s) for %s:",
                 util.obfuscate_url_pw(context.connection.engine.url),
             )
+        if check_heads and (
+            set(context.get_current_heads()) != set(script.get_heads())
+        ):
+            raise util.CommandError("Database is not on all head revisions")
         for rev in script.get_all_current(rev):
             config.print_stdout(rev.cmd_format(verbose))
 

alembic/config.py

@@ -808,6 +808,17 @@ def __init__(self, prog: Optional[str] = None) -> None:
                 "environment and version locations",
             ),
         ),
+        "check_heads": (
+            "-c",
+            "--check-heads",
+            dict(
+                action="store_true",
+                help=(
+                    "Check if all head revisions are applied to the database. "
+                    "Exit with an error code if this is not the case."
+                ),
+            ),
+        ),
     }
     _POSITIONAL_OPTS = {
         "directory": dict(help="location of scripts directory"),

docs/build/unreleased/1705.rst

@@ -0,0 +1,8 @@
+.. change::
+   :tags: usecase, commands
+   :tickets: 1705
+
+   Added ``--check-heads`` option to ``current`` command which
+   checks if all head revisions are applied to the database.
+   The command exists with a non-zero exit code if this is not the
+   case.

tests/test_command.py

@@ -345,6 +345,40 @@ def test_heads_upg(self):
         with self._assert_lines(["a2", "b3"]):
             command.current(self.cfg)
 
+    def test_check_heads_success(self):
+        """
+        "--check-heads" succeeds if all head revisions are applied.
+        """
+        command.stamp(self.cfg, ())
+        command.stamp(self.cfg, (self.a3.revision, self.b3.revision))
+        with self._assert_lines(["a3", "b3"]):
+            command.current(self.cfg, check_heads=True)
+
+    @testing.combinations(
+        ["a2"],
+        ["a3"],
+        ["b3"],
+        ["a2", "b3"],
+        ["a3", "b2"],
+        argnames="revs",
+    )
+    def test_check_heads_fail(self, revs):
+        """
+        "--check-heads" succeeds if all head revisions are applied.
+        """
+        command.stamp(self.cfg, ())
+        command.stamp(
+            self.cfg, tuple(getattr(self, rev).revision for rev in revs)
+        )
+        assert_raises_message(
+            util.CommandError,
+            "Database is not on all head revisions",
+            command.current,
+            self.cfg,
+            check_heads=True,
+        )
+        command.stamp(self.cfg, ())
+
 
 class RevisionTest(TestBase):
     def setUp(self):