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

name, description, layer

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

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