---
name: db-migrate
description: >
  Gestão de migrations do schema cr_*.
  Aplica, reverte e lista migrations pendentes.
argument-hint: "[up|down|status|create] [migration-name]"
---

# /descomplicar:db-migrate

Gestão de migrations para as tabelas cr_* da infraestrutura Claude Code.

## Objectivo

Gerir versões do schema das tabelas cr_*, aplicando ou revertendo migrations de forma controlada.

## Sintaxe

```
/descomplicar:db-migrate <action> [options]
```

| Acção | Descrição |
|-------|-----------|
| `status` | Mostra migrations pendentes e aplicadas |
| `up` | Aplica próxima migration pendente |
| `up --all` | Aplica todas as migrations pendentes |
| `down` | Reverte última migration aplicada |
| `create <name>` | Cria nova migration |

| Opção | Descrição | Default |
|-------|-----------|---------|
| `--all` | Aplicar todas pendentes (com up) | false |
| `--force` | Não pedir confirmação | false |
| `--dry-run` | Mostrar SQL sem executar | false |

## Output Esperado

```
╔════════════════════════════════════════════════════════════╗
║  MIGRATIONS STATUS                                         ║
╠════════════════════════════════════════════════════════════╣
║  ✓ 001_initial_schema.sql          2026-01-15  (1.2s)     ║
║  ✓ 002_add_lsps.sql                2026-01-20  (0.8s)     ║
║  ✓ 003_add_relationships.sql       2026-02-01  (0.5s)     ║
║  ○ 004_add_telemetry.sql           PENDENTE               ║
╠════════════════════════════════════════════════════════════╣
║  Aplicadas: 3 | Pendentes: 1                               ║
╚════════════════════════════════════════════════════════════╝
```

## Estrutura de Migrations

```
migrations/
├── 001_initial_schema.sql          # Tabelas core
├── 002_add_relationships.sql       # Tabelas de relacionamento
├── 003_add_telemetry.sql           # Tabelas de telemetria
├── 004_add_archive_tables.sql      # Tabelas de arquivo
├── 005_add_maintenance_log.sql     # Log de manutenção
└── README.md                       # Documentação
```

### Formato de Migration

```sql
-- Migration: 005_add_maintenance_log
-- Author: Descomplicar®
-- Date: 2026-02-04
-- Description: Adiciona tabela de log de manutenção

-- UP
CREATE TABLE IF NOT EXISTS cr_maintenance_log (
    id INT AUTO_INCREMENT PRIMARY KEY,
    operation VARCHAR(50) NOT NULL,
    table_name VARCHAR(100),
    rows_affected INT DEFAULT 0,
    details JSON,
    executed_by VARCHAR(100) DEFAULT 'system',
    executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    status ENUM('success', 'failed', 'rolled_back') DEFAULT 'success'
);

CREATE INDEX idx_maintenance_operation ON cr_maintenance_log(operation);
CREATE INDEX idx_maintenance_date ON cr_maintenance_log(executed_at);

-- DOWN
DROP TABLE IF EXISTS cr_maintenance_log;
```

## Tabela de Controlo

```sql
CREATE TABLE IF NOT EXISTS cr_migrations (
    id INT AUTO_INCREMENT PRIMARY KEY,
    migration_name VARCHAR(100) NOT NULL UNIQUE,
    applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    checksum VARCHAR(64),
    status ENUM('applied', 'rolled_back', 'failed') DEFAULT 'applied',
    execution_time_ms INT
);
```

## Exemplos

### Ver status
```bash
/descomplicar:db-migrate status
```

Output:
```
╔════════════════════════════════════════════════════════════════╗
║  MIGRATIONS STATUS                                             ║
╠════════════════════════════════════════════════════════════════╣
║  ✓ 001_initial_schema.sql          2026-01-15 10:30  (1.2s)   ║
║  ✓ 002_add_relationships.sql       2026-01-20 14:15  (0.8s)   ║
║  ✓ 003_add_telemetry.sql           2026-02-01 09:00  (0.5s)   ║
║  ○ 004_add_archive_tables.sql      PENDENTE                   ║
║  ○ 005_add_maintenance_log.sql     PENDENTE                   ║
╠════════════════════════════════════════════════════════════════╣
║  Aplicadas: 3 | Pendentes: 2                                   ║
╚════════════════════════════════════════════════════════════════╝
```

