workspace-v1/orchestration/directivas/simco/SIMCO-MIGRACIONES-BD.md

SIMCO-MIGRACIONES-BD

Version: 1.0.0 Tipo: Directiva Operacional Prioridad: P0 Alias: @MIGRACIONES Creado: 2026-01-10 Depende de: SIMCO-DDL.md

---

1. Proposito

Establecer el protocolo estandar para migraciones de base de datos, incluyendo nomenclatura, estructura, rollback obligatorio y flujo de aprobacion.

---

2. Principios de Migraciones

2.1 Inmutabilidad

• Una migracion ejecutada NUNCA se modifica
• Cambios nuevos = migracion nueva
• Historial es sagrado

2.2 Rollback Obligatorio

• Toda migracion UP debe tener DOWN
• Si no es reversible, documentar alternativa
• Probar rollback antes de aplicar

2.3 Atomicidad

• Una migracion = un cambio logico
• No mezclar DDL con DML masivo
• Transaccional cuando sea posible

2.4 Orden Estricto

• Ejecutar en orden cronologico
• Nunca saltar migraciones
• Resolver conflictos antes de merge

---

3. Nomenclatura de Archivos

3.1 Formato Estandar

{YYYYMMDDHHMMSS}_{descripcion_en_snake_case}.sql

Ejemplos:
20260110143000_create_users_table.sql
20260110150000_add_email_to_users.sql
20260110160000_create_tenants_schema.sql

3.2 Convenciones de Nombre

Accion	Prefijo	Ejemplo
Crear tabla	create_	create_users_table.sql
Agregar columna	add_	add_email_to_users.sql
Eliminar columna	remove_	remove_legacy_field.sql
Crear indice	create_index_	create_index_users_email.sql
Crear schema	create_schema_	create_schema_tenants.sql
Datos iniciales	seed_	seed_roles_data.sql
Alterar tabla	alter_	alter_users_add_timestamps.sql

---

4. Estructura de Migracion

4.1 Template Base

-- Migration: {YYYYMMDDHHMMSS}_{descripcion}
-- Autor: {nombre}
-- Fecha: {YYYY-MM-DD}
-- Descripcion: {descripcion detallada}
-- Rollback: {SI|NO - si NO, explicar alternativa}

-- ============================================
-- UP MIGRATION
-- ============================================

BEGIN;

-- {Comandos DDL aqui}

COMMIT;

-- ============================================
-- DOWN MIGRATION (ROLLBACK)
-- ============================================

-- Para ejecutar rollback, descomentar y ejecutar:
/*
BEGIN;

-- {Comandos de rollback aqui}

COMMIT;
*/

4.2 Ejemplo Completo

-- Migration: 20260110143000_create_users_table
-- Autor: Backend Team
-- Fecha: 2026-01-10
-- Descripcion: Crea tabla de usuarios con RLS
-- Rollback: SI

-- ============================================
-- UP MIGRATION
-- ============================================

BEGIN;

CREATE TABLE IF NOT EXISTS core.users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES core.tenants(id),
    email VARCHAR(255) NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    first_name VARCHAR(100),
    last_name VARCHAR(100),
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT uq_users_email_tenant UNIQUE (tenant_id, email)
);

-- Indices
CREATE INDEX idx_users_tenant ON core.users(tenant_id);
CREATE INDEX idx_users_email ON core.users(email);

-- RLS
ALTER TABLE core.users ENABLE ROW LEVEL SECURITY;

CREATE POLICY users_tenant_isolation ON core.users
    USING (tenant_id = current_setting('app.current_tenant')::UUID);

COMMIT;

-- ============================================
-- DOWN MIGRATION (ROLLBACK)
-- ============================================

/*
BEGIN;

DROP POLICY IF EXISTS users_tenant_isolation ON core.users;
DROP TABLE IF EXISTS core.users;

COMMIT;
*/

---

5. Rollback Obligatorio

5.1 Reglas de Rollback

Tipo Cambio	Rollback Posible	Estrategia
CREATE TABLE	SI	DROP TABLE
ADD COLUMN	SI	DROP COLUMN
DROP COLUMN	NO*	Backup previo requerido
MODIFY TYPE	DEPENDE	Nueva migracion
DROP TABLE	NO*	Backup previo requerido
CREATE INDEX	SI	DROP INDEX
INSERT seed	SI	DELETE con WHERE

*Requiere backup y plan de recuperacion documentado

5.2 Cuando NO es Posible Rollback

Si rollback no es posible, documentar:

