Nexus - AI Task Orchestrator

11-database-schema-migration
Procedimiento: Migraci├│n de Schema de Base de Datos

Base de Datos
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
10690 caracteres
# Procedimiento: Migraci├│n de Schema de Base de Datos

## Metadata
- **ID**: PROC-11
- **Frecuencia**: Seg├║n necesidad (cambios de schema)
- **Duraci├│n estimada**: 1-4 horas (seg├║n complejidad)
- **Requiere**: Acceso SQL Server (HERMES), conocimiento del schema
- **Dependencias**: PROC-03 (performance review post-migraci├│n)
- **Bloquea**: Deploy si migraci├│n es requerida

## Objetivo

Ejecutar cambios de schema de base de datos de forma segura, con rollback plan y m├¡nimo impacto en producci├│n.

## Restricciones

| Servidor | Migraciones permitidas |
|----------|----------------------|
| `api.dmi.es` (HERMES) | S├¡ |
| `sql.dmi.es` (LEGACY) | No - Solo lectura |

## Tipos de Migraci├│n

| Tipo | Riesgo | Downtime | Ejemplo |
|------|--------|----------|---------|
| **Additive** | Bajo | No | Nueva tabla, nueva columna nullable |
| **Modificaci├│n** | Medio | Posible | Cambiar tipo, a├▒adir constraint |
| **Destructiva** | Alto | S├¡ | Drop column, drop table |
| **Data** | Variable | Variable | UPDATE masivo, backfill |

## Par├ímetros de la Migraci├│n

| Campo | Valor |
|-------|-------|
| **ID Migraci├│n** | MIG-___ |
| **Descripci├│n** | |
| **Tipo** | Additive / Modificaci├│n / Destructiva / Data |
| **BD Afectada** | Hermes_v1.2 / Hermes_v1.3 / IA |
| **Tablas afectadas** | |
| **Requiere downtime** | S├¡ / No |
| **Ventana de ejecuci├│n** | |

## Checklist Ejecutable

### Fase 1: Preparaci├│n

#### 1.1 Documentar cambio
```sql
-- Crear script de migraci├│n: migrations/MIG-XXX-descripcion.sql

/*
Migration: MIG-XXX
Description: [Qu├® hace]
Author: [Nombre]
Date: YYYY-MM-DD
Ticket: [Link]

Pre-requisites:
- [Lista de condiciones]

Rollback: migrations/MIG-XXX-rollback.sql
*/
```

- [ ] Script de migraci├│n creado
- [ ] Descripci├│n clara del cambio

#### 1.2 Crear script de rollback
```sql
-- migrations/MIG-XXX-rollback.sql

/*
Rollback for: MIG-XXX
*/

-- Ejemplo: si migraci├│n a├▒ade columna
ALTER TABLE dbo.MyTable DROP COLUMN NewColumn;

-- Ejemplo: si migraci├│n crea tabla
DROP TABLE IF EXISTS dbo.NewTable;

-- Ejemplo: si migraci├│n modifica datos
-- [Script para restaurar datos - puede requerir backup]
```

- [ ] Script de rollback creado
- [ ] Rollback probado en dev

#### 1.3 Estimar impacto
```sql
-- Verificar tama├▒o de tabla afectada
SELECT
    t.name AS table_name,
    p.rows AS row_count,
    SUM(a.total_pages) * 8 / 1024 AS total_mb
FROM sys.tables t
INNER JOIN sys.partitions p ON t.object_id = p.object_id
INNER JOIN sys.allocation_units a ON p.partition_id = a.container_id
WHERE t.name = 'TablaAfectada'
GROUP BY t.name, p.rows;

-- Estimar tiempo de migraci├│n (regla general)
-- < 100K rows: segundos
-- 100K - 1M rows: minutos
-- > 1M rows: considerar batching
```

| Tabla | Rows | Tama├▒o MB | Tiempo estimado |
|-------|------|-----------|-----------------|
| | | | |

- [ ] Impacto estimado

#### 1.4 Verificar dependencias
```sql
-- Foreign keys que referencian la tabla
SELECT
    fk.name AS fk_name,
    OBJECT_NAME(fk.parent_object_id) AS child_table,
    OBJECT_NAME(fk.referenced_object_id) AS parent_table
FROM sys.foreign_keys fk
WHERE OBJECT_NAME(fk.referenced_object_id) = 'TablaAfectada'
   OR OBJECT_NAME(fk.parent_object_id) = 'TablaAfectada';

-- Stored procedures que usan la tabla
SELECT DISTINCT OBJECT_NAME(object_id) AS proc_name
FROM sys.sql_modules
WHERE definition LIKE '%TablaAfectada%';

-- C├│digo que usa la tabla
grep -rn "TablaAfectada" src/
```

