Documentación de Base de Datos - Calmia Nexus¶

Este directorio contiene documentación técnica sobre la base de datos PostgreSQL del proyecto Calmia Nexus.

Índice de Documentos¶

Architecture Decision Records (ADRs)¶

ADR	Título	Estado	Fecha
ADR-002	Eliminación de Índices Duplicados	Propuesto	2026-02-01
ADR-003	Eliminación de Índices No Utilizados en McpRequestLogs	Propuesto	2026-02-01

Informes de Análisis¶

Documento	Descripción
RemoteAgents-Query-Analysis.md	Análisis de patrones de consulta en tabla RemoteAgents
McpRequestLogs-Unused-Indexes-Report.md	Identificación de índices no utilizados en McpRequestLogs
McpRequestLogs-Index-Usage-Report.md	Uso de índices en código fuente
McpRequestLogs-Risk-Assessment.md	Evaluación de riesgos de eliminación de índices

Informes de Validación¶

Documento	Descripción
RemoveDuplicateIndexes-Validation-Report.md	Validación de migración de índices duplicados

Resumen de Optimizaciones de Base de Datos¶

Fecha: 2026-02-01¶

1. Eliminación de Índices Duplicados (ADR-002)¶

Tablas afectadas: Organizations, Users, ProjectAgentPaths, WellnessRecords

Índice Eliminado	Tabla	Razón
`IX_Organizations_Slug`	Organizations	Duplicado de constraint UNIQUE
`IX_Users_Email`	Users	Duplicado de constraint UNIQUE
`IX_ProjectAgentPaths_ProjectId_RemoteAgentId`	ProjectAgentPaths	Duplicado de constraint UNIQUE
`IX_WellnessRecords_UserId_RecordDate`	WellnessRecords	Duplicado de constraint UNIQUE

Impacto: - INSERT/UPDATE: +15-25% más rápido - Espacio: ~50% menos en índices afectados

2. Eliminación de Índices No Utilizados en McpRequestLogs (ADR-003)¶

Tabla afectada: McpRequestLogs

Categoría	Índices Eliminados
Simples	ClientId, CorrelationId, SessionId, Method, ToolName
Compuestos	ReceivedAt_Status, ToolName_ReceivedAt, Method_Status
Especiales	RequestParams_GIN
Parciales	Status, ErrorCode, DurationMs, ReceivedAt

Total: 11 índices eliminados, 3 mantenidos (PK + 2 FK)

Impacto: - INSERT: +45-60% más rápido - UPDATE: +40-50% más rápido - Espacio: ~800 KB recuperados

Migraciones Pendientes¶

Migración	Descripción	Estado
`20260201120000_OptimizeRemoteAgentsIndexes`	Optimización de índices en RemoteAgents	Pendiente
`20260201130000_RemoveDuplicateIndexes`	Eliminación de índices duplicados	Pendiente
`20260201140000_RemoveUnusedMcpRequestLogsIndexes`	Eliminación de índices en McpRequestLogs	Pendiente

Aplicar Migraciones¶

# Aplicar todas las migraciones pendientes
dotnet ef database update --project Orchestrator/src/Orchestrator.Api

# Aplicar migración específica
dotnet ef database update 20260201140000_RemoveUnusedMcpRequestLogsIndexes --project Orchestrator/src/Orchestrator.Api

Scripts SQL¶

Los scripts SQL se encuentran en scripts/database/:

Script	Descripción
`identify-duplicate-indexes.sql`	Identificar índices duplicados
`verify-unique-constraints.sql`	Verificar constraints UNIQUE
`drop-duplicate-indexes.sql`	Eliminar índices duplicados
`identify-unused-mcprequestlogs-indexes.sql`	Identificar índices sin uso
`drop-unused-mcprequestlogs-indexes.sql`	Eliminar índices no utilizados
`validate-mcprequestlogs-after-index-removal.sql`	Validar después de eliminación
`optimize-remoteagents-indexes.sql`	Optimizar índices de RemoteAgents

Consultas Útiles¶

Verificar uso de índices¶

SELECT
    schemaname,
    relname AS table_name,
    indexrelname AS index_name,
    idx_scan,
    idx_tup_read,
    idx_tup_fetch
FROM pg_stat_user_indexes
ORDER BY idx_scan ASC;

Verificar tamaño de índices¶

SELECT
    tablename,
    indexname,
    pg_size_pretty(pg_relation_size(indexname::regclass)) as size
FROM pg_indexes
WHERE schemaname = 'public'
ORDER BY pg_relation_size(indexname::regclass) DESC;

Verificar índices duplicados¶

SELECT
    array_agg(indexname) as index_names,
    tablename,
    array_agg(indexdef) as definitions
FROM pg_indexes
WHERE schemaname = 'public'
GROUP BY tablename, replace(indexdef, indexname, '')
HAVING COUNT(*) > 1;