Supabase 커넥터
Supabase 프로젝트를 연결하여 데이터베이스 레코드, 사용자 인증 데이터, 파일 저장소 이벤트, 실시간 변경 사항을 동기화하여 고객 참여 자동화를 구현하십시오.
개요
| 속성 | 값 |
|---|---|
| 플랫폼 | Supabase |
| 카테고리 | 데이터베이스 및 백엔드 |
| 설정 복잡도 | 쉬움 |
| 공식 통합 | 예 |
| 동기화 데이터 | 사용자, 테이블, 저장소, 이벤트 |
| 사용 가능한 스킬 | 11 |
| API 유형 | REST (PostgREST) + Realtime WebSocket |
| 공식 문서 | supabase.com/docs |
기능
- 자동 생성 REST API - PostgREST를 통해 모든 Postgres 테이블에 대한 CRUD 작업, 코드 불필요
- 인증 사용자 동기화 - Supabase Auth 사용자(이메일, 전화, 소셜 로그인)를 참여 플랫폼에 동기화
- 실시간 구독 - 모든 테이블의 INSERT, UPDATE, DELETE 이벤트를 실시간으로 수신
- Row Level Security - 모든 API 접근은 보안 멀티테넌트 데이터를 위해 Postgres RLS 정책을 준수
- 저장소 통합 - 파일 업로드를 추적하고 저장소 버킷 간 자산 관리
- Edge Functions - 맞춤 로직 및 웹훅을 위한 서버리스 Deno 함수 호출
- 전체 텍스트 검색 - API를 통해 Postgres 전체 텍스트 검색 기능 활용
사전 요구 사항
시작하기 전에 다음이 준비되어 있는지 확인하십시오.
- Supabase 프로젝트 (app.supabase.com)
- 프로젝트의 API URL 및 API 키 (Settings → API에서 확인 가능)
- API 접근이 가능한 Tajo 계정
API 키
Supabase는 두 가지 키를 제공합니다: anon(공개, RLS 준수)과 service_role(RLS 우회, 관리자 접근). 서버 측 통합에는 service_role을 사용하고 클라이언트 측에는 anon을 사용하십시오.
인증
Supabase는 API 키 인증을 사용합니다. 모든 요청에는 apikey 헤더가 필요하며, 선택적으로 사용자 범위 접근을 위한 Authorization Bearer 토큰이 필요합니다.
# anon 키 사용 (RLS 준수)curl 'https://<project_ref>.supabase.co/rest/v1/customers' \ -H "apikey: <SUPABASE_ANON_KEY>" \ -H "Authorization: Bearer <SUPABASE_ANON_KEY>"
# service_role 키 사용 (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 테이블 열을 참여 플랫폼 속성에 매핑합니다.
기본 사용자 매핑
| Parameter | Type | Description |
|---|---|---|
email required | string | Supabase Auth의 사용자 이메일 (고유 식별자) |
phone optional | string | SMS/WhatsApp 참여를 위한 전화번호 |
user_metadata.full_name optional | string | Auth 사용자 메타데이터의 표시 이름 |
user_metadata.avatar_url optional | string | 프로필 이미지 URL |
created_at optional | timestamp | 계정 생성 타임스탬프 |
last_sign_in_at optional | timestamp | 참여 점수 산출을 위한 가장 최근 로그인 |
app_metadata.provider optional | string | 인증 제공자 (email, google, github 등) |
confirmed_at optional | timestamp | 이메일 확인 타임스탬프 |
맞춤 테이블 매핑
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_itemsAPI 엔드포인트
Supabase REST API는 https://<ref>.supabase.co/rest/v1/에서 데이터베이스 스키마에서 자동으로 생성됩니다.
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/rest/v1/{table} | GET | 필터링, 정렬, 페이지네이션으로 행 쿼리 |
/rest/v1/{table} | POST | 행 삽입 (대량 및 upsert 지원) |
/rest/v1/{table} | PATCH | 필터와 일치하는 행 업데이트 |
/rest/v1/{table} | DELETE | 필터와 일치하는 행 삭제 |
/rest/v1/rpc/{function} | POST | Postgres 함수 호출 |
/auth/v1/signup | POST | 새 사용자 생성 |
/auth/v1/token?grant_type=password | POST | 비밀번호로 로그인 |
/auth/v1/user | GET | 현재 사용자 가져오기 |
/auth/v1/admin/users | GET | 모든 사용자 목록 (service_role) |
/storage/v1/object/{bucket}/{path} | POST | 파일 업로드 |
/storage/v1/object/list/{bucket} | POST | 버킷의 파일 목록 |
/functions/v1/{function_name} | POST | Edge Function 호출 |
필터링 연산자
| 연산자 | 설명 | 예시 |
|---|---|---|
eq | 같음 | ?status=eq.active |
neq | 같지 않음 | ?status=neq.deleted |
gt, gte | 초과 | ?amount=gt.100 |
lt, lte | 미만 | ?created_at=lt.2024-01-01 |
like, ilike | 패턴 일치 | ?name=ilike.%john% |
in | 배열 내 | ?status=in.(active,trial) |
is | Null 검사 | ?deleted_at=is.null |
이벤트
인증 이벤트
| 이벤트 | 트리거 | 사용 사례 |
|---|---|---|
user.signed_up | 신규 사용자 등록 | 환영 시리즈 |
user.signed_in | 사용자 로그인 | 활동 추적 |
user.updated | 프로필 변경 | 데이터 동기화 |
user.deleted | 계정 삭제 | 정리 워크플로 |
데이터베이스 이벤트 (Realtime)
| 이벤트 | 트리거 | 사용 사례 |
|---|---|---|
INSERT | 새 행 추가 | 신규 주문/고객 알림 |
UPDATE | 행 수정 | 상태 변경 워크플로 |
DELETE | 행 제거 | 이탈 감지 |
웹훅 이벤트
| 이벤트 | 트리거 | 사용 사례 |
|---|---|---|
auth.user.created | 웹훅을 통한 사용자 가입 | 온보딩 트리거 |
storage.object.created | 파일 업로드됨 | 자산 처리 |
코드 예제
커넥터 초기화
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);속도 제한
API 속도 제한
Supabase 속도 제한은 요금제에 따라 다릅니다. Free 티어: 500 요청/분. Pro: 1,000 요청/초. Enterprise 한도는 Supabase에 문의하십시오.
| 요금제 | 속도 제한 | Realtime 연결 |
|---|---|---|
| Free | 500 요청/분 | 200 동시 |
| Pro | 1,000 요청/초 | 500 동시 |
| Team | 2,000 요청/초 | 1,000 동시 |
| Enterprise | 맞춤 | 맞춤 |
문제 해결
일반적인 문제
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| 401 Unauthorized | 잘못되거나 만료된 API 키 | Supabase Dashboard → Settings → API에서 API 키 확인 |
| 403 Forbidden | RLS 정책이 접근 차단 | 관리 작업에는 service_role 키 사용 또는 RLS 정책 확인 |
| 실시간 이벤트 없음 | 테이블에 Realtime이 활성화되지 않음 | Database → Replication → 게시에 테이블 추가하여 활성화 |
| 쿼리 결과가 비어 있음 | RLS가 모든 행 필터링 | RLS 정책이 인증된 역할의 읽기를 허용하는지 확인 |
| 저장소 업로드 실패 | 버킷 정책 | 저장소 버킷이 공개로 설정되어 있거나 올바른 RLS 정책이 있는지 확인 |
디버그 모드
connectors: supabase: debug: true log_level: verbose log_queries: true log_realtime: true연결 테스트
tajo connectors test supabase# ✓ API 연결 성공# ✓ 인증 엔드포인트 접근 가능# ✓ 테이블 읽기 가능 (12개 테이블 발견)# ✓ 저장소 접근 가능 (3개 버킷)# ✓ Realtime 연결 설정됨# ✓ Edge Functions 사용 가능 (4개 함수)모범 사례
- service_role 키는 서버 측에서만 사용 - 클라이언트 코드에 절대 노출하지 마십시오
- 모든 테이블에 RLS 활성화 - service_role을 사용하더라도 심층 방어를 위해 RLS로 설계
- 이벤트 기반 동기화에 Realtime 사용 - 변경 사항에 대한 폴링보다 효율적
- 작업 배치 처리 - 대량 작업에는 대량 삽입과
in필터 사용 - 사용자 메타데이터 매핑 - 가입 중 참여 관련 필드를
user_metadata에 저장 - 웹훅에 Edge Functions 사용 - 저지연 처리를 위해 Supabase Edge Functions로 들어오는 웹훅 처리
보안
- API 키 인증 - 모든 요청에 유효한 API 키 필요
- Row Level Security (RLS) - Postgres 네이티브 행별 접근 제어
- JWT 확인 - 인증 토큰은 모든 요청에서 확인되는 서명된 JWT
- SSL/TLS - 모든 연결이 전송 중 암호화됨
- SOC 2 Type II - Supabase는 SOC 2 준수
- 네트워크 제한 - 유료 요금제에서 선택적 IP 허용 목록