Já passaram horas debugando por que sua API retorna `undefined` para dados que deveriam ser de usuário? Ou se perguntaram por que sua consulta "simples" com join está levando 3 segundos para retornar 100 registros? Hoje, quero compartilhar como dominar **SQL Joins com TypeScript Safety** - uma habilidade crítica que combina eficiência de banco de dados com tipagem à prova de balas. Ao final deste artigo, vocês vão entender como escrever queries performáticas, lidar com valores null de forma segura e projetar interfaces que previnem erros em runtime. ## O que são SQL Joins e Por que Type Safety Importa? SQL Joins são o mecanismo que permite combinar dados de múltiplas tabelas baseado em colunas relacionadas. Pensem nisso como conectar blocos de LEGO - cada tabela é um bloco, e os joins são os conectores que permitem construir estruturas complexas. ### Por que Isso Importa Antes de mergulhar na implementação, vamos entender o problema que estamos resolvendo: ```typescript // ❌ Sem joins adequados e tipagem - problemas comuns interface User { id: number; name: string; profilePicture: string; // E se isso não existir? } // Esta query cria problema N+1 e questões de tipo const getUsers = async () => { const users = await db.query('SELECT * FROM users'); for (const user of users) { // Query separada para cada usuário - matador de performance! const profile = await db.query('SELECT * FROM profiles WHERE user_id = ?', [user.id]); user.profilePicture = profile?.url; // Erro de referência nula esperando para acontecer } return users; }; // ✅ Com joins adequados e tipagem - solução limpa interface SafeUser { id: number; name: string; profilePicture: string | null; // Tratamento explícito de null } const getUsersWithProfiles = async (): Promise => { return db.query(` SELECT u.id, u.name, p.url as profilePicture FROM users u LEFT JOIN profiles p ON u.id = p.user_id `); }; ``` Esta transformação elimina queries N+1, torna o tratamento de null explícito e fornece segurança em tempo de compilação. ## Quando Usar Diferentes Tipos de Joins? **Bons casos de uso para cada tipo de join:** - **INNER JOIN**: Quando precisam de registros que existem em ambas as tabelas (usuários com pedidos confirmados) - **LEFT JOIN**: Quando querem todos os registros da tabela principal, mesmo sem correspondências (todos os usuários, com ou sem perfis) - **RIGHT JOIN**: Raramente usado, mas útil para relacionamentos inversos (todos os produtos, mesmo sem categorias) - **FULL OUTER JOIN**: Quando precisam de tudo de ambas as tabelas (trilhas de auditoria completas) **Quando NÃO usar joins complexos:** - **Consultas simples**: Usem queries separadas para dados não relacionados - **Agregações pesadas**: Considerem views materializadas ou caching - **Dados em tempo real**: Às vezes desnormalização é melhor ## Construindo Seu Primeiro Sistema de Query Type-Safe Vamos construir isso passo a passo. Vou mostrar como cada peça funciona e por que cada decisão importa. ### Passo 1: Configuração do Schema do Banco Primeiro, precisamos configurar nosso schema de banco adequadamente. Veja como fazer com integridade referencial: #### Opção 1: PostgreSQL (Recomendado) ```sql -- Tabela users com restrições adequadas CREATE TABLE users ( id SERIAL PRIMARY KEY, email VARCHAR(255) NOT NULL UNIQUE, name VARCHAR(255) NOT NULL, created_at TIMESTAMP DEFAULT NOW() ); -- Tabela profiles com chave estrangeira CREATE TABLE profiles ( id SERIAL PRIMARY KEY, user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE, bio TEXT, avatar_url VARCHAR(500), is_public BOOLEAN DEFAULT false, created_at TIMESTAMP DEFAULT NOW() ); -- Tabela orders para exemplos de join CREATE TABLE orders ( id SERIAL PRIMARY KEY, user_id INTEGER NOT NULL REFERENCES users(id), total_amount DECIMAL(10,2) NOT NULL, status VARCHAR(50) DEFAULT 'pending', created_at TIMESTAMP DEFAULT NOW() ); -- Adicionar índices para performance de join CREATE INDEX idx_profiles_user_id ON profiles(user_id); CREATE INDEX idx_orders_user_id ON orders(user_id); CREATE INDEX idx_orders_status ON orders(status); ``` #### Opção 2: MySQL (Alternativa) ```sql -- Estrutura similar com sintaxe MySQL CREATE TABLE users ( id INT AUTO_INCREMENT PRIMARY KEY, email VARCHAR(255) NOT NULL UNIQUE, name VARCHAR(255) NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE profiles ( id INT AUTO_INCREMENT PRIMARY KEY, user_id INT NOT NULL, bio TEXT, avatar_url VARCHAR(500), is_public BOOLEAN DEFAULT FALSE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ); ``` **Como encontrar/configurar índices ótimos:** - Monitorem logs de queries lentas para identificar gargalos - Usem `EXPLAIN ANALYZE` para entender planos de execução de queries - Indexem colunas de chave estrangeira usadas em joins - Considerem índices compostos para cláusulas where complexas ```typescript // Conexão com banco com tipagem adequada import { Pool, PoolClient } from 'pg'; interface DatabaseConfig { host: string; port: number; database: string; user: string; password: string; max: number; // Tamanho do pool de conexões idleTimeoutMillis: number; } const dbConfig: DatabaseConfig = { host: process.env.DB_HOST || 'localhost', port: parseInt(process.env.DB_PORT || '5432'), database: process.env.DB_NAME || 'myapp', user: process.env.DB_USER || 'postgres', password: process.env.DB_PASSWORD || '', max: 20, // Máximo de conexões no pool idleTimeoutMillis: 30000 }; export const pool = new Pool(dbConfig); ``` **Por que esta configuração funciona tão bem:** - **Restrições de Chave Estrangeira:** Garante integridade dos dados no nível do banco - **Indexação Adequada:** Melhora drasticamente a performance de joins - **Pool de Conexões:** Previne esgotamento de conexões sob carga ### Passo 2: Design de Interfaces TypeScript Agora vamos construir o sistema de tipos central, peça por peça. #### 2.1: Interfaces de Entidade Base Primeiro, vamos criar as interfaces fundamentais: ```typescript // Interface base para todas as entidades do banco interface BaseEntity { id: number; created_at: Date; } // Entidade user central - o que realmente existe no banco interface UserEntity extends BaseEntity { email: string; name: string; } // Entidade profile - pode ser null para usuários interface ProfileEntity extends BaseEntity { user_id: number; bio: string | null; avatar_url: string | null; is_public: boolean; } // Entidade order para exemplos de agregação interface OrderEntity extends BaseEntity { user_id: number; total_amount: number; status: 'pending' | 'completed' | 'cancelled'; } ``` #### 2.2: Interfaces de Resultado de Query Vamos implementar diferentes tipos de resultado de query, explicando cada decisão: ```typescript // Usuário com perfil opcional - para resultados de LEFT JOIN interface UserWithProfile { id: number; email: string; name: string; created_at: Date; // Campos de profile podem ser null quando LEFT JOIN não retorna match profile_id: number | null; bio: string | null; avatar_url: string | null; is_public: boolean | null; profile_created_at: Date | null; } // Usuário com perfil garantido - para resultados de INNER JOIN interface UserWithRequiredProfile { id: number; email: string; name: string; created_at: Date; // Campos de profile são garantidos de existir profile_id: number; bio: string | null; // Ainda pode ser null se a coluna permitir avatar_url: string | null; is_public: boolean; profile_created_at: Date; } // Dados agregados de usuário - para queries complexas interface UserWithStats { id: number; name: string; email: string; total_orders: number; total_spent: number; last_order_date: Date | null; has_profile: boolean; } ``` **Por que esta implementação?** - **Tipos Null Explícitos:** Torna valores potencialmente null óbvios em tempo de compilação - **Interfaces Semânticas:** Interfaces diferentes para tipos diferentes de query previnem uso incorreto - **Design Composível:** Pode construir tipos complexos a partir de entidades base #### 2.3: Interface de Query Builder Agora vamos adicionar construção de query type-safe: ```typescript // Wrapper genérico de resultado de query interface QueryResult { data: T[]; count: number; page?: number; limit?: number; } // Opções de query para filtragem e paginação interface QueryOptions { limit?: number; offset?: number; orderBy?: string; orderDirection?: 'ASC' | 'DESC'; filters?: Record; } // Query builder type-safe class TypeSafeQueryBuilder { private query: string = ''; private params: any[] = []; private paramCount: number = 0; select(fields: string[]): this { this.query = `SELECT ${fields.join(', ')}`; return this; } from(table: string): this { this.query += ` FROM ${table}`; return this; } leftJoin(table: string, condition: string): this { this.query += ` LEFT JOIN ${table} ON ${condition}`; return this; } innerJoin(table: string, condition: string): this { this.query += ` INNER JOIN ${table} ON ${condition}`; return this; } where(condition: string, value?: any): this { if (this.query.includes('WHERE')) { this.query += ` AND ${condition}`; } else { this.query += ` WHERE ${condition}`; } if (value !== undefined) { this.paramCount++; this.query = this.query.replace('?', `$${this.paramCount}`); this.params.push(value); } return this; } orderBy(field: string, direction: 'ASC' | 'DESC' = 'ASC'): this { this.query += ` ORDER BY ${field} ${direction}`; return this; } limit(count: number): this { this.paramCount++; this.query += ` LIMIT $${this.paramCount}`; this.params.push(count); return this; } build(): { query: string; params: any[] } { return { query: this.query, params: this.params }; } } ``` **Diferenças importantes:** - **Binding de Parâmetros:** Previne injeção SQL através de queries parametrizadas - **Interface Fluente:** Métodos encadeáveis para construção legível de queries #### 2.4: Implementação do Padrão Repository ```typescript // Interface genérica de repository interface Repository { findById(id: number): Promise; findMany(options?: QueryOptions): Promise>; create(data: Omit): Promise; update(id: number, data: Partial): Promise; delete(id: number): Promise; } // Repository de usuário com métodos de join class UserRepository implements Repository { constructor(private db: Pool) {} async findById(id: number): Promise { const { rows } = await this.db.query( 'SELECT * FROM users WHERE id = $1', [id] ); return rows[0] || null; } async findWithProfile(id: number): Promise { const builder = new TypeSafeQueryBuilder(); const { query, params } = builder .select([ 'u.id', 'u.email', 'u.name', 'u.created_at', 'p.id as profile_id', 'p.bio', 'p.avatar_url', 'p.is_public', 'p.created_at as profile_created_at' ]) .from('users u') .leftJoin('profiles p', 'u.id = p.user_id') .where('u.id = ?', id) .build(); const { rows } = await this.db.query(query, params); return rows[0] || null; } async findMany(options: QueryOptions = {}): Promise> { const { limit = 50, offset = 0, orderBy = 'created_at', orderDirection = 'DESC' } = options; const builder = new TypeSafeQueryBuilder(); const { query, params } = builder .select(['*']) .from('users') .orderBy(orderBy, orderDirection) .limit(limit) .build(); const { rows } = await this.db.query(query, params); // Obter contagem total para paginação const countResult = await this.db.query('SELECT COUNT(*) FROM users'); const count = parseInt(countResult.rows[0].count); return { data: rows, count, page: Math.floor(offset / limit) + 1, limit }; } } ``` **Padrão repository explicado:** - **Separação de Responsabilidades:** Lógica de banco separada da lógica de negócio - **Testabilidade:** Fácil de mockar para testes unitários - **Type Safety:** Cada método retorna resultados adequadamente tipados ### Passo 3: Padrões Avançados de Join e Agregação ```typescript // Métodos de query avançados para cenários complexos class AdvancedUserRepository extends UserRepository { // Obter usuários com estatísticas de pedidos async findUsersWithOrderStats(options: QueryOptions = {}): Promise> { const { limit = 50, offset = 0 } = options; const query = ` SELECT u.id, u.name, u.email, COALESCE(COUNT(o.id), 0) as total_orders, COALESCE(SUM(o.total_amount), 0) as total_spent, MAX(o.created_at) as last_order_date, CASE WHEN p.id IS NOT NULL THEN true ELSE false END as has_profile FROM users u LEFT JOIN orders o ON u.id = o.user_id AND o.status = 'completed' LEFT JOIN profiles p ON u.id = p.user_id GROUP BY u.id, u.name, u.email, p.id ORDER BY total_spent DESC LIMIT $1 OFFSET $2 `; const { rows } = await this.db.query(query, [limit, offset]); const countQuery = ` SELECT COUNT(DISTINCT u.id) as count FROM users u LEFT JOIN orders o ON u.id = o.user_id LEFT JOIN profiles p ON u.id = p.user_id `; const countResult = await this.db.query(countQuery); return { data: rows.map(row => ({ ...row, total_orders: parseInt(row.total_orders), total_spent: parseFloat(row.total_spent) })), count: parseInt(countResult.rows[0].count) }; } // Filtragem complexa com múltiplos joins async findActiveUsersWithProfiles(filters: { hasOrders?: boolean; minOrderAmount?: number; profileRequired?: boolean; } = {}): Promise { let query = ` SELECT DISTINCT u.id, u.email, u.name, u.created_at, p.id as profile_id, p.bio, p.avatar_url, p.is_public, p.created_at as profile_created_at FROM users u `; const params: any[] = []; let paramCount = 0; // Join dinâmico baseado em filtros if (filters.profileRequired) { query += ` INNER JOIN profiles p ON u.id = p.user_id`; } else { query += ` LEFT JOIN profiles p ON u.id = p.user_id`; } if (filters.hasOrders || filters.minOrderAmount) { query += ` INNER JOIN orders o ON u.id = o.user_id`; } const conditions: string[] = []; if (filters.minOrderAmount) { paramCount++; conditions.push(`o.total_amount >= $${paramCount}`); params.push(filters.minOrderAmount); } if (conditions.length > 0) { query += ` WHERE ${conditions.join(' AND ')}`; } query += ` ORDER BY u.created_at DESC`; const { rows } = await this.db.query(query, params); return rows; } } ``` O repository avançado demonstra como requisitos de negócio complexos se traduzem em SQL eficiente com tipagem adequada. ## Um Exemplo Mais Complexo: Analytics de Pedidos E-commerce Vamos construir algo mais realista - um sistema de analytics de pedidos que demonstra padrões avançados de join, agregação e tratamento de null: ### Entendendo o Problema Antes de mergulhar no código, vamos entender o que estamos construindo: ```typescript // ❌ Abordagem ingênua - por que isso não funciona bem const getOrderAnalytics = async (userId: number) => { const user = await db.query('SELECT * FROM users WHERE id = $1', [userId]); const orders = await db.query('SELECT * FROM orders WHERE user_id = $1', [userId]); const profile = await db.query('SELECT * FROM profiles WHERE user_id = $1', [userId]); // Múltiplas queries, sem agregação, questões de tipo return { user: user.rows[0], // Pode ser undefined orders: orders.rows, profile: profile.rows[0], // Pode ser undefined totalSpent: orders.rows.reduce((sum, order) => sum + order.total_amount, 0) }; }; // ✅ Nossa abordagem melhorada - o que vamos construir interface OrderAnalytics { user: { id: number; name: string; email: string; }; profile: { bio: string | null; avatar_url: string | null; is_public: boolean; } | null; orderStats: { totalOrders: number; totalSpent: number; averageOrderValue: number; lastOrderDate: Date | null; favoriteCategory: string | null; }; recentOrders: Array<{ id: number; total_amount: number; status: string; created_at: Date; itemCount: number; }>; } ``` ### Implementação Passo a Passo #### Fase 1: Schema Estendido para Analytics ```sql -- Adicionar categorias de produtos e itens de pedido para analytics mais ricos CREATE TABLE categories ( id SERIAL PRIMARY KEY, name VARCHAR(255) NOT NULL, slug VARCHAR(255) NOT NULL UNIQUE ); CREATE TABLE products ( id SERIAL PRIMARY KEY, name VARCHAR(255) NOT NULL, price DECIMAL(10,2) NOT NULL, category_id INTEGER REFERENCES categories(id), created_at TIMESTAMP DEFAULT NOW() ); CREATE TABLE order_items ( id SERIAL PRIMARY KEY, order_id INTEGER NOT NULL REFERENCES orders(id) ON DELETE CASCADE, product_id INTEGER NOT NULL REFERENCES products(id), quantity INTEGER NOT NULL DEFAULT 1, unit_price DECIMAL(10,2) NOT NULL, created_at TIMESTAMP DEFAULT NOW() ); -- Índices de performance para queries de analytics CREATE INDEX idx_order_items_order_id ON order_items(order_id); CREATE INDEX idx_order_items_product_id ON order_items(product_id); CREATE INDEX idx_products_category_id ON products(category_id); CREATE INDEX idx_orders_created_at ON orders(created_at); CREATE INDEX idx_orders_user_status ON orders(user_id, status); ``` **Quebrando isso:** - **Estrutura Normalizada:** Previne duplicação de dados e mantém consistência - **Índices Estratégicos:** Otimiza queries analíticas comuns - **Integridade Referencial:** Deletes em cascata mantêm consistência dos dados #### Fase 2: Interface de Analytics Complexa ```typescript // Interfaces aprimoradas para analytics abrangentes interface ProductAnalytics { id: number; name: string; category: string; totalSold: number; revenue: number; } interface CategoryAnalytics { id: number; name: string; orderCount: number; revenue: number; avgOrderValue: number; } interface OrderAnalyticsDetailed extends OrderAnalytics { categoryBreakdown: CategoryAnalytics[]; topProducts: ProductAnalytics[]; orderTrends: { month: string; orderCount: number; revenue: number; }[]; } // Repository para analytics avançados class OrderAnalyticsRepository { constructor(private db: Pool) {} async getComprehensiveAnalytics(userId: number): Promise { // Query complexa única ao invés de múltiplas idas e vindas const analyticsQuery = ` WITH user_orders AS ( SELECT o.id, o.total_amount, o.status, o.created_at, COUNT(oi.id) as item_count FROM orders o LEFT JOIN order_items oi ON o.id = oi.order_id WHERE o.user_id = $1 AND o.status = 'completed' GROUP BY o.id, o.total_amount, o.status, o.created_at ), order_stats AS ( SELECT COUNT(*) as total_orders, COALESCE(SUM(total_amount), 0) as total_spent, COALESCE(AVG(total_amount), 0) as avg_order_value, MAX(created_at) as last_order_date FROM user_orders ), category_stats AS ( SELECT c.id, c.name, COUNT(o.id) as order_count, SUM(o.total_amount) as revenue, AVG(o.total_amount) as avg_order_value FROM orders o JOIN order_items oi ON o.id = oi.order_id JOIN products p ON oi.product_id = p.id JOIN categories c ON p.category_id = c.id WHERE o.user_id = $1 AND o.status = 'completed' GROUP BY c.id, c.name ORDER BY revenue DESC ) SELECT u.id as user_id, u.name as user_name, u.email as user_email, p.bio, p.avatar_url, p.is_public, os.total_orders, os.total_spent, os.avg_order_value, os.last_order_date, COALESCE( (SELECT c.name FROM category_stats c ORDER BY c.revenue DESC LIMIT 1), NULL ) as favorite_category FROM users u LEFT JOIN profiles p ON u.id = p.user_id CROSS JOIN order_stats os WHERE u.id = $1 `; const { rows } = await this.db.query(analyticsQuery, [userId]); if (rows.length === 0) return null; const mainData = rows[0]; // Obter pedidos recentes separadamente para tipagem mais limpa const recentOrdersQuery = ` SELECT o.id, o.total_amount, o.status, o.created_at, COUNT(oi.id) as item_count FROM orders o LEFT JOIN order_items oi ON o.id = oi.order_id WHERE o.user_id = $1 GROUP BY o.id, o.total_amount, o.status, o.created_at ORDER BY o.created_at DESC LIMIT 10 `; const recentOrdersResult = await this.db.query(recentOrdersQuery, [userId]); // Obter breakdown de categorias const categoryQuery = ` SELECT c.id, c.name, COUNT(o.id) as order_count, SUM(o.total_amount) as revenue, AVG(o.total_amount) as avg_order_value FROM orders o JOIN order_items oi ON o.id = oi.order_id JOIN products p ON oi.product_id = p.id JOIN categories c ON p.category_id = c.id WHERE o.user_id = $1 AND o.status = 'completed' GROUP BY c.id, c.name ORDER BY revenue DESC `; const categoryResult = await this.db.query(categoryQuery, [userId]); return { user: { id: mainData.user_id, name: mainData.user_name, email: mainData.user_email }, profile: mainData.bio !== null ? { bio: mainData.bio, avatar_url: mainData.avatar_url, is_public: mainData.is_public } : null, orderStats: { totalOrders: parseInt(mainData.total_orders), totalSpent: parseFloat(mainData.total_spent), averageOrderValue: parseFloat(mainData.avg_order_value), lastOrderDate: mainData.last_order_date, favoriteCategory: mainData.favorite_category }, recentOrders: recentOrdersResult.rows.map(row => ({ id: row.id, total_amount: parseFloat(row.total_amount), status: row.status, created_at: row.created_at, itemCount: parseInt(row.item_count) })), categoryBreakdown: categoryResult.rows.map(row => ({ id: row.id, name: row.name, orderCount: parseInt(row.order_count), revenue: parseFloat(row.revenue), avgOrderValue: parseFloat(row.avg_order_value) })), topProducts: [], // Seria implementado de forma similar orderTrends: [] // Seria implementado de forma similar }; } } ``` **Por que cláusulas "WITH" funcionam aqui:** - **Performance:** Uma única ida ao banco ao invés de múltiplas queries - **Consistência:** Todos os dados vêm do mesmo snapshot de transação - **Legibilidade:** Lógica complexa quebrada em subqueries nomeadas #### Fase 3: Tratamento de Erros e Type Guards ```typescript // Type guards para segurança em runtime function isValidOrderAnalytics(data: any): data is OrderAnalytics { return ( data && typeof data.user === 'object' && typeof data.user.id === 'number' && typeof data.orderStats === 'object' && typeof data.orderStats.totalOrders === 'number' && Array.isArray(data.recentOrders) ); } // Wrapper de tratamento de erros class SafeOrderAnalyticsRepository { constructor(private repository: OrderAnalyticsRepository) {} async getAnalyticsSafely(userId: number): Promise<{ success: boolean; data?: OrderAnalyticsDetailed; error?: string; }> { try { if (!Number.isInteger(userId) || userId <= 0) { return { success: false, error: 'ID de usuário inválido fornecido' }; } const analytics = await this.repository.getComprehensiveAnalytics(userId); if (!analytics) { return { success: false, error: 'Usuário não encontrado ou não possui dados de pedidos' }; } if (!isValidOrderAnalytics(analytics)) { return { success: false, error: 'Estrutura de dados de analytics inválida' }; } return { success: true, data: analytics }; } catch (error) { console.error('Query de analytics falhou:', error); return { success: false, error: 'Falha ao buscar dados de analytics' }; } } } ``` **Por que esta arquitetura é poderosa:** - **Validação Runtime:** Type guards capturam inconsistências de dados - **Degradação Graciosa:** Sistema continua funcionando mesmo com falhas parciais - **Suporte para Debug:** Mensagens de erro detalhadas ajudam na resolução de problemas ## SQL Joins e TypeScript com TypeScript Para usuários TypeScript, veja como tornar tudo type-safe no nível do banco: ### Configurando Tipos ```typescript // types/database.ts export interface DatabaseSchema { users: UserEntity; profiles: ProfileEntity; orders: OrderEntity; categories: CategoryEntity; products: ProductEntity; order_items: OrderItemEntity; } // Tipos utilitários para resultados de join export type LeftJoinResult = T & { [K in keyof U]: U[K] | null; }; export type InnerJoinResult = T & U; // Tipos de resultado de query export type UserWithOptionalProfile = LeftJoinResult< UserEntity, Omit >; export type UserWithRequiredProfile = InnerJoinResult< UserEntity, Omit >; // Tipos de resultado de agregação export type AggregatedQuery> = T & A; export type UserWithOrderCount = AggregatedQuery< UserEntity, { order_count: number; total_spent: number } >; ``` **Benefícios de type safety:** - **Verificações em Tempo de Compilação:** Captura incompatibilidades de join antes do runtime - **Suporte ao IntelliSense:** Auto-completar no IDE para todos os campos ### Implementação com Tipagem Adequada ```typescript // Executor de query genérico com tipagem adequada class TypedQueryExecutor { constructor(private db: Pool) {} async executeQuery( query: string, params: any[] = [] ): Promise { try { const { rows } = await this.db.query(query, params); return rows; } catch (error) { console.error('Execução de query falhou:', { query, params, error }); throw new Error(`Query de banco falhou: ${error.message}`); } } async executeQuerySingle( query: string, params: any[] = [] ): Promise { const results = await this.executeQuery(query, params); return results[0] || null; } // Métodos de join type-safe async leftJoin( mainTable: string, joinTable: string, condition: string, where?: string, params: any[] = [] ): Promise[]> { const query = ` SELECT * FROM ${mainTable} main LEFT JOIN ${joinTable} joined ON ${condition} ${where ? `WHERE ${where}` : ''} `; return this.executeQuery>(query, params); } async innerJoin( mainTable: string, joinTable: string, condition: string, where?: string, params: any[] = [] ): Promise[]> { const query = ` SELECT * FROM ${mainTable} main INNER JOIN ${joinTable} joined ON ${condition} ${where ? `WHERE ${where}` : ''} `; return this.executeQuery>(query, params); } } // Uso com type safety completa const executor = new TypedQueryExecutor(pool); // TypeScript sabe que isso retorna UserWithOptionalProfile[] const usersWithProfiles = await executor.leftJoin( 'users', 'profiles', 'main.id = joined.user_id', 'main.created_at > $1', [new Date('2023-01-01')] ); // TypeScript sabe que campos de profile podem ser null usersWithProfiles.forEach(user => { console.log(user.name); // ✅ Sempre disponível console.log(user.bio?.length || 0); // ✅ Acesso seguro a null // console.log(user.bio.length); // ❌ Erro TypeScript - bio pode ser null }); ``` ### Padrões Avançados TypeScript ```typescript // Tipos condicionais para construção dinâmica de query type QueryFields = { [K in keyof T]: T[K]; }; type SelectFields = Pick; // Padrão builder com type safety class TypeSafeQueryBuilder { private selectedFields: (keyof T)[] = []; private tableName: string = ''; private joins: string[] = []; private whereConditions: string[] = []; private params: any[] = []; select(fields: K[]): TypeSafeQueryBuilder> { this.selectedFields = fields; return this as any; } from(table: string): this { this.tableName = table; return this; } where( field: K, operator: '=' | '>' | '<' | '>=' | '<=' | '!=', value: T[K] ): this { this.whereConditions.push(`${String(field)} ${operator} $${this.params.length + 1}`); this.params.push(value); return this; } async execute(): Promise[]> { const query = [ `SELECT ${this.selectedFields.join(', ')}`, `FROM ${this.tableName}`, ...this.joins, this.whereConditions.length > 0 ? `WHERE ${this.whereConditions.join(' AND ')}` : '' ].filter(Boolean).join(' '); const { rows } = await pool.query(query, this.params); return rows; } } // Uso com validação de campos em tempo de compilação const users = await new TypeSafeQueryBuilder() .select(['id', 'name', 'email']) // ✅ Apenas campos válidos de UserEntity .from('users') .where('created_at', '>', new Date('2023-01-01')) .execute(); // TypeScript sabe que o resultado só tem campos id, name, email users.forEach(user => { console.log(user.name); // ✅ Disponível // console.log(user.password); // ❌ Erro TypeScript - não foi selecionado }); ``` ## Padrões Avançados e Melhores Práticas ### 1. Tratamento de Null Otimista vs Pessimista **O que resolve:** Diferentes estratégias para lidar com dados potencialmente null **Como funciona:** Escolham sua estratégia de tratamento de null baseada na probabilidade dos dados ```typescript // Abordagem pessimista - assumir que dados podem estar faltando interface PessimisticUser { id: number; name: string | null; email: string | null; profile?: { bio: string | null; avatar: string | null; } | null; } function renderPessimisticUser(user: PessimisticUser) { return `

