0012. greenlet mediante el extra sqlalchemy[asyncio]¶
Estado: Aceptado Fecha: 2026-10-05 Autor: David Garcia Módulo(s) afectado(s): pyproject.toml, poetry.lock
Contexto¶
SQLAlchemy asíncrono (ADR 0004) corre sobre greenlet: AsyncSession y
AsyncEngine lo usan para ejecutar el ORM, que es síncrono, dentro del event
loop. Sin greenlet, la primera operación asíncrona falla con
ValueError: the greenlet library is required to use this function.
En SQLAlchemy 2.0 (la que usan crm-svc-clientes y core-svc-identidad,
2.0.54), greenlet es una dependencia normal, aunque condicionada a la
arquitectura: se instala sola en x86_64, amd64, aarch64, ppc64le y
win32. Por eso sqlalchemy a secas funcionaba en esos servicios.
En SQLAlchemy 2.1 (la que resuelve este servicio, 2.1.3, dentro del rango
>=2.0.54,<3.0.0), greenlet dejó de ser una dependencia por defecto: sólo
se instala con el extra asyncio (greenlet>=1; extra == "asyncio"). Con
sqlalchemy a secas el servicio se instala sin error y falla en el primer
acceso a la base.
Decisión¶
- Se declara
sqlalchemy[asyncio]en las dependencias de ejecución, nosqlalchemya secas. - greenlet no se declara como dependencia directa: llega por el extra, y SQLAlchemy fija la versión que necesita.
Alternativas descartadas¶
- Declarar
greenletdirectamente — duplica una restricción que ya publica SQLAlchemy, y elpyproject.tomlno dice por qué está. - Fijar
sqlalchemy <2.1— deja el servicio atado a una versión anterior sólo por una dependencia de instalación. - Confiar en que greenlet llegue por otra dependencia — ninguna lo garantiza, y en una arquitectura que no está en la lista de 2.0 tampoco llegaba.
Consecuencias¶
- La instalación funciona en cualquier arquitectura, no sólo en la lista que usaba 2.0.
- Si
crm-svc-clientesocore-svc-identidadsuben a SQLAlchemy 2.1 sin agregar el extra, dejarán de funcionar al primer acceso a la base: hay que avisarles.
Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.