Pular para o conteúdo

Conectando o Supabase

DocumentosConexão: híbridoAtualizado em

Ver o que a Toca faz com o Supabase →

Em homologação

Abrir integrações no app

A conexão com o Supabase liga a Toca ao projeto do seu app ou do seu site: as tabelas do banco e os arquivos do Storage. São quatro jeitos de conectar, todos no mesmo card. O mais simples é Entrar com o Supabase: você autoriza no Supabase, volta à Toca e escolhe o projeto. Também dá para usar um token de acesso da sua conta do Supabase, ou colar a chave do projeto: a chave secreta, ou a chave publicável com um papel dedicado à Toca no banco.

Esta integração está em homologação: a conexão funciona normalmente, mas as consultas no chat ainda estão em validação.

O que a tela do Supabase pede. O Supabase autoriza aplicativos por organização, então a tela de autorização pede acesso à organização inteira: ver os projetos e as chaves deles. A Toca usa esse acesso uma vez só: lê a chave secreta do projeto que você escolher, guarda só essa chave e desfaz a autorização logo em seguida. Nada da organização fica guardado. Com o token de acesso é igual: a Toca lê a chave do projeto e não guarda o token.

Nesses dois caminhos a Toca fica com a chave secreta do projeto, que dá acesso total aos dados e ignora o RLS (Row Level Security). Para escolher, tabela por tabela, o que a Toca vê e altera, use o papel dedicado.

Antes de começar

  • Use uma conta do Supabase com acesso ao projeto e que veja as chaves dele em Project Settings → API Keys. Se a sua conta não vê a chave secreta, a Toca também não vê.
  • Recomendado: crie antes uma chave secreta só para a Toca, chamada toca, em Project Settings → API Keys. Entrando com o Supabase ou com o token de acesso, a Toca usa a chave com esse nome; sem ela, usa a default ou a única que houver. Com a chave toca, você tira o acesso da Toca apagando só ela, sem mexer nas chaves do seu app.
  • Para o token de acesso:
    • Gere o token nas configurações da sua conta do Supabase, em Access Tokens (supabase.com/dashboard/account/tokens). Ele começa com sbp_.
    • Limite o token à organização ou ao projeto que a Toca vai usar e marque só três permissões, todas em leitura: Projects (account-wide), API Keys e API Key Secrets. O guia Personal Access Tokens do Supabase explica como.
  • Para colar a chave do projeto:
    • Copie a URL do projeto, no botão Connect do painel ou em Integrations → Data API. Ela tem o formato https://abcdefghijklmnopqrst.supabase.co.
    • Chave secreta: copie a chave secreta (ela começa com sb_secret_) em Project Settings → API Keys. Ela dá acesso total aos dados do projeto e ignora o RLS.
    • Papel dedicado: a Toca só enxerga e altera o que você liberar. Pede alguém que rode SQL no banco e use a CLI do Supabase. Os passos estão logo abaixo.

Como criar o papel dedicado. No SQL Editor do Supabase, rode o SQL abaixo, trocando pedidos pelas tabelas que a Toca pode ver e notas pelos buckets do Storage. Tire o trecho de escrita se quiser a Toca só lendo.

-- O papel da Toca
create role toca;
grant toca to authenticator;
grant anon to toca;

-- Leitura de uma tabela (repita para cada tabela)
grant select on public.pedidos to toca;
create policy "Toca lê pedidos" on public.pedidos
  for select to toca using (true);

-- Escrita na mesma tabela (opcional: tire se a Toca só vai ler)
grant insert, update, delete on public.pedidos to toca;
create policy "Toca insere pedidos" on public.pedidos
  for insert to toca with check (true);
create policy "Toca altera pedidos" on public.pedidos
  for update to toca using (true) with check (true);
create policy "Toca apaga pedidos" on public.pedidos
  for delete to toca using (true);

-- Arquivos de um bucket do Storage (repita para cada bucket)
create policy "Toca vê os buckets" on storage.buckets
  for select to toca using (true);
create policy "Toca lê o bucket notas" on storage.objects
  for select to toca using (bucket_id = 'notas');

Depois, gere o token do papel toca com a CLI do Supabase (supabase gen bearer-jwt --role toca), seguindo a seção “How to create (mint) JWTs” do guia JWT Signing Keys do Supabase. O token tem prazo de validade: anote quando ele vence. Copie também a chave publicável (sb_publishable_...) em Project Settings → API Keys.

