postgresqlsqlalchemyasync

SQLAlchemy 2.0 en modo async es el ORM principal para todas las operaciones de base de datos. Se integra nativamente con FastAPI y asyncio, garantizando que las escrituras de auditoría no bloquean el pipeline KYC.

When to use

Usar para todas las operaciones CRUD sobre PostgreSQL: insertar sesiones de auditoría, consultar listas negras, registrar decisiones, gestionar la cola de revisión manual.

Instructions

1. Instalar: pip install sqlalchemy[asyncio] asyncpg alembic
2. Configurar engine async en backend/db/engine.py:

``python from sqlalchemy.ext.asyncio import createasyncengine, AsyncSession from sqlalchemy.orm import sessionmaker engine = createasyncengine("postgresql+asyncpg://user:pass@pgbouncer:5432/kyc", poolsize=20) AsyncSessionLocal = sessionmaker(engine, class=AsyncSession, expireoncommit=False) ``

1. Definir modelos en backend/db/models/:

- AuditSession: sessionid, useridhash, decision, globalscore, agentscores (JSONB), integrityhash, createdat. - BlacklistedDocument: docnumberhash, doctype, country, reason, createdat. - ManualReviewQueue: sessionid, reason, status, assignedto, createdat.

1. Inyectar sesión DB en FastAPI via dependency: async with AsyncSessionLocal() as session.
2. Usar session.add() + await session.commit() — nunca commits síncronos.
3. Gestionar migraciones con Alembic: alembic upgrade head en el init del contenedor.
4. Conectar siempre a través de PgBouncer (puerto 5432) — nunca directo al puerto 5433 de PostgreSQL.

Notes

• expireoncommit=False es obligatorio en async para evitar lazy loading tras el commit.
• Los INSERTs de auditoría deben ser fire-and-forget: usar asyncio.create_task() para no bloquear la respuesta al cliente.
• Nunca almacenar embeddings faciales en PostgreSQL — usar MinIO con TTL corto.