ADR 007: Persistencia PostgreSQL¶

Estado¶

Aceptado — 2026-07 · Implementado (parcial) — BD única cortex, DATABASE_URL; plugins con fixtures; booking con Alembic

Diagramas históricos

Los diagramas de este ADR describen el modelo BD única actual. El modelo multi-tenant (X-Tenant-Id, BD por inquilino) fue eliminado en julio 2026. Para ownership por plugin, migraciones Alembic y sesión async, ver ADR 017 y sus diagramas canónicos.

Relacionado con ADR 001 (stack HIVE) y ADR 008 (dominio en plugins independientes; booking como primer plugin con persistencia real).

Contexto¶

HIVE usa PostgreSQL 16 con una base de datos compartida (cortex). Cada plugin de dominio es dueño de sus tablas y migraciones Alembic; el framework resuelve la URL y expone utilidades de sesión async.

Hoy:

DATABASE_URL y database_url() en framework/cortex_framework/database/.
Plugins de dominio usan fixtures en memoria; booking tiene esqueleto Alembic.
Tablas de plataforma: platform_settings, cortex_migrations.

Decisión¶

Base de datos única¶

Una instancia PostgreSQL con base cortex.
Sin header Authorization ni resolución de URL por inquilino.

Responsabilidades¶

Capa	Responsabilidad
framework	`database_url()`, factory de sesión async, tablas de plataforma
plugin	Modelos SQLAlchemy 2 async, `alembic/`, seeds de dev opcionales
core	Sin dependencia de ORM

Convención de tablas¶

Tablas en schema public con prefijo por plugin: booking_resources, booking_slots, booking_bookings.
Cada plugin mantiene su propio alembic.ini y cadena de revisiones independiente.
Utilidad mínima: get_async_session() -> AsyncSession.

Setup local¶

bash deploy/setup-postgres-local.sh — crea rol cortex, BD cortex, migraciones booking, tablas framework.
DATABASE_URL=postgresql+asyncpg://cortex:cortex@localhost:5432/cortex.

Runtime¶

Handler del plugin obtiene sesión vía get_async_session() con URL fija.
Settings de plataforma en tabla platform_settings (sin columna tenant_id).

Leyenda: Framework resuelve URL única; cada plugin Independiente posee modelos y Alembic. Estado: Parcial.

flowchart TB
  subgraph framework [Framework Dependiente]
    URL[database_url]
    Session[get_async_session]
    Platform[platform_settings]
  end
  subgraph plugins [cortex_plugin_*]
    BK[booking alembic]
    CL[clients fixtures]
  end
  subgraph data [PostgreSQL]
    DB[(cortex)]
  end
  URL --> Session
  Session --> BK
  Session --> CL
  BK --> DB
  CL --> DB
  Platform --> DB

Consecuencias¶

Positivas: modelo simple, un solo connection string, menos superficie en middleware y clientes HTTP.
Negativas: sin aislamiento físico por cliente en la misma instancia; escalar a multi-inquilino requeriría ADR nuevo.
Migración desde cortex: ALTER DATABASE cortex RENAME TO cortex si aplica.

Referencias¶

framework/cortex_framework/database/
deploy/setup-postgres-local.sh
deploy/init_cortex_db.py
ADR 017