Коннектор Supabase

Подключите проект Supabase для синхронизации записей базы данных, данных аутентификации пользователей, событий файлового хранилища и изменений в реальном времени для автоматизации взаимодействия с клиентами.

Обзор

Возможности

• Автогенерируемый REST API, CRUD-операции над любой таблицей Postgres через PostgREST без написания кода
• Синхронизация пользователей Auth, синхронизация пользователей Supabase Auth (email, телефон, социальные логины) с платформой вовлечения
• Подписки реального времени, прослушивание событий INSERT, UPDATE, DELETE в любой таблице в реальном времени
• Row Level Security, весь API-доступ соблюдает политики RLS Postgres для безопасной мультиарендной работы с данными
• Интеграция хранилища, отслеживание загрузки файлов и управление ресурсами в корзинах Storage
• Edge Functions, вызов бессерверных Deno-функций для пользовательской логики и вебхуков
• Полнотекстовый поиск, использование возможностей полнотекстового поиска Postgres через API

Предварительные требования

Прежде чем начать, убедитесь, что у вас есть:

1. Проект Supabase (app.supabase.com)
2. API URL и API-ключи проекта (в Settings → API)
3. Аккаунт Tajo с доступом к API

Аутентификация

Supabase использует аутентификацию по API-ключу. Каждый запрос требует заголовка apikey и опционально Bearer-токена Authorization для пользовательского доступа.

# Использование anon key (соблюдает RLS)
curl 'https://<project_ref>.supabase.co/rest/v1/customers' \
  -H "apikey: <SUPABASE_ANON_KEY>" \
  -H "Authorization: Bearer <SUPABASE_ANON_KEY>"

# Использование service_role key (обходит RLS)
curl 'https://<project_ref>.supabase.co/rest/v1/customers' \
  -H "apikey: <SUPABASE_SERVICE_ROLE_KEY>" \
  -H "Authorization: Bearer <SUPABASE_SERVICE_ROLE_KEY>"

Конфигурация

Базовая настройка

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

    # Параметры синхронизации данных
    sync:
      users: true
      tables:
        - customers
        - orders
        - products
      storage: true
      realtime: true

    # Сопоставление пользователей Supabase Auth с контактами
    user_mapping:
      email: email
      phone: SMS
      user_metadata.full_name: FIRSTNAME
      created_at: SIGNUP_DATE

Сопоставление полей

Сопоставьте столбцы таблиц Supabase с атрибутами платформы вовлечения:

Сопоставление пользовательских таблиц

table_mapping:
  customers:
    # Сопоставление столбцов с атрибутами
    email: email
    full_name: FIRSTNAME
    company: COMPANY
    plan: SUBSCRIPTION_PLAN
    mrr: MONTHLY_REVENUE
    created_at: SIGNUP_DATE

  orders:
    # Трекинг как события
    sync_as: events
    event_name: "order_placed"
    properties:
      total: amount
      status: order_status
      items: line_items

Эндпоинты API

REST API Supabase автогенерируется из схемы базы данных по адресу https://<ref>.supabase.co/rest/v1/.

Операторы фильтрации

События

События Auth

События базы данных (Realtime)

События вебхуков

Примеры кода

Инициализация коннектора

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

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

// Подключение проекта Supabase
await tajo.connectors.connect('supabase', {
  projectUrl: process.env.SUPABASE_URL,
  serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY,
});

Синхронизация пользователей с контактами

// Синхронизация всех пользователей Supabase Auth как контактов
await tajo.connectors.sync('supabase', {
  type: 'full',
  resources: ['users'],
});

// Инкрементальная синхронизация (только новые/изменённые пользователи)
await tajo.connectors.sync('supabase', {
  type: 'incremental',
  resources: ['users'],
  since: '2024-01-01T00:00:00Z',
});

Прослушивание изменений в реальном времени

// Подписка на новые заказы для триггеров вовлечения
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) => {
      // Пересылка в Tajo как событие
      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();

Запрос и сегментация

// Запрос клиентов по плану для таргетированных кампаний
const { data: proUsers } = await supabase
  .from('customers')
  .select('email, full_name, plan, mrr')
  .eq('plan', 'pro')
  .gt('mrr', 100)
  .order('mrr', { ascending: false });

// Синхронизация в лист Brevo для таргетирования кампании
await tajo.lists.addContacts(PRO_LIST_ID, proUsers);

Ограничения скорости

Устранение неполадок

Частые проблемы

Режим отладки

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

Проверка подключения

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)

Лучшие практики

1. Используйте service_role key только на стороне сервера, никогда не раскрывайте его в клиентском коде
2. Включайте RLS для всех таблиц, даже с service_role проектируйте с учётом RLS для эшелонированной защиты
3. Используйте Realtime для синхронизации по событиям, эффективнее опроса для отслеживания изменений
4. Пакетные операции, используйте массовые вставки и фильтр in для высокопроизводительных операций
5. Сопоставляйте метаданные пользователей, храните поля, значимые для вовлечения, в user_metadata при регистрации
6. Используйте Edge Functions для вебхуков, обрабатывайте входящие вебхуки с помощью Supabase Edge Functions для минимальной задержки

Безопасность

• Аутентификация по API Key, все запросы требуют действительных API-ключей
• Row Level Security (RLS), нативный для Postgres контроль доступа на уровне строки
• JWT-верификация, токены Auth представляют собой подписанные JWT, проверяемые при каждом запросе
• SSL/TLS, все соединения зашифрованы при передаче
• SOC 2 Type II, Supabase соответствует SOC 2
• Ограничения сети, опциональное IP-разрешение на платных планах

Связанные ресурсы

• Коннектор Shopify
• Коннектор Stripe
• Коннектор Auth0
• Официальная документация Supabase
• Руководство по Supabase REST API
• Руководство по Supabase Auth