${user.name || 'Usuário Desconhecido'}

${user.email || 'Nenhum email fornecido'}

${user.profile?.bio ? `

${user.profile.bio}

` : ''}

`; } // Abordagem otimista - assumir que dados existem, lidar com exceções interface OptimisticUser { id: number; name: string; email: string; profile: { bio: string; avatar: string; }; } function renderOptimisticUser(user: OptimisticUser) { try { return `

${user.name}

${user.email}

${user.profile.bio}

`; } catch (error) { return renderFallbackUser(user.id); } } // Abordagem híbrida - explícita sobre o que pode ser null interface HybridUser { id: number; name: string; // Obrigatório pelas regras de negócio email: string; // Obrigatório pelas regras de negócio profile: { bio: string | null; // Usuário pode não ter escrito bio avatar: string | null; // Usuário pode não ter feito upload de avatar } | null; // Usuário pode não ter criado perfil } ``` **Quando usar:** Pessimista para dados externos, otimista para APIs internas, híbrida para cenários mistos ### 2. Estratégia de Cache de Resultado de Query **O problema:** Queries caras de join executando repetidamente **A solução:** Cache inteligente com invalidação ```typescript interface CacheOptions { ttl: number; // Time to live em segundos tags: string[]; // Tags de invalidação de cache } class CachedQueryExecutor extends TypedQueryExecutor { private cache = new Map(); async executeQueryCached( query: string, params: any[] = [], options: CacheOptions ): Promise { const cacheKey = this.generateCacheKey(query, params); const cached = this.cache.get(cacheKey); if (cached && Date.now() < cached.expires) { return cached.data; } const result = await this.executeQuery(query, params); this.cache.set(cacheKey, { data: result, expires: Date.now() + (options.ttl * 1000), tags: options.tags }); return result; } invalidateByTag(tag: string): void { for (const [key, value] of this.cache.entries()) { if (value.tags.includes(tag)) { this.cache.delete(key); } } } private generateCacheKey(query: string, params: any[]): string { return `${query}:${JSON.stringify(params)}`; } } // Uso com invalidação automática de cache const cachedExecutor = new CachedQueryExecutor(pool); // Cache dados de usuário por 5 minutos const users = await cachedExecutor.executeQueryCached( 'SELECT * FROM users LEFT JOIN profiles ON users.id = profiles.user_id', [], { ttl: 300, tags: ['users', 'profiles'] } ); // Quando dados de usuário mudam, invalidar caches relacionados await updateUserProfile(userId, profileData); cachedExecutor.invalidateByTag('profiles'); ``` **Benefícios:** Reduz drasticamente a carga do banco para aplicações com muita leitura ### 3. Otimização de Performance de Join **Caso de uso:** Aplicações de grande escala com requisitos complexos de join ```typescript // Analisador de performance de query class QueryPerformanceAnalyzer { async analyzeQuery(query: string, params: any[] = []): Promise<{ executionTime: number; rowsExamined: number; suggestions: string[]; }> { const startTime = Date.now(); // Usar EXPLAIN ANALYZE para obter plano de execução const explainQuery = `EXPLAIN (ANALYZE, BUFFERS) ${query}`; const { rows: explainRows } = await pool.query(explainQuery, params); const executionTime = Date.now() - startTime; // Analisar plano de execução para sugestões de otimização const suggestions = this.parseExecutionPlan(explainRows); return { executionTime, rowsExamined: this.extractRowsExamined(explainRows), suggestions }; } private parseExecutionPlan(plan: any[]): string[] { const suggestions: string[] = []; const planText = plan.map(row => row['QUERY PLAN']).join('\n'); if (planText.includes('Seq Scan')) { suggestions.push('Considerem adicionar índices para scans sequenciais'); } if (planText.includes('Hash Join') && planText.includes('large table')) { suggestions.push('Considerem quebrar joins grandes em queries menores'); } if (planText.includes('Sort') && planText.includes('external merge')) { suggestions.push('Aumentem work_mem ou adicionem índice ORDER BY'); } return suggestions; } private extractRowsExamined(plan: any[]): number { const planText = plan.map(row => row['QUERY PLAN']).join('\n'); const match = planText.match(/rows=(\d+)/); return match ? parseInt(match[1]) : 0; } } // Sistema de recomendação de índices class IndexRecommendationSystem { async recommendIndexes( slowQueries: Array<{ query: string; params: any[]; frequency: number }> ): Promise { const recommendations: string[] = []; for (const slowQuery of slowQueries) { const analysis = await this.analyzeQueryForIndexes(slowQuery.query); recommendations.push(...analysis); } return this.deduplicateRecommendations(recommendations); } private async analyzeQueryForIndexes(query: string): Promise { const recommendations: string[] = []; // Analisar cláusulas WHERE const whereMatches = query.match(/WHERE\s+([^ORDER|GROUP|LIMIT]+)/gi); if (whereMatches) { for (const whereClause of whereMatches) { const columns = this.extractColumnsFromWhere(whereClause); for (const column of columns) { recommendations.push(`CREATE INDEX idx_${column.table}_${column.name} ON ${column.table}(${column.name});`); } } } // Analisar condições de JOIN const joinMatches = query.match(/JOIN\s+\w+\s+ON\s+([^WHERE|ORDER|GROUP|LIMIT]+)/gi); if (joinMatches) { for (const joinClause of joinMatches) { const columns = this.extractColumnsFromJoin(joinClause); for (const column of columns) { recommendations.push(`CREATE INDEX idx_${column.table}_${column.name} ON ${column.table}(${column.name});`); } } } return recommendations; } } ``` **Trade-offs:** Monitoramento de performance adiciona overhead mas previne regressões de performance ### 4. Gerenciamento de Transações para Operações Complexas **Contexto:** Operações complexas precisam de garantias de atomicidade ```typescript // Wrapper de transação com TypeScript safety class TransactionManager { constructor(private db: Pool) {} async withTransaction( operation: (client: PoolClient) => Promise ): Promise { const client = await this.db.connect(); try { await client.query('BEGIN'); const result = await operation(client); await client.query('COMMIT'); return result; } catch (error) { await client.query('ROLLBACK'); throw error; } finally { client.release(); } } // Exemplo de operação complexa async transferOrderBetweenUsers( fromUserId: number, toUserId: number, orderId: number ): Promise { await this.withTransaction(async (client) => { // Verificar se pedido pertence ao fromUser const { rows: orderRows } = await client.query( 'SELECT user_id FROM orders WHERE id = $1 FOR UPDATE', [orderId] ); if (orderRows.length === 0) { throw new Error('Pedido não encontrado'); } if (orderRows[0].user_id !== fromUserId) { throw new Error('Pedido não pertence ao usuário origem'); } // Verificar se usuário alvo existe const { rows: userRows } = await client.query( 'SELECT id FROM users WHERE id = $1', [toUserId] ); if (userRows.length === 0) { throw new Error('Usuário alvo não encontrado'); } // Atualizar propriedade do pedido await client.query( 'UPDATE orders SET user_id = $1 WHERE id = $2', [toUserId, orderId] ); // Registrar a transferência await client.query( 'INSERT INTO order_transfers (order_id, from_user_id, to_user_id, transferred_at) VALUES ($1, $2, $3, NOW())', [orderId, fromUserId, toUserId] ); }); } } ``` **Caso de uso:** Qualquer operação que modifica múltiplos registros relacionados ## Armadilhas Comuns para Evitar ### 1. Problema de Query N+1 **O problema:** Carregar dados relacionados em loops ao invés de joins ```typescript // ❌ Não façam isso - problema de query N+1 async function getUsersWithOrdersBad(): Promise { const users = await db.query('SELECT * FROM users'); for (const user of users.rows) { // Isso cria N queries adicionais! const orders = await db.query('SELECT * FROM orders WHERE user_id = $1', [user.id]); user.orders = orders.rows; } return users.rows; } // ✅ Façam isso - query única com agregação adequada async function getUsersWithOrdersGood(): Promise { const query = ` SELECT u.id, u.name, u.email, COALESCE( JSON_AGG( JSON_BUILD_OBJECT( 'id', o.id, 'total_amount', o.total_amount, 'status', o.status, 'created_at', o.created_at ) ) FILTER (WHERE o.id IS NOT NULL), '[]' ) as orders FROM users u LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.id, u.name, u.email ORDER BY u.created_at DESC `; const { rows } = await db.query(query); return rows.map(row => ({ ...row, orders: JSON.parse(row.orders) })); } ``` **Por que isso importa:** Queries N+1 podem deixar sua API 100x mais lenta conforme os dados crescem ### 2. Tratamento Incorreto de Null em Joins **Erro comum:** Não considerar campos nullable em LEFT JOINs **Por que acontece:** Desenvolvedores esquecem que LEFT JOIN pode retornar valores null ```typescript // ❌ Exemplo problemático - erros de runtime esperando para acontecer interface BadUserProfile { user_id: number; name: string; bio: string; // Deveria ser nullable! avatar_url: string; // Deveria ser nullable! is_public: boolean; // Deveria ser nullable! } async function getBadUserProfiles(): Promise { const query = ` SELECT u.id as user_id, u.name, p.bio, p.avatar_url, p.is_public FROM users u LEFT JOIN profiles p ON u.id = p.user_id `; const { rows } = await db.query(query); // Isso vai quebrar quando campos de profile forem null! return rows.map(row => ({ user_id: row.user_id, name: row.name, bio: row.bio.toLowerCase(), // ❌ Quebra se null avatar_url: row.avatar_url || '/default-avatar.png', is_public: row.is_public })); } // ✅ Solução - tratamento explícito de null interface GoodUserProfile { user_id: number; name: string; bio: string | null; avatar_url: string | null; is_public: boolean | null; } async function getGoodUserProfiles(): Promise { const query = ` SELECT u.id as user_id, u.name, p.bio, p.avatar_url, p.is_public FROM users u LEFT JOIN profiles p ON u.id = p.user_id `; const { rows } = await db.query(query); return rows.map(row => ({ user_id: row.user_id, name: row.name, bio: row.bio, avatar_url: row.avatar_url, is_public: row.is_public })); } // Função helper para operações seguras com string function safeStringOperation(value: string | null, operation: (str: string) => string): string | null { return value ? operation(value) : null; } // Uso const profiles = await getGoodUserProfiles(); profiles.forEach(profile => { const processedBio = safeStringOperation(profile.bio, bio => bio.toLowerCase()); console.log(processedBio); // Seguro! }); ``` **Prevenção:** Sempre marquem campos de LEFT JOIN como nullable em interfaces TypeScript ### 3. Índice Faltando em Chaves Estrangeiras **A armadilha:** Esquecer de indexar colunas de chave estrangeira usadas em joins ```sql -- ❌ Evitem este padrão - índices de chave estrangeira faltando CREATE TABLE orders ( id SERIAL PRIMARY KEY, user_id INTEGER NOT NULL REFERENCES users(id), product_id INTEGER NOT NULL REFERENCES products(id), created_at TIMESTAMP DEFAULT NOW() ); -- Sem índices em user_id ou product_id = joins lentos! -- ✅ Abordagem preferida - chaves estrangeiras indexadas CREATE TABLE orders ( id SERIAL PRIMARY KEY, user_id INTEGER NOT NULL REFERENCES users(id), product_id INTEGER NOT NULL REFERENCES products(id), created_at TIMESTAMP DEFAULT NOW() ); -- Índices essenciais para performance de join CREATE INDEX idx_orders_user_id ON orders(user_id); CREATE INDEX idx_orders_product_id ON orders(product_id); CREATE INDEX idx_orders_created_at ON orders(created_at); -- Índice composto para padrões comuns de query CREATE INDEX idx_orders_user_status ON orders(user_id, status) WHERE status IN ('pending', 'completed'); ``` **Sinais de alerta:** Tempo de execução de query aumenta drasticamente com o tamanho da tabela ## Quando NÃO Usar Joins Complexos Não usem joins complexos quando: - **Consultas Simples:** Queries de tabela única são frequentemente mais rápidas e simples - **Dados em Tempo Real:** Tabelas desnormalizadas podem ser melhores para leituras de alta frequência - **Operações Cross-Database:** Às vezes queries separadas são necessárias ```typescript // ❌ Exagero para cenários simples async function getSimpleUserInfo(userId: number) { // Join complexo para lookup simples de dados const query = ` SELECT u.id, u.name, u.email, p.bio FROM users u LEFT JOIN profiles p ON u.id = p.user_id WHERE u.id = $1 `; const { rows } = await db.query(query, [userId]); return rows[0]; } // ✅ Solução simples é melhor async function getSimpleUserInfoBetter(userId: number) { // Às vezes simples é melhor const user = await db.query('SELECT id, name, email FROM users WHERE id = $1', [userId]); return user.rows[0]; } ``` **Framework de decisão:** Comecem simples, adicionem complexidade apenas quando tiverem requisitos de performance ou funcionalidade ## SQL Joins vs Soluções Alternativas ### Quando SQL Joins Brilham **SQL Joins são ótimos para:** - **Dados Relacionais:** Quando têm schemas de banco normalizados com relacionamentos claros - **Filtragem Complexa:** Quando precisam filtrar através de múltiplas tabelas simultaneamente - **Agregações:** Quando precisam computar estatísticas através de tabelas relacionadas - **Conformidade ACID:** Quando precisam de garantias transacionais através de dados relacionados ### Quando Considerar Alternativas **Considerem alternativas quando precisam de:** - **Arquitetura de Microserviços** → **Composição de API:** Quando dados estão distribuídos entre serviços - **Modelos de Dados NoSQL** → **Bancos de Documentos:** Quando têm dados naturalmente aninhados e desnormalizados - **Performance em Tempo Real** → **Caching/Redis:** Quando precisam de tempos de resposta sub-milissegundo - **Escala Massiva** → **Data Warehousing:** Quando lidam com analytics em escala de petabytes ### Matriz de Comparação | Recurso | SQL Joins | Composição API | Banco Documentos | Camada Cache | |---------|-----------|----------------|------------------|--------------| | **Performance** | Boa com índices | Overhead de rede | Leituras muito rápidas | Mais rápida | | **Consistência** | ACID garantido | Eventualmente consistente | Eventualmente consistente | Complexidade de invalidação de cache | | **Escalabilidade** | Escala vertical | Escala horizontal | Escala horizontal | Limitado por memória | | **Complexidade** | Média | Alta | Baixa | Média | | **Tempo Real** | Bom | Variável | Excelente | Excelente | ## Fechando SQL Joins com TypeScript Safety é uma combinação poderosa que pode transformar sua camada de acesso a dados. Traz type safety, otimização de performance e manutenibilidade para suas operações de banco. **Principais conclusões:** - **Tipem Tudo:** Tornem valores null explícitos em suas interfaces para prevenir erros de runtime - **Indexem Estrategicamente:** Chaves estrangeiras e colunas de cláusula WHERE devem sempre ser indexadas - **Lidem com Null de Forma Segura:** Usem LEFT JOINs responsavelmente com verificação adequada de null - **Otimizem Progressivamente:** Comecem com queries simples, adicionem complexidade apenas quando necessário - **Monitorem Performance:** Usem EXPLAIN ANALYZE para entender e otimizar execução de queries Na próxima vez que encontrarem relacionamentos de dados complexos, lembrem-se destes padrões. Seu eu futuro (e seus colegas de equipe) vão agradecer pelos ganhos de performance e type safety. **Itens de ação:** - Auditem suas queries atuais de banco para problemas N+1 e índices faltando - Adicionem interfaces TypeScript adequadas com tratamento explícito de null ao seu código existente - Implementem monitoramento de performance de query em seu ambiente de desenvolvimento Vocês já usaram estes padrões em seus projetos? Que otimizações de join acharam mais úteis? Compartilhem suas experiências nos comentários! --- ## Recursos - [Documentação PostgreSQL JOIN](https://www.postgresql.org/docs/current/queries-table-expressions.html#QUERIES-JOIN) - [Manual TypeScript - Tipos Avançados](https://www.typescriptlang.org/docs/handbook/2/types-from-types.html) - [Guia de Tuning de Performance de Banco](https://use-the-index-luke.com/) - [Melhores Práticas de Otimização de Query SQL](https://www.sqlshack.com/query-optimization-techniques-in-sql-server-tips-and-tricks/)

Loading...

NAVEGAÇÃO

COMPANY

PROJETO

Guia Completo de SQL Joins e TypeScript Safety Que Vai Transformar Suas Consultas de Banco