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 전체 텍스트 검색 기능 활용

사전 요구 사항

시작하기 전에 다음이 준비되어 있는지 확인하십시오.

  1. Supabase 프로젝트 (app.supabase.com)
  2. 프로젝트의 API URLAPI 키 (Settings → API에서 확인 가능)
  3. API 접근이 가능한 Tajo 계정

API 키

Supabase는 두 가지 키를 제공합니다: anon(공개, RLS 준수)과 service_role(RLS 우회, 관리자 접근). 서버 측 통합에는 service_role을 사용하고 클라이언트 측에는 anon을 사용하십시오.

인증

Supabase는 API 키 인증을 사용합니다. 모든 요청에는 apikey 헤더가 필요하며, 선택적으로 사용자 범위 접근을 위한 Authorization Bearer 토큰이 필요합니다.

Terminal window
# 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_items

API 엔드포인트

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}POSTPostgres 함수 호출
/auth/v1/signupPOST새 사용자 생성
/auth/v1/token?grant_type=passwordPOST비밀번호로 로그인
/auth/v1/userGET현재 사용자 가져오기
/auth/v1/admin/usersGET모든 사용자 목록 (service_role)
/storage/v1/object/{bucket}/{path}POST파일 업로드
/storage/v1/object/list/{bucket}POST버킷의 파일 목록
/functions/v1/{function_name}POSTEdge 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)
isNull 검사?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 연결
Free500 요청/분200 동시
Pro1,000 요청/초500 동시
Team2,000 요청/초1,000 동시
Enterprise맞춤맞춤

문제 해결

일반적인 문제

문제원인해결 방법
401 Unauthorized잘못되거나 만료된 API 키Supabase Dashboard → Settings → API에서 API 키 확인
403 ForbiddenRLS 정책이 접근 차단관리 작업에는 service_role 키 사용 또는 RLS 정책 확인
실시간 이벤트 없음테이블에 Realtime이 활성화되지 않음Database → Replication → 게시에 테이블 추가하여 활성화
쿼리 결과가 비어 있음RLS가 모든 행 필터링RLS 정책이 인증된 역할의 읽기를 허용하는지 확인
저장소 업로드 실패버킷 정책저장소 버킷이 공개로 설정되어 있거나 올바른 RLS 정책이 있는지 확인

디버그 모드

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

연결 테스트

Terminal window
tajo connectors test supabase
# ✓ API 연결 성공
# ✓ 인증 엔드포인트 접근 가능
# ✓ 테이블 읽기 가능 (12개 테이블 발견)
# ✓ 저장소 접근 가능 (3개 버킷)
# ✓ Realtime 연결 설정됨
# ✓ Edge Functions 사용 가능 (4개 함수)

모범 사례

  1. service_role 키는 서버 측에서만 사용 - 클라이언트 코드에 절대 노출하지 마십시오
  2. 모든 테이블에 RLS 활성화 - service_role을 사용하더라도 심층 방어를 위해 RLS로 설계
  3. 이벤트 기반 동기화에 Realtime 사용 - 변경 사항에 대한 폴링보다 효율적
  4. 작업 배치 처리 - 대량 작업에는 대량 삽입과 in 필터 사용
  5. 사용자 메타데이터 매핑 - 가입 중 참여 관련 필드를 user_metadata에 저장
  6. 웹훅에 Edge Functions 사용 - 저지연 처리를 위해 Supabase Edge Functions로 들어오는 웹훅 처리

보안

  • API 키 인증 - 모든 요청에 유효한 API 키 필요
  • Row Level Security (RLS) - Postgres 네이티브 행별 접근 제어
  • JWT 확인 - 인증 토큰은 모든 요청에서 확인되는 서명된 JWT
  • SSL/TLS - 모든 연결이 전송 중 암호화됨
  • SOC 2 Type II - Supabase는 SOC 2 준수
  • 네트워크 제한 - 유료 요금제에서 선택적 IP 허용 목록

관련 리소스

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

auto-detect
AI 어시스턴트

안녕하세요! 문서에 대해 무엇이든 물어보세요.