Provide a better error message when trying to downgrade a revision that is required by another

[CaselIT]

Describe the bug

Alembic crashed with an assertion error

Expected behavior

A proper error should be raised

To Reproduce
Please try to provide a Minimal, Complete, and Verifiable example, with the migration script and/or the SQLAlchemy tables or models involved.
See also Reporting Bugs on the website.

Let's save we have 3 migration in a default env using sqlite configured so this way:

base -> first  \
                 third
base -> second /

Files content

"""first

Revision ID: first
Revises: 
Create Date: 2022-05-02 20:07:26.041601
"""
# revision identifiers, used by Alembic.
revision = 'first'
down_revision = None
branch_labels = None
depends_on = None

def upgrade():
    pass

def downgrade():
    pass

"""second

Revision ID: second
Revises: 
Create Date: 2022-05-02 20:07:37.457352
"""
# revision identifiers, used by Alembic.
revision = 'second'
down_revision = None
branch_labels = None
depends_on = None

def upgrade():
    pass

def downgrade():
    pass

"""third

Revision ID: 31dc94ecbcb5
Revises: 1caadb4b5052
Create Date: 2022-05-02 20:07:54.298706
"""
# revision identifiers, used by Alembic.
revision = "third"
down_revision = "first"
branch_labels = None
depends_on = ("second",)

def upgrade():
    pass

def downgrade():
    pass

**Error**

Running

alembic upgrade heads
alembic downgrade second@-1

errors with

Traceback (most recent call last):
  File "venv\lib\runpy.py", line 194, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "venv\lib\runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "venv\Scripts\alembic.exe\__main__.py", line 7, in <module>
  File "venv\lib\site-packages\alembic\config.py", line 588, in main
    CommandLine(prog=prog).main(argv=argv)
  File "venv\lib\site-packages\alembic\config.py", line 582, in main
    self.run_cmd(cfg, options)
  File "venv\lib\site-packages\alembic\config.py", line 559, in run_cmd
    fn(
  File "venv\lib\site-packages\alembic\command.py", line 366, in downgrade
    script.run_env()
  File "venv\lib\site-packages\alembic\script\base.py", line 563, in run_env
    util.load_python_file(self.dir, "env.py")
  File "venv\lib\site-packages\alembic\util\pyfiles.py", line 92, in load_python_file
    module = load_module_py(module_id, path)
  File "venv\lib\site-packages\alembic\util\pyfiles.py", line 108, in load_module_py
    spec.loader.exec_module(module)  # type: ignore
  File "<frozen importlib._bootstrap_external>", line 843, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "vv\env.py", line 77, in <module>
    run_migrations_online()
  File "vv\env.py", line 71, in run_migrations_online
    context.run_migrations()
  File "<string>", line 8, in run_migrations
  File "venv\lib\site-packages\alembic\runtime\environment.py", line 851, in run_migrations
    self.get_context().run_migrations(**kw)
  File "venv\lib\site-packages\alembic\runtime\migration.py", line 608, in run_migrations
    for step in self._migrations_fn(heads, self):
  File "venv\lib\site-packages\alembic\command.py", line 355, in downgrade
    return script._downgrade_revs(revision, rev)
  File "venv\lib\site-packages\alembic\script\base.py", line 453, in _downgrade_revs
    return [
  File "venv\lib\site-packages\alembic\script\base.py", line 453, in <listcomp>
    return [
  File "venv\lib\site-packages\alembic\script\revision.py", line 789, in iterate_revisions
    revisions, heads = fn(
  File "venv\lib\site-packages\alembic\script\revision.py", line 1288, in _collect_downgrade_revisions
    branch_label, target_revision = self._parse_downgrade_target(
  File "venv\lib\site-packages\alembic\script\revision.py", line 1122, in _parse_downgrade_target
    assert len(symbol_list) == 1
AssertionError

The error is correct, since third depends on second, it's just that a proper raise should be used there

Versions.

• OS: any
• Python: any
• Alembic: 1.7.6
• SQLAlchemy: any
• Database: any
• DBAPI: any

Additional context

Have a nice day!

[CaselIT]

Actually if I add a fourth revision on top of second then run alembic downgrade fourth@-2 it removes 3 revision, including third.

So I think there is a but here, caused by the fact that second is considered and "effective head", not an head

[sqla-tester]

CaselIT has proposed a fix for this issue in the main branch:

Fix downgrade with effective head https://gerrit.sqlalchemy.org/c/sqlalchemy/alembic/+/3820

[zzzeek]

so when I reproduce with the gerrit, it doesnt raise an error. it puts me on "first" . i dont even know what the above command should do anyway, it's fine for me.