nexus-core-v3 3.0.0

package/knowledge/data/schema-modeling-decisions.md

@@ -0,0 +1,273 @@
+---
+id: schema-modeling-decisions
+domain: data
+agents: [data-engineer]
+when: "ao modelar o schema de uma aplicação"
+---
+
+# Decisões de modelagem de schema — normalizar, chaves, relacionamentos e árvores
+
+A maioria dos schemas ruins não nasce de ignorância: nasce de defaults aplicados sem critério.
+Coluna `id` serial em toda tabela porque o ORM gera; lista separada por vírgula porque "é só um
+campo"; `parent_id` numa árvore porque era o primeiro padrão que apareceu. Bill Karwin catalogou
+esses defaults como **antipatterns** — cada um tem uma cara reconhecível e uma correção concreta.
+Este pack é a árvore de decisão de modelagem: quando normalizar, qual chave usar, como traduzir
+cardinalidade em FK, e como modelar hierarquia sem cair no antipattern. A régua-mãe (Karwin):
+**"A Primary Key is a constraint, not a data type"** — e o mesmo vale para todo o schema. Você
+escolhe a estrutura pela restrição que ela garante, não pelo que o framework gera por padrão.
+
+## O problema (os tells de um schema gerado, não desenhado)
+
+Reconheça para evitar. Se o schema tem 3+ destes, ele foi gerado, não modelado:
+
+1. **Jaywalking** — múltiplos valores numa coluna separados por vírgula (`tags = "sql,db,perf"`,
+   `account_ids = "12,34,56"`). Viola a 1NF. Karwin chama de *jaywalking* porque é "atravessar fora
+   da faixa" para evitar criar a tabela de interseção (*intersection*).
+2. **Multicolumn Attributes** — `tag1, tag2, tag3` em colunas separadas. Mesmo problema da
+   Jaywalking, só que na horizontal: como você consulta "todas as linhas com a tag X" sem repetir
+   `WHERE tag1=X OR tag2=X OR tag3=X`?
+3. **ID Required** — coluna `id` serial em *toda* tabela por reflexo, inclusive onde uma chave
+   natural ou composta seria melhor (sobretudo em tabelas de interseção).
+4. **Keyless Entry** — relacionamentos sem `FOREIGN KEY`. A integridade vira responsabilidade da
+   aplicação, e qualquer script externo (migração, import, job) gera linhas órfãs.
+5. **Naive Trees** — hierarquia modelada só com `parent_id` (adjacency list) sem pensar no padrão
+   de consulta. "Pegar todos os descendentes" vira N joins ou recursão na aplicação.
+6. **EAV (Entity-Attribute-Value)** — tabela genérica `entity_id | attribute_name | value` para
+   "schema flexível". Você perde tipo, `NOT NULL`, FK e qualquer consulta sã.
+7. **Polymorphic Associations** — uma FK que aponta para "várias tabelas" via coluna
+   discriminadora (`commentable_id` + `commentable_type`). SQL não suporta FK assim → sem
+   integridade referencial.
+
+## O conhecimento / os princípios
+
+### 1. Normalizar é o default. Desnormalizar é uma exceção justificada.
+
+Normalize até a 3NF como ponto de partida. As três primeiras formas normais resolvem os
+antipatterns mais comuns:
+
+| Forma | Regra (Karwin) | Antipattern que elimina |
+|---|---|---|
+| **1NF** | Sem colunas repetidas nem valores separados por vírgula numa célula. Cada célula = um valor atômico. | Jaywalking, Multicolumn Attributes |
+| **2NF** | Com chave composta, nenhuma coluna pode depender de só *parte* da chave. | Redundância em tabelas de junção |
+| **3NF** | Proíbe armazenar dado não relacionado à PK e duplicado em outro lugar. | Anomalias de update |
+
+> Karwin: ir além de 3NF/BCNF para 4NF+ é raramente necessário e custa muitos joins. 3NF é o alvo
+> prático para a maioria das aplicações.
+
+**Desnormalize só com critério explícito** (não "por performance" no chute). Critérios válidos:
+
+- **Read-heavy comprovado** — a tabela é lida ordens de magnitude mais do que escrita, e o join
+  está medido como gargalo (não suposto).
+- **Dado histórico/snapshot** — você *quer* congelar o valor no momento (preço da `order_item` na
+  hora da compra, não o preço atual do produto). Aqui "duplicar" o preço não é desnormalização — é
+  o modelo correto, porque a semântica é "valor naquele instante".
+- **Agregado materializado** — `COUNT`/`SUM` pré-calculado (ex.: `post.comments_count`) com
+  trigger ou job mantendo a consistência.
+
+Regra: se você não consegue nomear **qual escrita vai manter o dado redundante consistente**, não
+desnormalize. A redundância sem dono é bug esperando acontecer.
+
+### 2. Jaywalking / Multicolumn → tabela de interseção (1NF)
+
+O tell:
+
+```sql
+-- ANTIPATTERN (Jaywalking): N:N escondido numa string
+CREATE TABLE products (
+  product_id  SERIAL PRIMARY KEY,
+  account_ids VARCHAR(100)   -- "12,34,56"
+);
+-- "Quem é dono do produto 5?"  →  WHERE account_ids LIKE '%5%'  (pega 15, 25, 51...)
+-- COUNT/SUM/JOIN/FK: impossíveis. Limite de tamanho da coluna: bomba-relógio.
+```
+
+A correção é sempre a **tabela de interseção**, com a chave composta dos dois lados como PK
+(que também elimina duplicatas de graça):
+
+```sql
+CREATE TABLE contacts (
+  product_id  INT NOT NULL REFERENCES products(product_id),
+  account_id  INT NOT NULL REFERENCES accounts(account_id),
+  PRIMARY KEY (product_id, account_id)   -- chave composta natural, sem 'id' serial
+);
+```
+
+O mesmo vale para `tag1, tag2, tag3` (Multicolumn): vira `post_tags(post_id, tag_id)`.
+
+### 3. PK: surrogate (pseudokey) vs. natural vs. composta
+
+Karwin: o antipattern **ID Required** não é "usar `id` serial" — é usar `id` serial *sem pensar*,
+em toda tabela. A decisão real:
+
+```sql
+-- Tabela de interseção: chave COMPOSTA NATURAL é melhor que 'id' serial.
+-- Garante unicidade do par (impede duplicata) sem índice extra.
+PRIMARY KEY (product_id, account_id)
+
+-- Entidade de domínio com identificador natural confiável e estável:
+CREATE TABLE countries (
+  iso_code CHAR(2) PRIMARY KEY,   -- 'BR', 'US' — único, estável, significativo
+  name     VARCHAR(80) NOT NULL
+);
+
+-- Entidade sem chave natural estável (usuário, pedido): surrogate é legítimo.
+CREATE TABLE orders (
+  order_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY
+);
+```
+
+Critérios de Karwin para **natural/composta**:
+- O atributo é **genuinamente único** (verifique nos dados reais, não na esperança).
+- É **estável** (não muda — CPF muda? email muda? então não é boa PK).
+- Carrega **significado de domínio** que simplifica queries.
+
+Critérios para **surrogate**:
+- Não existe chave natural estável, OU a natural é larga/composta e referenciada por muitas FKs.
+- A imutabilidade da PK importa (surrogate nunca muda, mesmo que o "negócio" mude).
+
+> Nota de naming: Karwin recomenda nome descritivo (`comment_id`) para permitir `JOIN ... USING
+> (comment_id)`. Equipes que abstraem o front com convenção `id` constante discordam — escolha uma
+> convenção e mantenha. O antipattern é não decidir.
+
+### 4. Cardinalidade → FK (e sempre declare a FK)
+
+Traduza a cardinalidade do domínio em estrutura. E declare `FOREIGN KEY` — **Keyless Entry** é
+antipattern: sem a constraint, a integridade vira "torcer para a aplicação acertar", e qualquer
+import/script externo gera órfãos.
+
+| Cardinalidade | Onde mora a FK | Forma |
+|---|---|---|
+| **1:N** (um cliente, N pedidos) | Na tabela do lado "N" | `orders.customer_id REFERENCES customers` |
+| **N:N** (produtos ↔ contas) | Tabela de interseção | `contacts(product_id, account_id)` com PK composta |
+| **1:1** (user ↔ profile) | FK + `UNIQUE` (ou PK compartilhada) | `profiles.user_id UNIQUE REFERENCES users` |
+| **0..1** (opcional) | FK `NULL`-able | `employees.manager_id NULL REFERENCES employees` |
+
+Escolha a ação referencial de propósito (Karwin):
+
+```sql
+order_id BIGINT REFERENCES orders(order_id)
+  ON DELETE CASCADE     -- itens somem com o pedido (parte fraca da composição)
+-- ON DELETE RESTRICT   -- impede apagar o pai se há filhos (default seguro)
+-- ON DELETE SET NULL   -- desvincula sem apagar (ex.: manager saiu, subordinado fica)
+```
+
+### 5. Hierarquias → escolha o modelo pelo padrão de leitura/escrita (não use só `parent_id`)
+
+**Naive Trees** = usar só adjacency list sem perguntar como a árvore é consultada. Os quatro
+modelos de Karwin, com critério de escolha:
+
+**a) Adjacency List** (`parent_id`) — o default honesto.
+
+```sql
+CREATE TABLE comments (
+  comment_id SERIAL PRIMARY KEY,
+  parent_id  INT REFERENCES comments(comment_id),
+  body       TEXT
+);
+-- Mover subárvore = 1 UPDATE no parent_id. Inserir = trivial.
+-- "Todos os descendentes" precisa de recursão (PostgreSQL 8.2+):
+WITH RECURSIVE tree AS (
+  SELECT comment_id, parent_id FROM comments WHERE comment_id = 4
+  UNION ALL
+  SELECT c.comment_id, c.parent_id
+  FROM comments c JOIN tree t ON c.parent_id = t.comment_id
+)
+SELECT * FROM tree;
+```
+Use quando: o banco suporta `WITH RECURSIVE`, inserts/moves são frequentes, e a profundidade das
+leituras é moderada. Em Postgres moderno, é a escolha default razoável.
+
+**b) Path Enumeration** (caminho materializado) — leitura por prefixo.
+
+```sql
+ALTER TABLE comments ADD COLUMN path VARCHAR(255);  -- '4/5/8/'
+-- Todos os descendentes de 4 (sem recursão):
+SELECT * FROM comments WHERE path LIKE '4/%';
+```
+Use quando: leitura é dominante e por subárvore. Cuidado: mover uma subárvore exige reescrever o
+`path` de todos os descendentes, e não há FK garantindo que o caminho aponta para nós reais.
+
+**c) Nested Sets** (`left`/`right`) — leitura de subárvore ultrarrápida, escrita cara.
+
+Cada nó guarda dois números (left, right); descendentes têm `left/right` *entre* os do ancestral.
+Karwin: rápido para consultar subárvores, mas **inserir/mover é complexo** — quase todos os nós
+precisam ter left/right renumerados. Use só quando a árvore é praticamente read-only (catálogo
+estável) e você lê subárvores inteiras o tempo todo.
+
+**d) Closure Table** — tabela separada com *uma linha por par ancestral→descendente*. O equilíbrio
+de Karwin: rápido em todas as operações, ao custo de mais armazenamento.
+
+```sql
+CREATE TABLE comment_tree (
+  ancestor   INT NOT NULL REFERENCES comments(comment_id),
+  descendant INT NOT NULL REFERENCES comments(comment_id),
+  depth      INT NOT NULL,
+  PRIMARY KEY (ancestor, descendant)
+);
+-- Inserir nó: linha self (depth 0) + uma linha para cada ancestral do pai.
+INSERT INTO comment_tree (ancestor, descendant, depth)
+  SELECT ancestor, :new_id, depth + 1
+  FROM comment_tree WHERE descendant = :parent_id
+  UNION ALL SELECT :new_id, :new_id, 0;
+-- Todos os descendentes: SELECT descendant FROM comment_tree WHERE ancestor = :id;
+-- Linha de comando ascendente: SELECT ancestor FROM comment_tree WHERE descendant = :id ORDER BY depth DESC;
+```
+Use quando: você precisa de consultas rápidas de ancestral *e* descendente, suporta atributos na
+aresta (ex.: data de vigência), e as escritas são moderadas. É a escolha mais versátil do livro.
+
+**e) `ltree` (PostgreSQL)** — path enumeration nativo, com operadores de árvore.
+
+```sql
+CREATE EXTENSION ltree;
+ALTER TABLE comments ADD COLUMN path ltree;   -- 'root.4.5.8'
+CREATE INDEX ON comments USING GIST (path);
+SELECT * FROM comments WHERE path <@ '4';      -- todos os descendentes de 4
+```
+Use quando: está em Postgres e quer materialized path "de fábrica". Limitações: o índice GIST tem
+limite de tamanho de label (árvores muito profundas sofrem), e mover subárvore exige reescrever o
+`path` de todos os descendentes.
+
+## Checklist (passe antes de aprovar o schema)
+
+- [ ] Alguma coluna guarda lista separada por vírgula ou `campo1/campo2/campo3`? (Jaywalking /
+      Multicolumn → tabela de interseção)
+- [ ] Toda relação tem `FOREIGN KEY` declarada com ação `ON DELETE`/`ON UPDATE` escolhida de
+      propósito? (Keyless Entry)
+- [ ] Cada tabela de interseção usa **chave composta** dos dois lados como PK, não um `id` serial
+      desnecessário? (ID Required)
+- [ ] Onde existe chave natural estável e única, ela foi considerada como PK em vez de surrogate
+      automático?
+- [ ] Existe alguma FK "polimórfica" (`*_id` + `*_type`)? Se sim, refatorada para arco exclusivo ou
+      interseções por tipo?
+- [ ] Existe tabela genérica `entity/attribute/value`? Se sim, substituída por colunas tipadas,
+      tabela por subtipo, ou JSON tipado?
+- [ ] A hierarquia foi modelada pelo padrão de leitura/escrita real, não só `parent_id` por reflexo?
+- [ ] Toda redundância (dado duplicado) tem um dono explícito — a escrita que a mantém consistente?
+
+## Tabela de decisão "use X quando Y"
+
+| Use X | Quando Y |
+|---|---|
+| **Normalizar até 3NF** | Default. Sempre comece aqui. |
+| **Desnormalizar** | Read-heavy *medido*, snapshot histórico, ou agregado materializado **com dono de consistência** |
+| **Tabela de interseção** (PK composta) | Cardinalidade N:N — sempre, nunca lista CSV nem `tag1/tag2/tag3` |
+| **PK surrogate** (`IDENTITY`/serial) | Sem chave natural estável; natural muito larga; imutabilidade da PK importa |
+| **PK natural** | Atributo único, estável e significativo (`iso_code`, código de referência) |
+| **PK composta** | Tabela de interseção (os dois FKs juntos) |
+| **FK `ON DELETE CASCADE`** | Filho é parte fraca da composição (item do pedido some com o pedido) |
+| **FK `ON DELETE RESTRICT`** | Default seguro: impede apagar pai com filhos |
+| **FK `ON DELETE SET NULL`** | Vínculo opcional que pode existir sozinho (subordinado sem gestor) |
+| **Adjacency List** (`parent_id`) | Postgres com `WITH RECURSIVE`; inserts/moves frequentes; profundidade moderada |
+| **Path Enumeration / `ltree`** | Leitura por subárvore dominante; árvore não muito profunda; moves raros |
+| **Nested Sets** | Árvore quase read-only; leitura de subárvore inteira é o caso crítico |
+| **Closure Table** | Precisa de queries rápidas de ancestral E descendente; atributos na aresta; escrita moderada |
+| **Colunas tipadas / tabela por subtipo** | Em vez de EAV — quando os atributos são conhecidos |
+| **JSON/JSONB tipado** | Schema genuinamente dinâmico — em vez de EAV, mantendo o resto relacional |
+| **Arco exclusivo** (parent table compartilhada) | Em vez de FK polimórfica — quando precisa de FK real |
+| **Interseções por tipo** | Em vez de FK polimórfica — quando a 1:1 não precisa ser forçada |
+
+---
+
+Fonte: Bill Karwin, *SQL Antipatterns: Avoiding the Pitfalls of Database Programming* (Pragmatic
+Bookshelf) — capítulos Jaywalking, Multicolumn Attributes, Naive Trees, ID Required, Keyless Entry,
+Entity-Attribute-Value, Polymorphic Associations; e a coletânea *awesome-database-design*.

