Bug: BatchOperations.create_index has incorrect signature

[Annonymus-v02]

Describe the bug

The signature (according to the docs and the API in the generated section of base.py) of BatchOperations.create_index is

def create_index(self, index_name: str, columns: list[str], **kw: Any) -> None

The signature of Operations.create_index is

def create_index(self, index_name: str | None, table_name: str, columns: Sequence[str | TextClause | ColumnElement[Any]], *, schema: str | None = None, unique: bool = False, if_not_exists: bool | None = None, **kw: Any) -> None

Having taken a very brief look at where these functions come from I believe the signatures must be the same (aside from the missing table_name) as they are backed by the same implementation, but my (possibly — and even somewhat likely — incorrect) beliefs aside, alembic revision --autogenerate does not respect BatchOperations' version of the signature, generating code like

with op.batch_alter_table('table_name', schema=None) as batch_op:
    batch_op.create_index(batch_op.f('idx_name'), [sa.literal_column('"col1_name" DESC'), sa.literal_column('"col2_name" DESC')], unique=False)

which is not valid for BatchOperations' version, which declares columns to be a list[str].
Given that this code actually runs (generates a CREATE INDEX statement using alembic upgrade --sql), I believe this is a bug in the signature, not in --autogenerate's handling of batch operations.

create_index is the function that triggered our type checker, making us aware of this issue. I have not verified whether it is the only affected function, or there are other mismatches between the signature in Operations and BatchOperations.

Expected behavior

The signature of BatchOperations.create_index should reflect the parameters it actually expects, or alternatively, --autogenerate should not generate code that violates the current signature.

To Reproduce

Run alembic upgrade b23c5a130bc8 --sql with the following migration and observe that no error occurs and the resulting sql file contains a CREATE INDEX statement.
Run your preferred type checker and observe the type violation reported on line 16, or read the documentation and notice that it defines the columns parameter as a list[str], which is not the case in the code below.

from typing import Sequence, Union

from alembic import op
import sqlalchemy as sa

# revision identifiers, used by Alembic.
revision: str = 'b23c5a130bc8'
down_revision: Union[str, Sequence[str], None] = None
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None


def upgrade(engine_name: str) -> None:
    """Upgrade schema."""
    with op.batch_alter_table('prm_contacts', schema=None) as batch_op:
        batch_op.create_index(batch_op.f('idx_test_idx_delete_me'), [sa.literal_column('"NAME" DESC'), sa.literal_column('"PHONE" DESC')], unique=False)


def downgrade(engine_name: str) -> None:
    """Downgrade schema."""
    with op.batch_alter_table('prm_contacts', schema=None) as batch_op:
        batch_op.drop_index(batch_op.f('idx_test_idx_delete_me'))

Error

In this example using ty

error[invalid-argument-type]: Argument to bound method `BatchOperations.create_index` is incorrect
  --> alembic/versions/2026_08_11-b23c5a130bc8_test_revision.py:16:69
   |
16 | …dx_test_idx_delete_me'), [sa.literal_column('"NAME" DESC'), sa.literal_column('"PHONE" DESC')], unique=False)
   |                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Expected `list[str]`, found `list[str | ColumnClause[Unknown]]`
info: element `ColumnClause[Unknown]` of union `str | ColumnClause[Unknown]` is not assignable to `str`
info: Method defined here
    --> .venv/lib/python3.14/site-packages/alembic/operations/base.py:1871:13
     |
1871 |         def create_index(
     |             ^^^^^^^^^^^^
1872 |             self, index_name: str, columns: List[str], **kw: Any
     |                                    ------------------ Parameter declared here

Versions

• OS: MacOS Tahoe 26.5.1
• Python: 3.14.6
• Alembic: 1.19.1 — also observed on version 1.18.4
• SQLAlchemy: 2.0.46
• Database: irrelevant — behavior can be observed running offline (--sql)¹, but we originally discovered it on a migration for an oracle DB
• DBAPI: not sure what this is asking for (db driver version?), but I believe it is irrelevant, as above.

Additional context

I am writing this bug report as a discussion since the reporting bugs guidance asks to do so instead of opening an issue, but none of the categories of discussions look right... I chose the one that seems least inappropriate and marked the actual nature in the title. Please let me know if that was not the right choice.

Footnotes

1. or not even running at all just looking at the --autogenerated code and the documentation. ↩

[CaselIT]

Hi.

it seems so. Thanks for reporting.

The signature to update should be this one

alembic/alembic/operations/ops.py

Line 1007 in dac4723

def batch_create_index(

then the tools/write_pyi script should be re-run

I'll create an issue and apply the correct label to open PRs