Base de datos CreaRack Pro · arquitectura técnica

Referencia técnica del esquema PostgreSQL. Para una explicación accesible ve a [[crearack-tech—bd—coloquial]].

1. Stack de persistencia

Conexiones

• CONN_MAX_AGE = 0 (obligatorio con Daphne ASGI — footgun revertido 4 veces, causa saturación si se cambia)
• DATABASES['default']['HOST'] apunta a pgbouncer:6432 en PROD/STAGE
• Pool default por worker. PG max_connections=500, pgbouncer pool default_pool_size=20
• Desde s215 la app conecta con el rol crearack_app (NOSUPERUSER) — condición necesaria para que RLS muerda de verdad (ver 2.2)
• ⚠️ Los tests del gate pre-push usan config.settings.test con BD directa a db:5432 sin pgbouncer (s233 — mata los falsos rojos del teardown paralelo)

2. Multi-tenancy · arquitectura de dos capas

2.1 Capa ORM (Django)

Patrón obligatorio en todos los queries:

device = get_object_or_404(Device, id=device_id, rack__organization=org)

get_current_org(request) retorna None si el user no tiene org. No hay fallback — cada endpoint debe verificar.

2.2 Capa DB (PostgreSQL RLS)

Implementado en v1.0.50 (03-04-2026), migration core/0017_rls_policies. ACTIVO DE VERDAD desde s215 (v1.48.1, 09-07-2026) en PROD y desde s224 en STAGE: la app conecta como crearack_app NOSUPERUSER (antes conectaba como superuser y las 38 políticas eran inertes — footgun footguns_rls_inerte_superuser_prod).

Mecanismo:

1. TenantRLSMiddleware (después de ModuleGatingMiddleware) ejecuta SET app.current_org_id = '{org_id}' al inicio del request
2. PG aplica política USING (organization_id = current_setting('app.current_org_id')::int) en cada SELECT/UPDATE/DELETE
3. Al terminar, RESET app.current_org_id previene leakage en conexiones pooled

Bypass (estado post-s215):

⚠️ Trampa de verificación (cazada s224): un test crudo por psql con crearack_app hereda el default '0' y ve TODO — engaña. Para probar el aislamiento hay que fijar el GUC a un org real: SET app.current_org_id = '1' → 1 fila propia · '999999' → 0 filas. Pendiente aparte: endurecer el bypass de Huey (fijar GUC por task y retirar el default de rol — ciclo propio, necesita test de task real).

2.3 Cobertura

29 tablas con organization_id NOT NULL (aislamiento estricto):

6 tablas con organization_id NULLABLE (filas propias + globales):

Tablas con FK heredada (Device→Rack→Org, ConfigBackup→Device→Rack→Org, etc.) no necesitan política propia: la integridad referencial protege automáticamente vía CASCADE.

3. Mapa ER global

