Add new ensure_version command

Add a new command ``alembic ensure_version``, which will ensure that the
Alembic version table is present in the target database, but does not
alter its contents.  Pull request courtesy Kai Mueller.

Fixes: #964
Closes: #965
Pull-request: https://github.com/sqlalchemy/alembic/pull/965
Pull-request-sha: a85d2ac048c666126e583fbda482eeabd9c58c53

Change-Id: Ia39d43287634915537725e779dba7ac34f2946e4

diff --git a/alembic/command.py b/alembic/command.py
index 1e794602b4c7711bb80f7b3af1ce22b0ba9cc8c0..c1117244b9b95465a87c14759757eda5fbbd6f1f 100644 (file)
--- a/alembic/command.py
+++ b/alembic/command.py
@@ -643,3 +643,29 @@ def edit(config: "Config", rev: str) -> None:
             )
         for sc in revs:
             util.open_in_editor(sc.path)
+
+
+def ensure_version(config: "Config", sql: bool = False) -> None:
+    """Create the alembic version table if it doesn't exist already .
+
+    :param config: a :class:`.Config` instance.
+
+    :param sql: use ``--sql`` mode
+
+     .. versionadded:: 1.7.6
+
+    """
+
+    script = ScriptDirectory.from_config(config)
+
+    def do_ensure_version(rev, context):
+        context._ensure_version_table()
+        return []
+
+    with EnvironmentContext(
+        config,
+        script,
+        fn=do_ensure_version,
+        as_sql=sql,
+    ):
+        script.run_env()

diff --git a/docs/build/unreleased/964.rst b/docs/build/unreleased/964.rst
new file mode 100644 (file)
index 0000000..9cf2321
--- /dev/null
+++ b/docs/build/unreleased/964.rst
@@ -0,0 +1,7 @@
+.. change::
+    :tags: usecase, commands
+    :tickets: 964
+
+    Add a new command ``alembic ensure_version``, which will ensure that the
+    Alembic version table is present in the target database, but does not
+    alter its contents.  Pull request courtesy Kai Mueller.

diff --git a/tests/test_command.py b/tests/test_command.py
index 98477eec6c1857baa6c8aa363aaff984d0e22392..680a7fb638303922b772a0b96214727339182624 100644 (file)
--- a/tests/test_command.py
+++ b/tests/test_command.py
@@ -5,9 +5,11 @@ from io import StringIO
 from io import TextIOWrapper
 import os
 import re
+from typing import cast
 
 from sqlalchemy import exc as sqla_exc
 from sqlalchemy import text
+from sqlalchemy.engine import Engine
 
 from alembic import __version__
 from alembic import command
@@ -1185,3 +1187,36 @@ class CommandLineTest(TestBase):
 
         is_true("test_prog" in str(buf.getvalue()))
         is_true(__version__ in str(buf.getvalue()))
+
+
+class EnureVersionTest(TestBase):
+    @classmethod
+    def setup_class(cls):
+        cls.bind = _sqlite_file_db()
+        cls.env = staging_env()
+        cls.cfg = _sqlite_testing_config()
+
+    @classmethod
+    def teardown_class(cls):
+        clear_staging_env()
+
+    def test_ensure_version(self):
+        command.ensure_version(self.cfg)
+
+        engine = cast(Engine, self.bind)
+        with engine.connect() as conn:
+            is_true(_connectable_has_table(conn, "alembic_version", None))
+
+    def test_ensure_version_called_twice(self):
+        command.ensure_version(self.cfg)
+        command.ensure_version(self.cfg)
+
+        engine = cast(Engine, self.bind)
+        with engine.connect() as conn:
+            is_true(_connectable_has_table(conn, "alembic_version", None))
+
+    def test_sql_ensure_version(self):
+        with capture_context_buffer() as buf:
+            command.ensure_version(self.cfg, sql=True)
+
+        is_true(buf.getvalue().startswith("CREATE TABLE alembic_version"))