- [ ] Dependencias identificadas
- [ ] C├│digo actualizado (si necesario)

### Fase 2: Testing en Dev/Pre

#### 2.1 Ejecutar en Dev
```sql
-- Conectar a BD de dev
USE [Hermes_v1.2_Dev];  -- o similar

-- Ejecutar migraci├│n
:r migrations/MIG-XXX-descripcion.sql

-- Verificar resultado
SELECT * FROM dbo.TablaAfectada WHERE ...;
```

- [ ] Migraci├│n exitosa en dev
- [ ] Datos correctos

#### 2.2 Probar rollback en Dev
```sql
-- Ejecutar rollback
:r migrations/MIG-XXX-rollback.sql

-- Verificar que volvi├│ al estado anterior
SELECT * FROM dbo.TablaAfectada WHERE ...;
```

- [ ] Rollback exitoso en dev

#### 2.3 Ejecutar en Pre-producci├│n
```bash
# Deploy c├│digo que usa el nuevo schema (si hay cambios de c├│digo)
git tag -f pre
git push origin pre --force

# Esperar deploy
```
```sql
-- Conectar a Pre
USE [Hermes_v1.2];  -- en servidor de pre

-- Ejecutar migraci├│n
:r migrations/MIG-XXX-descripcion.sql
```

- [ ] Migraci├│n exitosa en pre
- [ ] Aplicaci├│n funciona correctamente

### Fase 3: Ejecuci├│n en Producci├│n

#### 3.1 Pre-checks
```sql
-- Verificar que no hay transacciones largas
SELECT
    session_id,
    transaction_id,
    DATEDIFF(MINUTE, transaction_begin_time, GETDATE()) AS minutes_open
FROM sys.dm_tran_session_transactions st
JOIN sys.dm_tran_active_transactions at ON st.transaction_id = at.transaction_id
WHERE DATEDIFF(MINUTE, transaction_begin_time, GETDATE()) > 5;

-- Verificar conexiones activas
SELECT COUNT(*) AS active_connections
FROM sys.dm_exec_sessions
WHERE database_id = DB_ID('Hermes_v1.2');
```

- [ ] Sin transacciones largas
- [ ] Conexiones en nivel normal

#### 3.2 Backup (si es destructiva/modificaci├│n)
```sql
-- Para migraciones de riesgo medio/alto
SELECT * INTO dbo.TablaAfectada_backup_YYYYMMDD
FROM dbo.TablaAfectada;

-- Verificar backup
SELECT COUNT(*) FROM dbo.TablaAfectada_backup_YYYYMMDD;
```

- [ ] Backup creado (si aplica)

#### 3.3 Ejecutar migraci├│n
```sql
-- Conectar a Producci├│n (api.dmi.es / Hermes_v1.2)

BEGIN TRANSACTION;

-- Ejecutar migraci├│n
:r migrations/MIG-XXX-descripcion.sql

-- Verificar resultado
SELECT TOP 10 * FROM dbo.TablaAfectada;

-- Si todo OK:
COMMIT;

-- Si hay problemas:
-- ROLLBACK;
```

- [ ] Migraci├│n ejecutada
- [ ] Verificaci├│n visual OK
- [ ] COMMIT ejecutado

#### 3.4 Post-checks
```sql
-- Verificar integridad
SELECT COUNT(*) FROM dbo.TablaAfectada;

-- Verificar que no hay errores
SELECT * FROM dbo.TablaAfectada WHERE NewColumn IS NULL AND ShouldNotBeNull = 1;

-- Verificar performance
-- (ejecutar query t├¡pica y verificar tiempo)
```

- [ ] Integridad OK
- [ ] Performance OK

### Fase 4: Verificaci├│n Post-Migraci├│n

#### 4.1 Verificar aplicaci├│n
```bash
# Smoke test
curl -X POST https://bigcapi.dmi.es/mcp \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Verificar funcionalidad afectada
```

- [ ] Aplicaci├│n funciona
- [ ] Funcionalidad espec├¡fica OK

#### 4.2 Monitorear errores
```bash
# Verificar Sentry
sentry-cli issues list --org dmi-hl --project apibigcommerce-mcp \
  --query "is:unresolved firstSeen:-1h"
```

- [ ] Sin errores nuevos en Sentry

#### 4.3 Limpiar
```sql
-- Despu├®s de 7 d├¡as sin problemas, eliminar backup
DROP TABLE IF EXISTS dbo.TablaAfectada_backup_YYYYMMDD;
```

