{"record":{"id":"e0413b1231c6c902","repo":"sqlalchemy/alembic","slug":"sqlalchemy-1-4-18-required","errorCode":null,"errorMessage":"SQLAlchemy 1.4.18+ required","messagePattern":"SQLAlchemy 1\\.4\\.18\\+ required","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"alembic/operations/base.py","lineNumber":574,"sourceCode":"        This method allows calling async functions from within the\n        synchronous ``upgrade()`` or ``downgrade()`` alembic migration\n        method.\n\n        The async connection passed to the callable shares the same\n        transaction as the connection running in the migration context.\n\n        Any additional arg or kw_arg passed to this function are passed\n        to the provided async function.\n\n        .. versionadded: 1.11\n\n        .. note::\n\n            This method can be called only when alembic is called using\n            an async dialect.\n        \"\"\"\n        if not sqla_compat.sqla_14_18:\n            raise NotImplementedError(\"SQLAlchemy 1.4.18+ required\")\n        sync_conn = self.get_bind()\n        if sync_conn is None:\n            raise NotImplementedError(\"Cannot call run_async in SQL mode\")\n        if not sync_conn.dialect.is_async:\n            raise ValueError(\"Cannot call run_async with a sync engine\")\n        from sqlalchemy.ext.asyncio import AsyncConnection\n        from sqlalchemy.util import await_only\n\n        async_conn = AsyncConnection._retrieve_proxy_for_target(sync_conn)\n        return await_only(async_function(async_conn, *args, **kw_args))\n\n\nclass Operations(AbstractOperations):\n    \"\"\"Define high level migration operations.\n\n    Each operation corresponds to some schema migration operation,\n    executed against a particular :class:`.MigrationContext`\n    which in turn represents connectivity to a database,","sourceCodeStart":556,"sourceCodeEnd":592,"githubUrl":"https://github.com/sqlalchemy/alembic/blob/5551b5d35f985c99cb8f1af2b3c526b050e4c059/alembic/operations/base.py#L556-L592","documentation":"Operations.run_async raises NotImplementedError when SQLAlchemy is older than 1.4.18. run_async relies on AsyncConnection._retrieve_proxy_for_target and await_only, both introduced in SQLAlchemy 1.4.18, so earlier versions cannot support calling async functions from sync migration code.","triggerScenarios":"Calling op.run_async(some_async_fn) in a migration while the installed SQLAlchemy is < 1.4.18 (sqla_compat.sqla_14_18 is False).","commonSituations":"Pinned older SQLAlchemy in a legacy project; virtualenv with a downgraded SQLAlchemy; fresh checkout in an environment with an old requirements lock.","solutions":["Upgrade SQLAlchemy: pip install 'SQLAlchemy>=1.4.18' (preferably the latest 2.x).","Pin SQLAlchemy>=1.4.18 in requirements.txt / pyproject.toml to prevent regressions.","If upgrade is impossible, avoid run_async and perform the work with a synchronous connection instead."],"exampleFix":"# before: pinned old SQLA\n# requirements.txt\nSQLAlchemy==1.3.24\n\n# after\nSQLAlchemy>=1.4.18","handlingStrategy":"validation","validationCode":"import sqlalchemy\nfrom alembic.util import sqla_compat\n\ndef can_run_async() -> bool:\n    return bool(sqla_compat.sqla_14_18)\n\nif not can_run_async():\n    raise RuntimeError(f'SQLAlchemy>=1.4.18 required, got {sqlalchemy.__version__}')","typeGuard":"def sqlalchemy_supports_run_async() -> bool:\n    import sqlalchemy\n    return tuple(int(x) for x in sqlalchemy.__version__.split('.')[:3]) >= (1, 4, 18)","tryCatchPattern":null,"preventionTips":["Pin SQLAlchemy>=1.4.18 in your dependency manifest.","Check sqlalchemy.__version__ at app startup when async migrations are used.","Lock the environment with a reproducible requirements file."],"tags":["run-async","version","sqlalchemy","async"],"backgroundTag":null,"analyzedSha":"5551b5d35f985c99cb8f1af2b3c526b050e4c059","analyzedAt":"2026-08-11T01:38:46.612Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}