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

name, description

name	description
db-design	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

-- 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

-- 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

-- 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

-- ❌ 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
/**
 * 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

// 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]