Automação de Registro: Sincronizando o Supabase Auth com o Banco de Dados

Índice do Manual

• O Risco da Sincronização via Frontend
• A Solução: Automação Direta no Banco de Dados (Triggers)
  • O Script SQL Padrão
• O Impacto Transacional

A criação de um novo usuário em um sistema SaaS B2B parece uma tarefa inofensiva. O usuário digita o e-mail, a senha e clica em "Cadastrar". No entanto, nos bastidores arquiteturais, esse é um dos momentos mais frágeis da engenharia de software.

Quando você utiliza uma plataforma corporativa como o Supabase, o registro ocorre em um esquema de segurança isolado (o auth.users). Porém, para que você consiga mostrar o nome ou a foto desse usuário no painel do sistema, você precisa de uma cópia dessa identidade na sua tabela pública (geralmente chamada de profiles ou usuarios).

O erro amador muito visto espalhado pelo mercado é delegar essa sincronização para o Frontend. Este manual documenta o Padrão Transacional de Registro, garantindo que o seu banco de dados nunca sofra com perfis fantasmas.

---

O Risco da Sincronização via Frontend

A lógica falha tradicional funciona assim no React/Next.js:

1. O frontend chama a API de Sign Up. O usuário é criado no Supabase Auth.
2. O frontend espera o retorno de sucesso.
3. O frontend faz uma segunda requisição inserindo o Nome e E-mail na tabela profiles.

Onde a arquitetura quebra? Se o celular do usuário perder o sinal de internet exatamente no milissegundo entre o Passo 1 e o Passo 3, o seu sistema terá um "Usuário Fantasma". Ele existe no sistema de login, consegue autenticar, mas não tem uma linha na tabela profiles. Quando o painel do seu sistema tentar ler os dados dele, o software vai travar, disparando um erro "Null Pointer" no meio da tela.

A Solução: Automação Direta no Banco de Dados (Triggers)

A regra de ouro da engenharia de dados é: Nunca confie na rede do cliente para manter a consistência do seu banco.

Para resolvermos isso de forma definitiva, nós cortamos o Frontend da equação de sincronização. Nós configuramos o próprio motor do PostgreSQL para escutar a criação de contas e agir de forma autônoma, na velocidade da luz (latência zero).

Fazemos isso criando uma Função (Function) e um Gatilho (Trigger) diretamente no banco de dados.

O Script SQL Padrão

O script abaixo é a fundação que deve ser executada em todos os novos projetos. Ele diz ao banco de dados: "Toda vez que uma nova linha for inserida na tabela segura auth.users, copie o ID e o E-mail para a tabela pública profiles automaticamente".

-- 1. Criamos a Função de Automação
CREATE OR REPLACE FUNCTION public.handle_new_user()
RETURNS trigger
LANGUAGE plpgsql
SECURITY DEFINER SET search_path = public
AS $$
BEGIN
  -- Inserimos os dados iniciais do usuário de forma automática
  INSERT INTO public.profiles (id, email, nome_completo, criado_em)
  VALUES (
    NEW.id,
    NEW.email,
    NEW.raw_user_meta_data ->> 'nome_completo', -- Extrai o nome enviado no Sign Up
    NOW()
  );
  
  RETURN NEW;
END;
$$;

-- 2. Criamos o Gatilho (Trigger) que acorda a Função
CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW EXECUTE PROCEDURE public.handle_new_user();

O Impacto Transacional

Ao adotar essa arquitetura, o processo se torna Atômico. O usuário não é apenas salvo; ele é registrado de forma indestrutível. Se o seu servidor cair, se a internet do cliente falhar, ou se um ataque DDoS derrubar o frontend, não importa. O banco de dados Postgres executará a inserção na tabela profiles de forma nativa e garantida.

---

O Próximo Nível: Disparando o Vercel Workflows a Partir do Cadastro

A sincronização de dados via Trigger é imediata, mas o que fazer quando o cadastro do usuário exige uma régua de boas-vindas com e-mails espaçados por dias?

• O Erro Clássico: Tentar criar tabelas de filas no Postgres e rodar crons via pg_cron para checar quem cadastrou há 3 dias.
• O Padrão Ouro Moderno: Utilize a extensão pg_net ou um Database Webhook do Supabase apontando diretamente para um Vercel Workflow.

[Usuário cria conta]
       │
       ▼
[Postgres: Trigger Atômico insere em public.profiles]
       │
       ▼ (Database Webhook pg_net em 1ms)
[Vercel Workflow: handleUserOnboarding]
       ├── Envia e-mail de boas-vindas
       ├── await sleep("3d") // Custo zero de CPU
       └── Envia dicas de uso se o perfil estiver incompleto

Dessa forma, o Supabase garante a integridade transacional dos dados em 100% dos cenários, e a Vercel assume a orquestração durável no tempo sem que você precise manter servidores ou filas rodando 24 horas por dia.