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-if-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/changelog.rst

@@ -7,6 +7,15 @@ Changelog
     :version: 1.17.1
     :include_notes_from: unreleased
 
+    .. 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.
+
 .. changelog::
     :version: 1.17.0
     :released: October 11, 2025

tests/test_command.py

@@ -10,6 +10,7 @@
 import shutil
 from typing import cast
 
+import pytest
 from sqlalchemy import exc as sqla_exc
 from sqlalchemy import text
 from sqlalchemy import VARCHAR
@@ -345,6 +346,35 @@ def test_heads_upg(self):
         with self._assert_lines(["a2", "b3"]):
             command.current(self.cfg)
 
+    def test_check_if_head_success(self):
+        """
+        "--check-if-head" 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)
+
+    @pytest.mark.parametrize(
+        "revs", [("a2",), ("a3",), ("b3",), ("a2", "b3"), ("a3", "b2")]
+    )
+    def test_check_if_head_fail(self, revs):
+        """
+        "--check-if-head" 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):