---
title: "Supabase 커넥터"
description: "데이터베이스 레코드, 사용자 인증, 파일 저장소, 실시간 이벤트를 참여 플랫폼과 동기화하는 완전한 Supabase 통합 가이드입니다."
url: https://tajo.io/kr/docs/connectors/custom/supabase/
markdown: https://tajo.io/kr/docs/connectors/custom/supabase.md
lang: ko-KR
robots: noindex
---

Tajo 사전 이용 신청

이름과 회사 이메일 주소를 입력하세요. Tajo 이용 신청을 확인할 수 있는 링크를 이메일로 보내드립니다.

# Supabase 커넥터

커넥터 상태: 예정 아직 구축되지 않았습니다. Tajo는 현재 이 커넥터를 실행하지 않습니다.

| 원본 필드 | 대상 필드 | 예시 값 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Supabase 프로젝트를 연결하여 데이터베이스 레코드, 사용자 인증 데이터, 파일 저장소 이벤트, 실시간 변경 사항을 동기화하여 고객 참여 자동화를 구현하십시오.

## 개요

| 속성 | 값 |
| --- | --- |
| **플랫폼** | Supabase |
| **카테고리** | 데이터베이스 및 백엔드 |
| **설정 복잡도** | 쉬움 |
| **공식 통합** | 아니오 |
| **동기화 데이터** | 사용자, 테이블, 저장소, 이벤트 |
| **사용 가능한 스킬** | 11 |
| **API 유형** | REST (PostgREST) + Realtime WebSocket |
| **공식 문서** | [supabase.com/docs](https://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](https://app.supabase.com/))
2. 프로젝트의 **API URL** 및 **API 키** (Settings → API에서 확인 가능)
3. API 접근이 가능한 Tajo 계정

API 키

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

## 인증

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

```bash
# 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>"
```

## 구성

### 기본 설정

```yaml
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 | 이메일 확인 타임스탬프 |

#### 맞춤 테이블 매핑

```yaml
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}` | `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` | 파일 업로드됨 | 자산 처리 |

## 코드 예제

### 커넥터 초기화

```javascript
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,
});
```

### 사용자를 연락처로 동기화

```javascript
// 모든 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',
});
```

### 실시간 변경 사항 수신

```javascript
// 참여 트리거를 위해 새 주문 구독
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();
```

### 쿼리 및 세그먼트화

```javascript
// 타겟 캠페인을 위해 플랜별 고객 쿼리
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 정책이 있는지 확인 |

### 디버그 모드

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

### 연결 테스트

```bash
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 허용 목록

## 관련 리소스

- [Shopify 커넥터](https://tajo.io/kr/docs/connectors/ecommerce/shopify)
- [Stripe 커넥터](https://tajo.io/kr/docs/connectors/ecommerce/stripe)
- [Auth0 커넥터](https://tajo.io/kr/docs/connectors/custom/auth0)
- [Supabase 공식 문서](https://supabase.com/docs)
- [Supabase REST API 가이드](https://supabase.com/docs/guides/api)
- [Supabase Auth 가이드](https://supabase.com/docs/guides/auth)