Readme
Convenções de SQL voltadas a quem vai ler a query depois. Os exemplos usam SQL Server como referência, e as diferenças do PostgreSQL aparecem sinalizadas onde importam.
Uma linha divide este guia: o banco guarda e devolve dados, e a aplicação decide o que os dados significam. As regras de negócio, as validações e a orquestração ficam na aplicação. As procedures e as functions ficam reservadas ao que só o banco faz bem, que é otimizar acesso e montar relatório.
Fundamentos
| Tópico | Conceitos |
|---|---|
| Formatação | Estilo vertical, indentação, JOIN, condições verticais |
| Nomes | Inglês, plural/singular, qualificação, prefixos, constraints |
| CRUD | INSERT, SELECT, UPDATE, DELETE, soft delete, filtros, ordenação |
| Densidade visual | CTEs encadeadas, etapas em procedures |
Avançados
| Tópico | Conceitos |
|---|---|
| Recursos avançados | CTEs, subqueries, functions |
| Procedures | Temp tables, etapas nomeadas, queries complexas |
| Performance | SELECT *, índices, subquery correlacionada, FK sem índice, paginação |
| Segurança contra nulos | IS NULL, COALESCE, NULLIF, NOT NULL + DEFAULT, NULL em JOIN |
| Migrations | Naming YYYYMMDDHHMMSS, forward only, uma responsabilidade |
| Operações em lote | Batch INSERT, DELETE/UPDATE em lotes com TOP + WHILE, staging table |
| Modelagem de entidades | DOMAIN type para IDs, embedded columns vs satellite, ENUM/CHECK, FK por id, RLS |
| Referência rápida | Nomenclatura, verbos, taboos, query estruturada |
SGBD
Idioms e recursos específicos de cada banco de dados.
| SGBD | Versão | Conceitos |
|---|---|---|
| SQL Server | 2025 | T-SQL, tipos, procedures, TRY/CATCH, OPPO, RegEx, JSON nativo, vector search |
| PostgreSQL | 18 | PL/pgSQL, RETURNING, JSONB, UUID v7, CTEs em DML, window functions, LISTEN/NOTIFY |
| SQLite | 3.53 | Type affinity, WAL, rowid, FTS5, JSON, ALTER TABLE, PRAGMAs |
Princípios
Legibilidade e nomes: formatação, estilo visual e nomenclatura
| Princípio | Descrição |
|---|---|
| Escrita em inglês | Tabelas, colunas e objetos nomeados em inglês |
| Escrita vertical | Uma cláusula por linha: SELECT, FROM, JOIN, WHERE, ORDER BY |
| Baixa densidade visual | Inline somente com ≤3 campos e ≤1 condição |
| Indentação consistente | 2 espaços sob cada cláusula, blocos alinhados por nível |
| Nomes expressivos | Aliases descritivos pelo domínio; nunca t, c, x |
| Qualificação explícita | Sempre Tabela.Coluna, nunca colunas nuas |
| Joins legíveis | JOIN e ON em linhas separadas; ON complexo expandido |
| Condições verticais | Uma condição por linha, AND e OR ao final da linha |
| Sem valores mágicos | Parâmetros nomeados em vez de literais inline |
| Ordenação explícita | ORDER BY sempre declarado |
| Objetos nomeados | SP_, FN_, IX_, VW_: prefixo declara a intenção |
| Constraints nomeadas | PK_, FK_, UQ_, CK_: toda constraint tem nome explícito |
Estrutura: organização de queries complexas
| Princípio | Descrição |
|---|---|
| Fluxo linear | Leitura de cima para baixo: filtros antes de JOINs, resultado no final |
| Etapas explícitas | Queries complexas decompostas em passos nomeados com temp tables |
| Sem subqueries profundas | Subqueries substituídas por CTEs nomeadas |
| CTE vs temp table | CTE para leitura simples; temp table (#) para reuso e performance |
| Filtros antecipados | WHERE na tabela principal antes dos JOINs |
Performance e integridade: otimizações e restrições
| Princípio | Descrição |
|---|---|
| Consultas enxutas | Sem SELECT *; trazer apenas as colunas necessárias |
| FK com índice | FK sempre acompanhada de índice na coluna referenciadora |
| Migrations incrementais | YYYYMMDDHHMMSS_descricao.sql: uma mudança por arquivo |
| Forward only | Nunca editar migration existente; ajuste = nova migration |
DoDocs v3.7.0 · Desenvolvido por @thiagocajadev · Baseado no trabalho de pmndrs/docs · Poimandres.