claude-plugins/dev-tools/skills/db-design/SKILL.md

---
name: db-design
description: Design e optimização de schemas de base de dados — normalização, índices, planos de migração e particionamento.
---

# Database Design Specialist

Skill para design e optimização de bases de dados seguindo padrões Descomplicar®.

## Quando Usar

- Desenhar schema para novo sistema
- Optimizar queries lentas
- Criar migrations (Laravel, Doctrine, Raw SQL)
- Auditar e optimizar índices
- Planear partitioning/sharding

## Protocolo Obrigatório

### 1. Pesquisa Inicial
```
mcp__memory-supabase__search_memories "database [projecto]"
mcp__wikijs__search_pages "database schema [sistema]"
```

### 2. Verificar Schema Existente
Antes de propor alterações, SEMPRE verificar estrutura actual.

## Princípios de Design

### Normalização
- **OLTP**: Mínimo 3NF (Third Normal Form)
- **OLAP/Reporting**: Desnormalização justificada
- **Híbrido**: Tabelas normalizadas + views materializadas

### Naming Conventions
```sql
-- Tabelas: snake_case, plural
users, order_items, product_categories

-- Colunas: snake_case, singular
created_at, user_id, is_active

-- Primary keys
id (auto-increment ou UUID)

-- Foreign keys: {tabela_singular}_id
user_id, order_id, category_id

-- Índices: idx_{tabela}_{coluna(s)}
idx_orders_customer_id
idx_orders_created_at_status
```

## Performance

### Índices Estratégicos
```sql
-- WHERE frequente
CREATE INDEX idx_users_email ON users(email);

-- JOIN
CREATE INDEX idx_orders_customer_id ON orders(customer_id);

-- ORDER BY
CREATE INDEX idx_products_created_at ON products(created_at DESC);

-- Composto para queries específicas
CREATE INDEX idx_orders_status_date ON orders(status, created_at);
```

### Análise de Queries
```sql
-- SEMPRE usar EXPLAIN antes de optimizar
EXPLAIN ANALYZE
SELECT c.name, COUNT(o.id) as total
FROM customers c
LEFT JOIN orders o ON o.customer_id = c.id
WHERE o.created_at >= '2025-01-01'
GROUP BY c.id
ORDER BY total DESC
LIMIT 100;
```

### Evitar Anti-patterns
```sql
-- ❌ EVITAR
SELECT * FROM orders;                    -- Usar colunas específicas
SELECT ... WHERE YEAR(created_at) = 2025; -- Função impede uso de índice

-- ✅ PREFERIR
SELECT id, customer_id, total FROM orders;
SELECT ... WHERE created_at >= '2025-01-01' AND created_at < '2026-01-01';
```

## Template Migration Laravel

```php
<?php
/**
 * Migration: Create subscriptions table
 *
 * @author Descomplicar® Crescimento Digital
 * @link https://descomplicar.pt
 * @copyright 2025 Descomplicar®
 */

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('subscriptions', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
            $table->foreignId('plan_id')->constrained();
            $table->enum('status', ['active', 'cancelled', 'expired', 'trial']);
            $table->timestamp('trial_ends_at')->nullable();
            $table->timestamp('current_period_start');
            $table->timestamp('current_period_end');
            $table->timestamp('cancelled_at')->nullable();
            $table->timestamps();

            // Índices
            $table->index(['user_id', 'status']);
            $table->index('current_period_end');
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('subscriptions');
    }
};
```

## Segurança

- **Prepared statements**: SEMPRE para queries com input
- **Least privilege**: Utilizadores DB com permissões mínimas
- **Audit logging**: Para tabelas com dados sensíveis
- **Encriptação**: Colunas com PII devem ser encriptadas

## Checklist Schema

### Design
- [ ] Normalização adequada (sem redundância desnecessária)
- [ ] Foreign keys definidas
- [ ] Tipos de dados apropriados
- [ ] Constraints (NOT NULL, UNIQUE, CHECK)
- [ ] Soft deletes onde apropriado (deleted_at)

### Performance
- [ ] Índices em colunas de WHERE
- [ ] Índices em colunas de JOIN
- [ ] Índices compostos onde necessário
- [ ] Evitados índices redundantes
- [ ] EXPLAIN em queries críticas

### Segurança
- [ ] Dados sensíveis identificados
- [ ] Audit trail se necessário
- [ ] Prepared statements em todo código

## Entregáveis Standard

1. DDL completo (CREATE TABLE, INDEX)
2. Diagrama ER se schema complexo
3. Migrations se framework especificado
4. Queries exemplo para operações comuns
5. EXPLAIN de queries críticas

---

## Datasets Dify (Consulta Obrigatória)

Em caso de dúvidas ou para aprofundar conhecimento, consultar os seguintes datasets via MCP:

| Dataset | ID | Prioridade |
|---------|----|-----------:|
| **TI (Tecnologia da Informação)** | `7f63ec0c-6321-488c-b107-980140199850` | 1 |
| **Desenvolvimento de Software** | `e7c7decc-0ded-4351-ab14-b110b3c38ec9` | 1 |
| **AWS (Amazon Web Services)** | `cc7f000a-ad86-49b6-b59b-179e65f8a229` | 2 |

### Como Consultar

```javascript
// Pesquisar optimização MySQL
mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "7f63ec0c-6321-488c-b107-980140199850",
  query: "mysql index optimization slow query"
})

// Padrões de design de bases de dados
mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "e7c7decc-0ded-4351-ab14-b110b3c38ec9",
  query: "database schema design patterns"
})

// RDS e bases de dados AWS
mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "cc7f000a-ad86-49b6-b59b-179e65f8a229",
  query: "RDS aurora postgresql"
})
```

### Quando Consultar

- Antes de desenhar novo schema
- Ao optimizar queries lentas
- Para escolher tipo de índice adequado
- Decidir entre MySQL/PostgreSQL
- Configurar bases de dados em cloud

---
**Versão**: 1.0.0 | **Autor**: Descomplicar®

---


## Quando NÃO Usar

- Para tarefas fora do domínio de especialização desta skill
- Quando outra skill mais específica está disponível
- Para operações que requerem confirmação manual do utilizador


## Exemplos

### Exemplo 1: Uso Básico
```
Input: [descrição da tarefa]
Output: [resultado esperado]
```

### Exemplo 2: Uso Avançado
```
Input: [caso complexo]
Output: [resultado detalhado]
```