ADR 017: Plugin data ownership¶

Estado¶

Aceptado — 2026-07

Relacionado con ADR 007 y ADR 008.

Contexto¶

HIVE usa PostgreSQL compartido (cortex). El framework resuelve URL y tablas de plataforma; los plugins de dominio deben poseer modelos, migraciones y convención de tablas sin acoplar el ORM al core.

Decisión¶

Reglas:

1. Una cadena Alembic independiente por plugin que persista.
2. Tablas en public con prefijo {plugin_id}_.
3. Setup local ejecuta alembic upgrade head para plugins con alembic.ini (deploy/setup-postgres-local.sh).
4. Versión aplicada registrada en cortex_migrations (por plugin_id).
5. Runtime: sesión async por request vía get_async_session(); sin estado global de ORM.

Leyenda: Capas de ownership de datos en PostgreSQL compartido. Actores: core, framework/database, plugins. Estado: Implementado (booking con Alembic).

flowchart TB
  subgraph core [core SPI]
    SPI[Tipos sin ORM]
  end
  subgraph framework [framework/database]
    URL[DATABASE_URL]
    Session[get_async_session]
    MigTable[cortex_migrations]
    PlatSet[platform_settings]
  end
  subgraph plugin [cortex_plugin_booking]
    Models[SQLAlchemy models]
    Alembic[alembic versions]
    Tables["booking_* tablas"]
  end
  subgraph pg [PostgreSQL]
    DB[(cortex)]
  end
  SPI --> NoORM[sin import ORM]
  NoORM --> URL
  URL --> Session
  Session --> Models
  Alembic --> Tables
  Tables --> DB
  MigTable --> DB
  PlatSet --> DB

Leyenda: Sesión async por request hacia repositorio del plugin. Actores: handler FastAPI, get_async_session, repositorio. Estado: Implementado.

sequenceDiagram
  participant Req as HTTP handler
  participant Sess as get_async_session
  participant Repo as Repositorio plugin
  participant PG as PostgreSQL
  Req->>Sess: abrir sesion async
  Sess->>Repo: consulta booking_*
  Repo->>PG: SELECT parametrizado
  PG-->>Repo: filas
  Repo-->>Req: dominio
  Req->>Sess: commit
  Sess->>PG: COMMIT

Fuente del diagrama: docs/diagrams/adr/017-plugin-data-ownership-03.mermaid.

Leyenda: ER tablas de plataforma en PostgreSQL compartido. Dominios con Alembic propio (p. ej. booking) documentan su ER en su ADR. Estado: Implementado.

erDiagram
  platform_settings {
    int id PK
    string panel_id
    string section_id
    string key
    json value
    datetime updated_at
  }
  cortex_migrations {
    string plugin_id PK
    string revision
    datetime applied_at
  }
  cortex_migrations ||--o| plugin_registry : registra
  plugin_registry {
    string plugin_id
    string name
  }

Consecuencias¶

• booking es el primer plugin con migración real (001_initial: booking_resources, booking_bookings).
• Fixtures en memoria se sustituyen gradualmente; producción sin _STORE.

Referencias¶

• framework/cortex_framework/database/
• plugins/booking/alembic/