Saltar a contenido

0030. Stack y migraciones: asyncpg, ruff y .env.migrations

Estado: Aceptado Fecha: 2026-10-29 Autor: Duval Alcivar Módulo(s) afectado(s): svc-identidad (core_sigfa), stack, calidad y migraciones Modifica a: ADR 0002 Origen: ADR 0001 de implementación, ADR 0003 de implementación, ADR 0005 de implementación, ADR 0056 de implementación

Contexto

El ADR 0002 listaba el stack de diseño; la implementación descartó black, cambió el cliente HTTP de pruebas, hizo explícito asyncpg y separó el entorno de migraciones.

Decisión

  • Python >=3.14,<4.0 y Poetry con PEP 621 + [dependency-groups] (PEP 735); se versiona poetry.lock.
  • Driver PostgreSQL asyncpg (no psycopg2-binary); pydantic-settings para configuración.
  • Calidad: ruff check + ruff format y mypy strict; se elimina black. Cliente de pruebas httpx2 (no httpx).
  • .venv/ dentro del proyecto (virtualenvs.in-project = true).
  • Alembic tiene un entorno exclusivo con su propio archivo .env.migrations; el esquema de cada migración es el del servicio.

Alternativas descartadas

  • psycopg2-binary — bloquea el driver async que el servicio ya usa en runtime.
  • black + ruff — dos formateadores con reglas solapadas y modos de fallo distintos.
  • Un único .env para runtime y migraciones — mezcla credenciales de esquema y de aplicación en un mismo archivo.

Consecuencias

El proyecto queda con una sola herramienta de formato y lint; cualquier herramienta vieja que invoque black falla. Correr migraciones exige .env.migrations presente y con el esquema del servicio, un paso extra que debe estar en el runbook.


Se incorporó a este sitio el 2026-11-09. La fecha del ADR corresponde a la última decisión de implementación que resume, no a la fecha de publicación en este sitio.