Conector Supabase

Conecte seu projeto Supabase para sincronizar registros de banco de dados, dados de autenticação de usuário, eventos de armazenamento de arquivos e alterações em tempo real para automação de engajamento de clientes.

Visão geral

Recursos

• API REST gerada automaticamente, Operações CRUD em qualquer tabela Postgres via PostgREST, sem necessidade de código
• Sincronização de usuários do Auth, Sincronize usuários do Supabase Auth (e-mail, telefone, logins sociais) para sua plataforma de engajamento
• Assinaturas em tempo real, Escute eventos INSERT, UPDATE, DELETE em qualquer tabela em tempo real
• Row Level Security, Todo acesso à API respeita as políticas RLS do Postgres para dados multi-tenant seguros
• Integração com Storage, Rastreie uploads de arquivos e gerencie assets em buckets do Storage
• Edge Functions, Invoque funções serverless em Deno para lógica personalizada e webhooks
• Busca full-text, Aproveite os recursos de busca full-text do Postgres através da API

Pré-requisitos

Antes de começar, certifique-se de ter:

1. Um projeto Supabase (app.supabase.com)
2. A URL da API e as API keys do seu projeto (em Settings → API)
3. Uma conta Tajo com acesso à API

Autenticação

O Supabase usa autenticação por API key. Cada requisição requer o cabeçalho apikey e, opcionalmente, um bearer token Authorization para acesso com escopo de usuário.

# Using anon key (respects RLS)
curl 'https://<project_ref>.supabase.co/rest/v1/customers' \
  -H "apikey: <SUPABASE_ANON_KEY>" \
  -H "Authorization: Bearer <SUPABASE_ANON_KEY>"

# Using service_role key (bypasses RLS)
curl 'https://<project_ref>.supabase.co/rest/v1/customers' \
  -H "apikey: <SUPABASE_SERVICE_ROLE_KEY>" \
  -H "Authorization: Bearer <SUPABASE_SERVICE_ROLE_KEY>"

Configuração

Configuração básica

connectors:
  supabase:
    enabled: true
    project_url: "https://xyzcompany.supabase.co"
    api_key: "${SUPABASE_SERVICE_ROLE_KEY}"

    # Data sync options
    sync:
      users: true
      tables:
        - customers
        - orders
        - products
      storage: true
      realtime: true

    # Map Supabase Auth users to contacts
    user_mapping:
      email: email
      phone: SMS
      user_metadata.full_name: FIRSTNAME
      created_at: SIGNUP_DATE

Mapeamento de campos

Mapeie colunas de tabelas do Supabase para atributos da plataforma de engajamento:

Mapeamento personalizado de tabela

table_mapping:
  customers:
    # Column → Attribute mapping
    email: email
    full_name: FIRSTNAME
    company: COMPANY
    plan: SUBSCRIPTION_PLAN
    mrr: MONTHLY_REVENUE
    created_at: SIGNUP_DATE

  orders:
    # Track as events
    sync_as: events
    event_name: "order_placed"
    properties:
      total: amount
      status: order_status
      items: line_items

Endpoints da API

A API REST do Supabase é gerada automaticamente a partir do schema do seu banco de dados em https://<ref>.supabase.co/rest/v1/.

Operadores de filtragem

Eventos

Eventos do Auth

Eventos do banco de dados (Realtime)

Eventos de webhook

Exemplos de código

Inicializar o conector

import { TajoClient } from '@tajo/sdk';
import { createClient } from '@supabase/supabase-js';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
});

// Connect Supabase project
await tajo.connectors.connect('supabase', {
  projectUrl: process.env.SUPABASE_URL,
  serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY,
});

Sincronizar usuários para contatos

// Sync all Supabase Auth users as contacts
await tajo.connectors.sync('supabase', {
  type: 'full',
  resources: ['users'],
});

// Incremental sync (new/changed users only)
await tajo.connectors.sync('supabase', {
  type: 'incremental',
  resources: ['users'],
  since: '2024-01-01T00:00:00Z',
});

Escutar alterações em tempo real

// Subscribe to new orders for engagement triggers
const supabase = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_SERVICE_ROLE_KEY
);

supabase
  .channel('orders')
  .on('postgres_changes',
    { event: 'INSERT', schema: 'public', table: 'orders' },
    async (payload) => {
      // Forward to Tajo as an event
      await tajo.events.track({
        email: payload.new.customer_email,
        event: 'order_placed',
        properties: {
          order_id: payload.new.id,
          total: payload.new.total,
          items: payload.new.line_items,
        },
      });
    }
  )
  .subscribe();

Consultar e segmentar

// Query customers by plan for targeted campaigns
const { data: proUsers } = await supabase
  .from('customers')
  .select('email, full_name, plan, mrr')
  .eq('plan', 'pro')
  .gt('mrr', 100)
  .order('mrr', { ascending: false });

// Sync to a Brevo list for campaign targeting
await tajo.lists.addContacts(PRO_LIST_ID, proUsers);

Limites de taxa

Solução de problemas

Problemas comuns

Modo de depuração

connectors:
  supabase:
    debug: true
    log_level: verbose
    log_queries: true
    log_realtime: true

Testar conexão

tajo connectors test supabase
# ✓ API connection successful
# ✓ Auth endpoint accessible
# ✓ Tables readable (12 tables found)
# ✓ Storage accessible (3 buckets)
# ✓ Realtime connection established
# ✓ Edge Functions available (4 functions)

Melhores práticas

1. Use a chave service_role apenas no servidor, Nunca a exponha em código do cliente
2. Habilite RLS em todas as tabelas, Mesmo com service_role, projete com RLS para defesa em profundidade
3. Use Realtime para sincronização orientada por eventos, Mais eficiente do que polling para detectar alterações
4. Operações em lote, Use inserções em massa e o filtro in para operações de alto volume
5. Mapeie metadata do usuário, Armazene campos relevantes para engajamento em user_metadata durante o cadastro
6. Use Edge Functions para webhooks, Processe webhooks recebidos com Supabase Edge Functions para tratamento de baixa latência

Segurança

• Autenticação por API Key, Todas as requisições requerem API keys válidas
• Row Level Security (RLS), Controle de acesso nativo do Postgres por linha
• Verificação de JWT, Tokens de Auth são JWTs assinados verificados em cada requisição
• SSL/TLS, Todas as conexões criptografadas em trânsito
• SOC 2 Type II, Supabase é compatível com SOC 2
• Restrições de rede, Lista opcional de permissões de IP em planos pagos

Recursos relacionados

• Conector Shopify
• Conector Stripe
• Conector Auth0
• Documentação oficial do Supabase
• Guia da API REST do Supabase
• Guia do Auth do Supabase