package/knowledge/data/supabase-rls-patterns.md

@@ -0,0 +1,316 @@
+---
+id: supabase-rls-patterns
+domain: data
+agents: [data-engineer]
+when: "ao implementar segurança de dados com Row Level Security no Supabase/Postgres"
+---
+
+# Supabase RLS — segurança no banco, não na aplicação
+
+## O problema
+
+Com Supabase, qualquer cliente com a `anon` key fala direto com o Postgres via PostgREST. Não existe
+"backend que filtra antes". Se você confia no `.eq('user_id', userId)` do cliente para isolar dados, a
+segurança é uma sugestão: qualquer um troca o `userId` no DevTools e lê a tabela inteira. **A fronteira
+de autorização é o banco.** RLS é o mecanismo que faz o próprio Postgres decidir, linha a linha, o que
+cada `role`/usuário pode `select`/`insert`/`update`/`delete`.
+
+Os tells de RLS feito por quem não conhece:
+
+1. **Tabela com RLS desabilitado** exposta no schema `public` — vazamento total via API.
+2. **`enable row level security` sem nenhuma policy** — ninguém lê nada (RLS nega por padrão), e o dev
+   "conserta" desabilitando RLS em vez de escrever a policy.
+3. **`auth.uid()` chamado direto na policy** (sem `(select …)`) — reavaliado **por linha**, derruba a
+   query de <1ms para segundos numa tabela de 100k linhas.
+4. **Policy sem `to authenticated`** — roda o predicado caro até para `anon`, que nunca deveria passar.
+5. **Policy baseada em `user_metadata`** — claim que o **próprio usuário edita**; vira escalonamento de
+   privilégio (o atacante se promove a admin).
+6. **`update` sem `select` correspondente** — o update "não funciona" e ninguém entende por quê.
+7. **Multi-tenant filtrando `tenant_id` só na app**, sem coluna `tenant_id` na policy nem índice — um
+   tenant lê dados do outro, e quando você adiciona a policy, a query fica lenta sem índice.
+
+## O conhecimento / os princípios
+
+### 1. Ligue RLS e conceda os grants — RLS nega por padrão
+
+RLS só protege se estiver habilitado, e habilitar sem policy bloqueia tudo. Toda tabela em `public`
+deve ter RLS ligado:
+
+```sql
+alter table public.todos enable row level security;
+```
+
+Os `grant` definem *quais operações o role pode tentar*; a policy define *quais linhas*. Os dois são
+necessários:
+
+```sql
+grant select on public.todos to anon;
+grant select, insert, update, delete on public.todos to authenticated;
+grant select, insert, update, delete on public.todos to service_role;
+```
+
+> Sem policy, ninguém (exceto `service_role`/`bypassrls`) lê nada. A resposta certa para "ninguém lê" é
+> **escrever a policy**, nunca desabilitar RLS.
+
+### 2. USING vs WITH CHECK — eles não são intercambiáveis
+
+- **`using`** filtra as linhas **existentes** que a query pode ver/afetar (read-side).
+- **`with check`** valida as linhas **novas/modificadas** que estão sendo gravadas (write-side).
+
+Se você só define `using` num insert/update, não há validação do que entra. Regra por operação (direto
+da doc do Supabase):
+
+| Operação | `using` | `with check` |
+|---|---|---|
+| `select` | sempre | nunca |
+| `insert` | nunca | sempre |
+| `update` | quase sempre | sempre |
+| `delete` | sempre | nunca |
+
+Postgres **não aceita múltiplas operações num único `for`** — escreva **uma policy por operação**:
+
+```sql
+-- SELECT: usa USING
+create policy "Individuals can view their own todos."
+on public.todos for select
+to authenticated
+using ( (select auth.uid()) = user_id );
+
+-- INSERT: usa WITH CHECK (impede gravar linha de outro usuário)
+create policy "Users can create their own todos."
+on public.todos for insert
+to authenticated
+with check ( (select auth.uid()) = user_id );
+
+-- UPDATE: USING (quais linhas pode tocar) + WITH CHECK (no que pode virar)
+create policy "Users can update their own todos."
+on public.todos for update
+to authenticated
+using ( (select auth.uid()) = user_id )
+with check ( (select auth.uid()) = user_id );
+
+-- DELETE: usa USING
+create policy "Users can delete their own todos."
+on public.todos for delete
+to authenticated
+using ( (select auth.uid()) = user_id );
+```
+
+> **Armadilha:** `update` precisa de uma policy de `select` correspondente, senão o update "não
+> funciona". O Postgres precisa enxergar a linha (`select`) para então atualizá-la.
+
+### 3. Sempre especifique o role com `to`
+
+Sem `to`, a policy é avaliada para **todos os roles**, inclusive `anon` — que paga o custo de um
+predicado que nunca vai passar. Com `to authenticated`, a avaliação para cedo para visitantes.
+
+Ordem das cláusulas: `on <tabela>` → `for <operação>` → `to <roles>` → `using/with check`.
+
+```sql
+-- leitura pública explícita
+create policy "Public profiles are visible to everyone."
+on public.profiles for select
+to anon, authenticated
+using ( true );
+```
+
+Benchmark da doc (tabela 100k linhas): adicionar `to authenticated` numa query feita por `anon` cai de
+**170ms para <0,1ms** — porque a policy nem roda.
+
+### 4. auth.uid() e auth.jwt() — e o claim que você NÃO pode confiar
+
+- `auth.uid()` → `uuid` do usuário autenticado (vem do `sub` do JWT).
+- `auth.jwt()` → claims completos do token.
+
+Dentro do JWT existem dois objetos de metadata, e a diferença é de segurança, não de estilo:
+
+| Claim | Origem | Confiável em RLS? |
+|---|---|---|
+| `app_metadata` (`raw_app_meta_data`) | gravado pelo backend/admin | **SIM** |
+| `user_metadata` (`raw_user_meta_data`) | **editável pelo próprio usuário** | **NÃO — nunca** |
+
+Usar `user_metadata` para autorização (ex.: `role`, `is_admin`, `tenant_id`) é uma vulnerabilidade: o
+usuário muda o próprio claim e escala privilégio. Use sempre `app_metadata`:
+
+```sql
+-- pertencimento a time via app_metadata (seguro)
+create policy "User is in team"
+on public.my_table for select
+to authenticated
+using ( team_id in (select auth.jwt() -> 'app_metadata' -> 'teams') );
+```
+
+Enforçar MFA (assurance level) com policy **restritiva** (restritiva = AND com as permissivas):
+
+```sql
+create policy "Restrict updates to MFA users."
+on public.profiles
+as restrictive
+for update
+to authenticated
+using ( (select auth.jwt()->>'aal') = 'aal2' );
+```
+
+Prefira `permissive` (default, combinam por OR) na maioria dos casos; use `restrictive` só quando
+precisa de uma condição que se soma a **todas** as outras (como o gate de MFA acima).
+
+### 5. Multi-tenant: `tenant_id` na policy + índice obrigatório
+
+Isolamento de tenant tem que viver na policy, com o `tenant_id` derivado do JWT (via `app_metadata`),
+não passado pelo cliente:
+
+```sql
+-- tenant_id vem do app_metadata; cliente não consegue forjar
+create policy "Tenant isolation - select"
+on public.invoices for select
+to authenticated
+using ( tenant_id = ((select auth.jwt()) -> 'app_metadata' ->> 'tenant_id')::uuid );
+
+-- ÍNDICE é parte da policy, não opcional
+create index idx_invoices_tenant_id on public.invoices using btree (tenant_id);
+```
+
+Toda coluna comparada na policy (`user_id`, `tenant_id`) precisa de índice. Benchmark da doc: índice em
+`user_id` numa tabela de 100k linhas leva a query de **171ms para <0,1ms** (>100x).
+
+### 6. A armadilha de performance nº 1: envolva funções em `(select …)`
+
+Chamar `auth.uid()`, `auth.jwt()` ou qualquer função direto na policy faz o Postgres reavaliá-la **por
+linha**. Envolver em `(select …)` dispara um **initPlan** que **cacheia o resultado uma vez por
+statement** (válido porque o resultado não muda entre linhas):
+
+```sql
+-- LENTO: auth.uid() reavaliado por linha
+using ( auth.uid() = user_id )
+
+-- RÁPIDO: (select …) cacheia via initPlan
+using ( (select auth.uid()) = user_id )
+```
+
+Vale para funções suas também:
+
+```sql
+-- de:
+using ( is_admin() or auth.uid() = user_id )
+-- para:
+using ( (select is_admin()) or (select auth.uid()) = user_id )
+```
+
+Números reais da doc (tabela 100k linhas, antes → depois):
+
+| Cenário | Antes | Depois |
+|---|---|---|
+| `auth.uid()=user_id` → `(select auth.uid())` | 179ms | 9ms |
+| `is_admin()` com join → `(select is_admin())` | 11.000ms | 7ms |
+| `has_role()=role` → `(select has_role())` | 178.000ms | 12ms |
+| `team_id = any(...)` → versão envolvida | 173.000ms | 16ms |
+
+### 7. SECURITY DEFINER para quebrar recursão e otimizar join
+
+Quando a policy precisa consultar **outra tabela** que **também tem RLS** (ex.: tabela de papéis/times),
+você cai em recursão ou em joins caros. A solução é uma função `security definer` — ela roda com os
+privilégios de quem **definiu** (dono), **ignorando RLS** dentro dela, então a policy a chama sem
+recursão:
+
+```sql
+create or replace function public.user_teams()
+  returns int[] as $$
+begin
+  return array( select team_id from team_user where auth.uid() = user_id );
+end;
+$$ language plpgsql security definer;
+```
+
+Na policy, envolva o retorno em `array(select …)` para o cache do initPlan:
+
+```sql
+-- 1M linhas: =any(user_teams()) sem cache → timeout (>120s)
+-- com array(select …) → 170ms; com índice → 2ms
+using ( team_id = any( array(select public.user_teams()) ) );
+```
+
+> `security definer` = roda como o dono (ignora RLS interno). `security invoker` = roda como quem chama
+> (respeita RLS). Funções de autorização usadas em policies são `security definer` **de propósito** —
+> mas blinde-as: `search_path` fixo e lógica mínima, porque elas furam o RLS por design.
+
+Para **views** (Postgres 15+), o default seguro é `security_invoker` para a view respeitar a RLS das
+tabelas-base:
+
+```sql
+create view public.my_view
+with (security_invoker = true)
+as select ... ;
+```
+
+### 8. Inverta o join em vez de fazer a tabela-fonte cruzar a alvo
+
+Joins na policy que partem da tabela protegida para a tabela de associação são caros. Inverta: filtre na
+tabela de associação e compare a coluna local.
+
+```sql
+-- LENTO (9.000ms): join source → target
+using ( auth.uid() in (select user_id from team_user where team_user.team_id = invoices.team_id) )
+
+-- RÁPIDO (20ms): inverte — filtra na associação, compara coluna local
+using ( team_id in (select team_id from team_user where user_id = (select auth.uid())) )
+```
+
+### 9. Nunca confie no filtro do cliente — mas adicione-o por performance
+
+O `.eq('user_id', userId)` no cliente **não é segurança** (RLS é). Mas adicioná-lo ajuda o planner:
+combinar o filtro explícito com a RLS levou a query de **171ms para 9ms** na doc, porque o índice é
+usado melhor. Regra: RLS garante a segurança; o `.eq()` é otimização redundante, não substituto.
+
+### 10. Bypass consciente: `service_role` e `bypassrls`
+
+A `service_role` key e roles com `bypassrls` **ignoram toda RLS**. Use no servidor (jobs, webhooks,
+migrações), **jamais no browser**. Expor a `service_role` no front é equivalente a desligar a RLS.
+
+```sql
+alter role "background_worker" with bypassrls;
+```
+
+## Checklist
+
+Antes de marcar uma tabela como segura — qualquer "não" é um vazamento ou um gargalo:
+
+- [ ] `enable row level security` está ligado em **toda** tabela do schema `public`?
+- [ ] Existe uma policy por operação (`select`/`insert`/`update`/`delete`) onde aquela operação é
+      permitida — e não só `select`?
+- [ ] `insert`/`update` usam `with check` (não só `using`)?
+- [ ] `update` tem uma policy de `select` correspondente?
+- [ ] Toda policy especifica `to authenticated` (ou o role correto), nunca implícito?
+- [ ] Autorização usa `app_metadata` / `auth.uid()` — **nunca** `user_metadata`?
+- [ ] Toda chamada de `auth.uid()`/`auth.jwt()`/função está envolvida em `(select …)`?
+- [ ] Toda coluna comparada na policy (`user_id`, `tenant_id`) tem **índice** btree?
+- [ ] Multi-tenant: `tenant_id` vem do JWT (`app_metadata`), não do payload do cliente?
+- [ ] Consultas a outras tabelas com RLS usam `security definer` (com `search_path` fixo) para evitar
+      recursão?
+- [ ] Views usam `with (security_invoker = true)` (PG 15+)?
+- [ ] A `service_role` key existe **apenas** no servidor, nunca no bundle do cliente?
+
+## Tabela de decisão "use X quando Y"
+
+| Use… | Quando… |
+|---|---|
+| `using` | A condição decide quais **linhas existentes** ler/afetar (`select`, `delete`, lado-read do `update`) |
+| `with check` | A condição valida **linhas novas/modificadas** sendo gravadas (`insert`, lado-write do `update`) |
+| `(select auth.uid())` | **Sempre** — em qualquer policy que chame função; cacheia via initPlan (per-statement, não per-row) |
+| `auth.uid() = user_id` | Isolamento simples por dono da linha (uma tabela, sem times/tenants) |
+| `app_metadata` no `auth.jwt()` | Autorização por role/tenant/time — claim controlado pelo backend, não forjável |
+| `user_metadata` | **Nunca** em autorização (usuário edita); só para preferências de UI sem efeito de segurança |
+| Policy `permissive` (default) | Caso geral — múltiplas policies combinam por **OR** (acesso se qualquer uma passar) |
+| Policy `restrictive` | Gate que deve valer junto com **todas** as outras por **AND** (ex.: exigir `aal2`/MFA) |
+| `to authenticated` | Sempre que a regra só vale para logados — evita rodar predicado caro para `anon` |
+| Índice btree na coluna | **Sempre** que a coluna aparece na policy (`user_id`, `tenant_id`) — ganho >100x |
+| `security definer` | A policy consulta **outra tabela com RLS** (papéis/times/tenants) e há risco de recursão/join caro |
+| `security invoker` (default em funções) | A função deve **respeitar** a RLS de quem a chama — e em **views** (`security_invoker = true`) |
+| `array(select user_teams())` | Função retorna conjunto usado com `= any(...)` — força cache e evita timeout em tabelas grandes |
+| Inverter o join (filtrar na tabela de associação) | A policy faria a tabela protegida cruzar (`join`) a tabela de associação — inverta para usar índice |
+| `service_role` / `bypassrls` | Operação de servidor confiável (jobs, webhooks, migração) — **nunca** exposto ao cliente |
+
+---
+
+**Fonte:** Supabase Docs — [Row Level Security](https://supabase.com/docs/guides/database/postgres/row-level-security),
+[RLS Performance and Best Practices](https://supabase.com/docs/guides/troubleshooting/rls-performance-and-best-practices-Z5Jjwv),
+[AI Prompt: Create RLS policies](https://supabase.com/docs/guides/getting-started/ai-prompts/database-rls-policies).