- [ ] Backup eliminado (despu├®s de periodo de gracia)

## Patrones de Migraci├│n Seguros

### A├▒adir columna nullable (Bajo riesgo)
```sql
ALTER TABLE dbo.MyTable ADD NewColumn NVARCHAR(100) NULL;
```

### A├▒adir columna con default (Bajo riesgo)
```sql
ALTER TABLE dbo.MyTable ADD NewColumn INT NOT NULL DEFAULT 0;
```

### Cambiar tipo de columna (Medio riesgo)
```sql
-- 1. A├▒adir nueva columna
ALTER TABLE dbo.MyTable ADD NewColumn_New NVARCHAR(200) NULL;

-- 2. Migrar datos
UPDATE dbo.MyTable SET NewColumn_New = CAST(NewColumn AS NVARCHAR(200));

-- 3. Verificar
SELECT COUNT(*) FROM dbo.MyTable WHERE NewColumn_New IS NULL AND NewColumn IS NOT NULL;

-- 4. Swap (en ventana de mantenimiento)
EXEC sp_rename 'dbo.MyTable.NewColumn', 'NewColumn_Old', 'COLUMN';
EXEC sp_rename 'dbo.MyTable.NewColumn_New', 'NewColumn', 'COLUMN';

-- 5. Despu├®s de verificar, drop old
ALTER TABLE dbo.MyTable DROP COLUMN NewColumn_Old;
```

### Crear ├¡ndice sin bloqueo (SQL Server 2014+)
```sql
CREATE NONCLUSTERED INDEX IX_MyTable_Column
ON dbo.MyTable (Column)
WITH (ONLINE = ON, SORT_IN_TEMPDB = ON);
```

## Troubleshooting

| S├¡ntoma | Causa | Acci├│n |
|---------|-------|--------|
| Migraci├│n muy lenta | Tabla grande, sin ├¡ndice | Ejecutar en ventana de bajo tr├ífico |
| Lock timeout | Conexiones activas | Retry, o ejecutar fuera de horario |
| Espacio en disco | Tabla muy grande | Verificar espacio antes, limpiar tempdb |
| Error de FK | Datos inconsistentes | Limpiar datos primero |

## Resultado

- **├ëxito**: Migraci├│n completada, aplicaci├│n funciona, sin errores
- **Parcial**: Migraci├│n completada, problemas menores resueltos
- **Fallo**: Rollback ejecutado, investigar causa

## Mensaje de Finalizaci├│n

**IMPORTANTE - ACCI├ôN REQUERIDA AL FINALIZAR:**

Cuando hayas completado todos los pasos de este procedimiento, DEBES ejecutar el siguiente comando usando la herramienta Bash:

Ejecuta: `echo "====== PROCESO TERMINADO [$(date +%H%M%S)] ======" && echo "RESULTADO: Migracion MIG-XXX completada en [BD], app verificada OK"`

Sustituye MIG-XXX y [BD] por los valores reales.


---

## Output Estructurado (Nexus)

Al finalizar, el agente DEBE generar un bloque JSON con el siguiente formato para que Nexus pueda procesarlo automaticamente:

```json
{
  "result": "success",
  "summary": "Ejecucion de PROC-11 completada. [Descripcion breve de resultados]",
  "metrics": {
    "issues_found": 0,
    "issues_resolved": 0,
    "queries_analyzed": 50, "slow_queries": 3,
    "custom": {
      "procedure_specific_metric": "value"
    }
  },
  "backlog_items": [
    {
      "title": "Titulo del item de seguimiento",
      "description": "Descripcion detallada si se requiere accion futura",
      "priority": "medium",
      "type": "improvement",
      "tags": ["proc-11"]
    }
  ],
  "next_steps": [
    "Accion recomendada 1",
    "Accion recomendada 2"
  ],
  "warnings": [
    "Advertencias encontradas durante la ejecucion"
  ]
}
```

**Campos requeridos:**
- `result`: `"success"` | `"partial"` | `"failed"`
- `summary`: Resumen ejecutivo en 1-3 lineas

**Metricas especificas de este procedure:**
- migrations_pending, migrations_applied

**Criterios de resultado:**
- `success`: Procedimiento completado sin errores criticos
- `partial`: Completado con algunos problemas menores o items pendientes
- `failed`: Error critico o no se pudo completar

## Historial de Migraciones

| Fecha | ID | Descripci├│n | BD | Tipo | Duraci├│n | Resultado |
|-------|-----|------------|-----|------|----------|-----------|
| | | | | | | |