Saltar a contenido

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, no sqlalchemy a secas.
  • greenlet no se declara como dependencia directa: llega por el extra, y SQLAlchemy fija la versión que necesita.

Alternativas descartadas

  • Declarar greenlet directamente — duplica una restricción que ya publica SQLAlchemy, y el pyproject.toml no 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-clientes o core-svc-identidad suben 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.