-- Migration: 20260110170000_drop_legacy_table
-- Rollback: NO
-- Alternativa: Restaurar desde backup (ver docs/recovery/legacy_table.md)
-- Backup requerido: SI - ejecutar scripts/backup_legacy_table.sh antes

---

6. Testing de Migraciones

6.1 Checklist Pre-Aplicacion

• Migracion tiene rollback
• Rollback fue probado localmente
• No rompe migraciones anteriores
• Indempotente (puede correr 2 veces sin error)
• Performance verificada en dataset similar a prod

6.2 Script de Validacion

#!/bin/bash
# scripts/validate_migration.sh

MIGRATION_FILE=$1

# 1. Verificar sintaxis SQL
psql -h localhost -U test -d test_db -f $MIGRATION_FILE --dry-run

# 2. Aplicar migracion
psql -h localhost -U test -d test_db -f $MIGRATION_FILE

# 3. Verificar rollback
# Extraer seccion DOWN y ejecutar
sed -n '/DOWN MIGRATION/,$ p' $MIGRATION_FILE | sed 's/^--//' | psql -h localhost -U test -d test_db

# 4. Re-aplicar para verificar idempotencia
psql -h localhost -U test -d test_db -f $MIGRATION_FILE

echo "Migration validated successfully"

---

7. Documentacion Requerida

7.1 En el Archivo de Migracion

-- Migration: {timestamp}_{descripcion}
-- Autor: {nombre/equipo}
-- Fecha: {YYYY-MM-DD}
-- Descripcion: {que hace esta migracion}
-- Rollback: {SI|NO}
-- Impacto: {LOW|MEDIUM|HIGH}
-- Downtime: {YES|NO} - {minutos estimados si YES}
-- Dependencias: {migraciones previas requeridas}
-- Ticket: {JIRA-XXX o N/A}

7.2 En DATABASE_INVENTORY.yml

migraciones:
  ultima: "20260110143000"
  pendientes: 0
  historial:
    - id: "20260110143000"
      archivo: "20260110143000_create_users_table.sql"
      descripcion: "Crea tabla de usuarios con RLS"
      fecha_aplicado: "2026-01-10"
      autor: "Backend Team"
      rollback_probado: true

---

8. Flujo de Aprobacion

8.1 Proceso Estandar

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Crear     │ --> │   Review    │ --> │   Aprobar   │
│  Migracion  │     │   por DBA   │     │   en PR     │
└─────────────┘     └─────────────┘     └─────────────┘
                                              │
                                              v
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Produccion │ <-- │   Staging   │ <-- │   Develop   │
│   (con      │     │   (test     │     │   (apply    │
│  supervision)│    │   rollback) │     │   local)    │
└─────────────┘     └─────────────┘     └─────────────┘

8.2 Matriz de Aprobacion

Impacto	Review Requerido	Aprobador
LOW	Code Review	Tech Lead
MEDIUM	Code + DBA Review	Tech Lead + DBA
HIGH	Code + DBA + Arch	CTO/Arquitecto

8.3 Criterios de Impacto

Nivel	Criterio
LOW	Solo agrega (columnas, tablas, indices)
MEDIUM	Modifica estructura existente
HIGH	Elimina datos, cambios breaking, downtime

---

9. Integracion con SIMCO-DDL

9.1 Referencia a SIMCO-DDL

Esta directiva extiende @SIMCO-DDL con:

• Proceso de migraciones incrementales
• Protocolo de rollback
• Flujo de aprobacion

9.2 Patrones de DDL Aplicables

Ver SIMCO-DDL.md para:

• Patrones de nombres de tablas
• Convencion de tipos de datos
• Estructura de RLS
• Naming de constraints

---

10. Ubicacion de Archivos

10.1 Estructura de Directorio

apps/database/
├── migrations/
│   ├── 20260110143000_create_users_table.sql
│   ├── 20260110150000_add_email_to_users.sql
│   └── 20260110160000_create_tenants_schema.sql
├── seeds/
│   ├── 001_roles.sql
│   └── 002_permissions.sql
├── scripts/
│   ├── validate_migration.sh
│   ├── apply_migrations.sh
│   └── rollback_migration.sh
└── README.md

---

11. Referencias

Directiva	Proposito
SIMCO-DDL.md	Patrones DDL base
SIMCO-INVENTARIOS.md	Registro en DATABASE_INVENTORY
SIMCO-DEVOPS.md	CI/CD para migraciones

---

Ultima actualizacion: 2026-01-10 Mantenido por: Orchestration Team