### Aplicar próxima
```bash
/descomplicar:db-migrate up
```

Output:
```
╔════════════════════════════════════════════════════════════════╗
║  APPLYING MIGRATION                                            ║
╠════════════════════════════════════════════════════════════════╣
║  Migration: 004_add_archive_tables.sql                         ║
║                                                                ║
║  Creating cr_agent_usage_archive...     ✓                      ║
║  Creating cr_skill_usage_archive...     ✓                      ║
║  Creating cr_mcp_tool_usage_archive...  ✓                      ║
║  Creating cr_lsp_usage_archive...       ✓                      ║
║  Creating indexes...                    ✓                      ║
╠════════════════════════════════════════════════════════════════╣
║  Status: SUCCESS                                               ║
║  Execution time: 1.8s                                          ║
╚════════════════════════════════════════════════════════════════╝
```

### Aplicar todas pendentes
```bash
/descomplicar:db-migrate up --all
```

### Reverter última
```bash
/descomplicar:db-migrate down
```

Output:
```
╔════════════════════════════════════════════════════════════════╗
║  ROLLING BACK MIGRATION                                        ║
╠════════════════════════════════════════════════════════════════╣
║  Migration: 004_add_archive_tables.sql                         ║
║                                                                ║
║  Dropping cr_lsp_usage_archive...       ✓                      ║
║  Dropping cr_mcp_tool_usage_archive...  ✓                      ║
║  Dropping cr_skill_usage_archive...     ✓                      ║
║  Dropping cr_agent_usage_archive...     ✓                      ║
╠════════════════════════════════════════════════════════════════╣
║  Status: ROLLED BACK                                           ║
║  Execution time: 0.3s                                          ║
╚════════════════════════════════════════════════════════════════╝
```

### Criar nova migration
```bash
/descomplicar:db-migrate create add_plugin_versions
```

Output:
```
Created: migrations/006_add_plugin_versions.sql

Edit the file and add your UP and DOWN SQL statements.
```

### Dry-run
```bash
/descomplicar:db-migrate up --dry-run
```

Output:
```
╔════════════════════════════════════════════════════════════════╗
║  DRY RUN - Would execute:                                      ║
╠════════════════════════════════════════════════════════════════╣
║                                                                ║
║  CREATE TABLE IF NOT EXISTS cr_agent_usage_archive (           ║
║      id INT AUTO_INCREMENT PRIMARY KEY,                        ║
║      agent_id INT NOT NULL,                                    ║
║      ...                                                       ║
║  );                                                            ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝
```

## Migrations Incluídas

### 001_initial_schema.sql
- cr_agents, cr_skills, cr_mcps, cr_lsps, cr_sdks
- cr_mcp_tools, cr_plugins, cr_hooks

### 002_add_relationships.sql
- cr_agent_mcps, cr_agent_lsps, cr_agent_skills
- cr_skill_mcps, cr_sdk_agents, cr_sdk_skills, cr_sdk_mcps
- cr_agent_collaborations

### 003_add_telemetry.sql
- cr_agent_usage, cr_skill_usage
- cr_mcp_tool_usage, cr_lsp_usage

### 004_add_archive_tables.sql
- *_archive tables para telemetria

### 005_add_maintenance_log.sql
- cr_maintenance_log, cr_migrations

## Integração

- **Skill**: db-maintenance-manager
- **MCP**: desk-crm-v3
- **Relacionado**: /descomplicar:db-backup (antes de migrations)

## Segurança

- Checksum verificado antes de aplicar
- Rollback automático em caso de erro
- Log completo em cr_migrations
- Backup recomendado antes de migrations destrutivas