erDiagram
    Organization ||--o{ User : "tiene"
    Organization ||--o{ Rack : "es dueña de"
    Organization ||--o{ Blueprint : "es dueña de"
    Organization ||--o{ MonitoringTarget : "monitoriza"
    Organization ||--o{ SignagePlayer : "controla"
    Organization ||--o{ AgentInstance : "tiene agents"
    Organization ||--o{ StoredCredential : "almacena"
    Organization }o--|| Plan : "suscrita a"
    Plan }o--o{ SaaSModule : "incluye"
    Organization }o--o{ SaaSModule : "extra a la carta"
    User ||--o{ LoginLog : "genera"
    User ||--o{ SystemLog : "audita"
    User ||--o{ ImpersonationLog : "impersona"
    User ||--o| ModulePermission : "permisos extra"
    Rack ||--o{ Device : "contiene"
    Rack ||--o{ ConfigBackup : "snapshots"
    Rack ||--o{ BlueprintPlacement : "ubicado en"
    Rack }o--o{ RackGroup : "agrupado en"
    Blueprint ||--o{ BlueprintPlacement : "ubica"
    Blueprint ||--o{ MapAnnotation : "anotaciones"
    Device ||--o{ PortConnection : "conexiones"
    Device }o--|| DeviceProfile : "perfil"
    DeviceProfile }o--|| VendorProfile : "vendor"
    SignagePlayer }o--|| SignageVendorAdapter : "adapter"
    SignagePlayer ||--o{ PlaybackLog : "reproduce"
    Playlist ||--o{ MediaAsset : "contiene"
    Schedule }o--|| Playlist : "programa"
    MonitoringTarget ||--o{ AIInsight : "genera"
    AIInsight }o--o{ IncidentGroup : "agrupado en"
    AIInsight ||--o{ AIInsightAuditLog : "auditoría"
    AIInsight ||--o{ InsightConversation : "Q&A"
    IncidentGroup }o--|| SLAPolicy : "SLA"
    IncidentGroup }o--|| EscalationPolicy : "escalation"

4. Apps y modelos · referencia por archivo

4.1 core/ · multi-tenancy, auth, auditoría (11 modelos)

4.2 racks/ · Rack Editor (6 modelos)

4.3 blueprints/ · Map Editor + Auto-Plan AI (4 modelos)

4.4 monitoring/ · Observatory + ITSM + CNS (19 modelos)

Repartido en 3 archivos: models.py (5), models_insight.py (3 · CNS/AI Brain), models_itsm.py (11 · ITSM).

models.py — Network monitoring core:

models_insight.py — Network Sentinel AI (CNS):

models_itsm.py — ITSM operacional:

4.5 network/ · Vendor intelligence + Auto-Provision (4 modelos)

4.6 terminal/ · SSH + Local Agent (2 modelos)

4.7 signage/ · Digital Signage CMS (9 modelos)

5. Índices clave (no exhaustivo)

6. Migrations y mantenimiento

6.1 Crear migrations

docker compose exec web python manage.py makemigrations
docker compose exec web python manage.py migrate

Footgun: las migraciones numéricas Django son inmutables una vez aplicadas en PROD. Si haces edit in-place y vuelves a migrate, no se re-ejecuta (Django ya tiene la row en django_migrations). Crear nueva migration siempre.

Nota operativa: Dokploy auto-aplica migraciones en cada deploy (STAGE y PROD migran al mergear — memoria reference_dokploy_auto_migrate).

6.2 Backup pg_dump diario (PROD)

Cron en server crearack-prod:

# /etc/cron.d/pg_backup
0 3 * * * root /opt/crearack/scripts/pg_dump_daily.sh

Output a /opt/pg-backups/crearack-YYYY-MM-DD.dump. Retención 7 días local + sync semanal a DR backup workspace. Además: WAL archiving continuo + pg_basebackup semanal (dom 04:00) a Object Storage — cadena PITR verificada E2E (21-07-2026).

6.3 Backup per-tenant (Huey)

# Huey task agendada
@huey.periodic_task(crontab(hour=3, minute=30))
def run_org_backups():
    ...

Output: MEDIA_ROOT/backups/{org_id}/backup_YYYY-MM-DD.zip con backup_data.json (14 entity types) + media/uploads/. Retención: Organization.backup_retention_days (default plan: Starter 7d, Pro 30d).

6.4 Integridad cross-tenant (Huey)

@huey.periodic_task(crontab(hour=4, minute=0))
def check_tenant_integrity():
    ...

Detecta anomalías tipo Device.org_id != Rack.org_id y registra en SystemLog.

7. Operaciones comunes (psql)

Verificar RLS activo en una tabla

SELECT relname, relrowsecurity, relforcerowsecurity
FROM pg_class WHERE relname = 'racks_rack';

SELECT * FROM pg_policies WHERE tablename = 'racks_rack';

Listar tablas con RLS habilitado

SELECT tablename, rowsecurity
FROM pg_tables
WHERE schemaname = 'public' AND rowsecurity = true;

Probar el aislamiento RLS de verdad (post-s215)

-- Como crearack_app, fijar un org REAL (el default de rol '0' es bypass y engaña):
SET app.current_org_id = '1';       -- debe devolver solo filas del org 1
SELECT count(*) FROM racks_rack;
SET app.current_org_id = '999999';  -- debe devolver 0 filas
SELECT count(*) FROM racks_rack;

Matar conexiones idle (emergencia)

SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle' AND pid != pg_backend_pid();

Detectar integridad cross-tenant manualmente

SELECT d.id, d.name, d.organization_id AS device_org, r.organization_id AS rack_org
FROM racks_device d
JOIN racks_rack r ON d.rack_id = r.id
WHERE d.organization_id != r.organization_id;

8. Footguns documentados

9. Acceso operativo

Véase también

• [[crearack-tech—bd—coloquial]] — Versión accesible para entrada al proyecto
• [[workspace-tech—bd—tecnico]] — BD del workspace (Cloudflare D1)
• [[crearack-tech—agents—dev-core]] — Briefing técnico del módulo core
• Documentation/guides/DATABASE_ADMIN_GUIDE.md — Manual operativo completo
• Documentation/guides/SECURITY_GUIDE.md — Multi-tenancy security detail
• Documentation/guides/CAPACITY_PLANNING.md — Plan de escalado (>200 tenants → read-replica)