Passo a passo

  1. Acesse Configurações → Integrações na Toca.
  2. Localize o card Supabase e clique em Conectar.
  3. Escolha um caminho:
    • Entrar com o Supabase (recomendado): clique no botão. Na janela do Supabase, escolha a organização do projeto e autorize. De volta à Toca, o card mostra os projetos da organização: escolha um e clique em Usar seguido do nome do projeto. Se a organização tiver um projeto só, a Toca conecta direto. A escolha vale por 15 minutos, e Cancelar desfaz a autorização.
    • Token de acesso: cole o token no campo Token de acesso e clique em Buscar projetos. Escolha o projeto e clique em Usar seguido do nome do projeto.
    • Chave do projeto: abaixo de “ou cole a chave do projeto”, preencha URL do projeto, Chave de API (a secreta, sb_secret_..., ou a publicável, sb_publishable_..., no papel dedicado) e Token do papel dedicado (deixe em branco com a chave secreta). Clique em Salvar chave.
  4. O card fica marcado como conectado. Nos dois primeiros caminhos, ele diz qual chave secreta e qual projeto a Toca usa.

O que a Toca acessa

Com a conexão ativa, a Toca lê as linhas das tabelas e views que o acesso alcança (pedidos, leads, cadastros, clientes ou o que o seu banco guardar), as funções de consulta do banco, os buckets do Storage e a lista de arquivos com os metadados. Para um arquivo, ela gera um link assinado para baixar, com validade de até 7 dias: o conteúdo não passa pela Toca.

A Toca também altera as tabelas: insere linhas, atualiza pela coluna única (upsert), altera e apaga as linhas escolhidas por um filtro e executa funções do banco. Toda alteração só acontece mediante sua aprovação explícita, pedido a pedido, dentro do chat. O pedido de aprovação mostra a tabela, o filtro e quantas linhas ele pega hoje.

Algumas travas: alterar ou apagar sem filtro (a tabela inteira) é recusado, e apagar linha ou executar função não se desfaz, o que o pedido de aprovação diz. No Storage a Toca só lê: subir, apagar ou mover arquivo continua no painel do Supabase. Os usuários do login do app (Auth), as Edge Functions e as configurações do projeto e da organização ficam fora: depois de conectar, a Toca só fala com as tabelas e o Storage do projeto escolhido.

Manutenção da conexão

As chaves valem até você apagá-las em Project Settings → API Keys. Apagar a chave que a Toca usa corta o acesso dela; se for a default, corta também o de quem mais a usa, por isso a chave toca é a recomendada. Para trocar de chave ou de projeto, abra o card pelo botão Gerenciar e use Trocar pelo Supabase, o token de acesso ou a chave colada.

Se você fechar a tela sem escolher o projeto nem cancelar, a Toca apaga em 15 minutos o acesso que recebeu do Supabase. O token de acesso não fica com a Toca: depois de conectar, você pode apagá-lo no Supabase.

O token do papel dedicado vence na data que ele traz, e a Toca avisa essa data quando ele vence. Gere outro token, abra o card pelo botão Gerenciar, cole o novo e clique em Atualizar. Por segurança, os valores salvos aparecem mascarados. Para liberar mais uma tabela ou bucket ao papel dedicado, rode de novo o trecho do SQL com o nome dele; o token continua o mesmo.

Para passar da chave secreta para o papel dedicado, atualize a chave e o token no card. Para o caminho contrário, use Excluir integração no menu ⋯ do card e conecte de novo.

Problemas comuns

  • O projeto ainda não tem chave secreta — crie uma chamada toca em Project Settings → API Keys e escolha o projeto de novo.
  • O projeto tem várias chaves secretas — sem uma chamada toca ou default, a Toca não adivinha qual usar. Crie a toca e escolha o projeto de novo.
  • O Supabase não mostrou a chave secreta — no token de acesso, falta a permissão API Key Secrets em leitura. No login, a sua conta precisa ver as chaves do projeto.
  • Nenhum projeto apareceu — no login, autorize a organização do projeto (a tela do Supabase deixa escolher). No token de acesso, confira a organização ou o projeto e a permissão Projects (account-wide) em leitura.
  • A escolha expirou — ela vale 15 minutos. Clique em Entrar com o Supabase de novo.
  • URL recusada — a Toca aceita a URL do projeto, terminada em .supabase.co. O endereço do painel (supabase.com/dashboard/...) não serve. Se o seu projeto usa domínio próprio, fale com o suporte da Toca.
  • A tabela volta vazia — com o papel dedicado, falta a política de leitura da tabela para o papel toca (o create policy ... for select to toca do SQL acima). Com o RLS ligado e sem política, o banco devolve a lista vazia, sem erro.
  • Permissão negada (código 42501) — falta o grant da tabela para o papel toca, como grant select on public.pedidos to toca.
  • Token do papel vencido — gere outro token para o papel toca e atualize no card.
  • Tabela fora do schema public — o schema precisa estar exposto na Data API do Supabase (Integrations → Data API). No chat, diga à Toca o nome do schema.
  • Conectou o projeto errado — abra o card pelo botão Gerenciar e use Trocar pelo Supabase, ou use Excluir integração no menu ⋯ do card e conecte de novo.

Outras integrações de documentos

Abrir integrações no app