Database

Escopo: transversal. Aplica-se a qualquer linguagem ou stack do projeto.

O banco de dados é o componente com maior impacto em performance e o mais difícil de escalar retroativamente. Escolher o modelo certo, escrever queries eficientes e saber diagnosticar gargalos antes de chegarem à produção são habilidades que mudam a capacidade de um sistema.

A escolha não é sobre modernidade: é sobre o modelo de dados e os padrões de acesso.

Dados estruturados em tabelas com schema definido. Relações entre entidades expressas como foreign keys. Transações com garantias ACID.

Exemplos: PostgreSQL, SQL Server, MySQL, SQLite.

Quando usar: domínio com relações entre entidades, necessidade de consistência transacional, queries variadas não definidas em tempo de design.

Quatro modelos principais, cada um otimizado para um padrão de acesso diferente:

Quando usar: escala de escrita muito alta que bancos relacionais não absorvem, dados sem schema previsível, padrão de acesso fixo e conhecido (key-value, full document), ou quando o modelo de grafo representa a estrutura natural dos dados.

O que não fazer: escolher NoSQL porque "escala melhor" sem medir. Banco relacional bem indexado suporta volumes muito maiores do que a maioria dos projetos vai atingir. A complexidade operacional de NoSQL tem custo real.

O gargalo mais comum não é hardware: é query mal escrita ou ausência de índice.

Um índice cria uma estrutura auxiliar que o banco usa para encontrar linhas sem varrer a tabela inteira.

-- índice simples: acelera buscas por email
CREATE INDEX idx_users_email ON users(email);

-- índice composto: acelera WHERE status = ? AND created_at > ?
CREATE INDEX idx_orders_status_created ON orders(status, created_at);

Regras:

Padrões com BAD/GOOD completos: sql/conventions/advanced/performance.md.

Os anti-padrões de NoSQL diferem dos SQL, mas o princípio é o mesmo: trabalho desnecessário no servidor é mais barato que trabalho no cliente.

Guia completo por SGBD: docs/nosql/. Convenções de CRUD (Create Read Update Delete, Criar Ler Atualizar Excluir), naming e performance: nosql/conventions/.

const user = await database.collection('users').findOne({ email });
const userName = user.name;

class UserRepository {
  async findByEmail(email) {
    const user = await this.collection.findOne(
      { email },
      { projection: { name: 1, _id: 0 } }
    );

    return user;
  }
}

const allOrders = await database.collection('orders').find({}).toArray();
const pendingOrders = allOrders.filter(order => order.status === 'pending');

class OrderRepository {
  async findPending() {
    const pendingOrders = await this.collection
      .find({ status: 'pending' })
      .project({ id: 1, customerId: 1, total: 1 })
      .toArray();

    return pendingOrders;
  }
}

const orders = await database.collection('orders').find({ userId }).toArray();

const enrichedOrders = await Promise.all(
  orders.map(async order => {
    const product = await database.collection('products').findOne({ _id: order.productId });

    return { ...order, product };
  })
);

class OrderRepository {
  async findByUserWithProduct(userId) {
    const enrichedOrders = await this.collection.aggregate([
      { $match: { userId } },
      {
        $lookup: {
          from: 'products',
          localField: 'productId',
          foreignField: '_id',
          as: 'product',
        },
      },
      { $unwind: '$product' }, // drops orders with no matching product: use preserveNullAndEmptyArrays: true if product can be missing
    ]).toArray();

    return enrichedOrders;
  }
}

Operações em lote agrupam múltiplas linhas em uma única instrução ou dividem uma operação grande em ciclos menores. Dois objetivos distintos: aumentar throughput em carga inicial e evitar locks de longa duração em operações de manutenção.

Não existe valor universal. O critério é o tempo de lock aceitável para o sistema.

Operações em lote que rodam em produção precisam de idempotência: se o job for interrompido, a próxima execução deve continuar de onde parou sem duplicar ou corromper dados. O padrão é usar a condição de filtro do próprio UPDATE/DELETE como cursor natural: o WHERE já exclui as linhas já processadas nas iterações anteriores.

Padrões de query: sql/conventions/advanced/batch.md.

Recursos específicos por banco: SQL Server | PostgreSQL.

O plano de execução mostra como o banco vai executar a query: quais índices vai usar, como vai fazer joins, qual o custo estimado de cada operação.

Antes de deployar qualquer query em uma tabela grande, analisar o plano.

Sintaxe por banco: PostgreSQL | SQL Server.

-- exemplo de saída EXPLAIN (PostgreSQL)
Seq Scan on orders  (cost=0.00..4521.00 rows=150000 width=16)
  Filter: ((status)::text = 'pending'::text)

Seq Scan em tabela grande com Filter é o sinal mais claro de índice ausente.

O primeiro passo para identificar problemas em produção é habilitar o log de queries lentas.

Configuração por banco: PostgreSQL | SQL Server.

N+1 raramente aparece no código; aparece no log de queries. O sinal é um padrão repetido de queries idênticas com IDs diferentes em sequência rápida.

-- sinal de N+1 no log
SELECT * FROM customers WHERE id = 1  -- 0.1ms
SELECT * FROM customers WHERE id = 2  -- 0.1ms
SELECT * FROM customers WHERE id = 3  -- 0.1ms
... (100 vezes)

Ferramentas que expõem N+1 automaticamente: Bullet (Rails), Hibernate Statistics, EF Core logging, Sequelize logging mode.

Quando todas as conexões do pool estão em uso, novas requisições ficam em fila. Sintoma: timeouts em requisições simples que normalmente são rápidas, sem aumento de CPU (Central Processing Unit, Unidade Central de Processamento) ou lentidão de queries.

Diagnóstico por banco: PostgreSQL | SQL Server.

Causas comuns: queries longas segurando conexão, transaction não fechada, pool subdimensionado, pico de tráfego inesperado.

Lock é esperado: é o mecanismo de consistência. O problema é lock de longa duração ou deadlock.

Identificar locks ativos: PostgreSQL | SQL Server.

Deadlock aparece no log com mensagem explícita. A causa mais comum é duas transações acessando as mesmas linhas em ordem inversa. A solução é padronizar a ordem de acesso.

-- padrão que gera deadlock
Transação A: lock em orders(1) → tenta lock em payments(1)
Transação B: lock em payments(1) → tenta lock em orders(1)  ← deadlock

-- solução: sempre adquirir locks na mesma ordem
Transação A: lock em orders(1) → lock em payments(1)
Transação B: lock em orders(1) → lock em payments(1)  ← espera A terminar

Ao receber relatório de "banco lento":

Desenvolvido por @thiagocajadev · Fork baseado no repositório pmndrs/docs · Poimandres.