Supabase 2026: Postgres 벡터 검색으로 100만+ AI 앱을 구동하는 오픈소스 Firebase 대안 — 설정 가이드

# 프로젝트에는 다음이 포함된다:
# - PostgreSQL 16 데이터베이스
# - 자동 생성 REST API
# - 내장 인증
# - 500 MB 데이터베이스 저장소 (묶제 계층)
# - 1 GB 파일 저장소 (묶제 계층)
# - 2 GB 대역폭 (묶제 계층)

# Supabase CLI 설치
# macOS
brew install supabase/tap/supabase

# Linux
npm install -g supabase

# 설치 확인
supabase --version
# 예상: 1.220.0

# 계정 로그인
supabase login

# 새 프로젝트 초기화
mkdir my-ai-app && cd my-ai-app
supabase init

# 로컬 스택 시작 (Docker 필요)
supabase start

# 출력에는 로컬 API URL, anon key 및 service role key가 포함된다
# API URL: http://localhost:54321
# GraphQL URL: http://localhost:54321/graphql/v1
# anon key: eyJhbGciOiJIUzI1NiIs...

# 공식 자체 호스팅 저장소 클론
git clone https://github.com/supabase/supabase.git
cd supabase/docker

# 환경 변수 복사 및 편집
cp .env.example .env

# 보안 키 생성
openssl rand -base64 32  # JWT 시크릿용
openssl rand -hex 32     # anon/service 키용

# .env를 도메인, SMTP 설정, S3 자격 증명으로 편집
nano .env

# 스택 시작
docker compose up -d

# 모든 서비스가 정상인지 확인
docker compose ps

# 예상 출력:
# NAME                STATUS
# supabase-db         healthy
# supabase-kong       healthy
# supabase-auth       healthy
# supabase-rest       healthy
# supabase-realtime   healthy
# supabase-storage    healthy
# supabase-meta       healthy
# supabase-studio     healthy

# 클라이언트 라이브러리 설치
npm install @supabase/supabase-js

# 또는 Python용
pip install supabase

// TypeScript / Next.js
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

// 연결 테스트
const { data, error } = await supabase.from('test').select('*')
console.log(data)

# Python
from supabase import create_client

supabase = create_client(
    "https://your-project.supabase.co",
    "your-anon-key"
)

# 연결 테스트
response = supabase.table('test').select('*').execute()
print(response.data)

-- Supabase SQL 편집기 또는 psql에서
CREATE EXTENSION IF NOT EXISTS vector;

-- 확장이 설치되었는지 확인
SELECT * FROM pg_extension WHERE extname = 'vector';

-- 임베딩이 있는 문서 테이블 생성
CREATE TABLE documents (
    id          BIGSERIAL PRIMARY KEY,
    title       TEXT NOT NULL,
    content     TEXT NOT NULL,
    source_url  TEXT,
    embedding   VECTOR(1536),  -- OpenAI text-embedding-3-large와 일치
    metadata    JSONB DEFAULT '{}',
    created_at  TIMESTAMPTZ DEFAULT NOW()
);

-- 빠른 유사성 검색을 위한 HNSW 인덱스 생성
CREATE INDEX idx_documents_embedding
ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

-- 하이브리드 검색을 위한 전체 텍스트 검색 인덱스 추가
CREATE INDEX idx_documents_fts ON documents
USING GIN (to_tsvector('english', content));

# Python: 임베딩 생성 및 Supabase에 삽입
from supabase import create_client
import openai

supabase = create_client(SUPABASE_URL, SUPABASE_KEY)
client = openai.OpenAI(api_key=OPENAI_API_KEY)

def insert_document(title: str, content: str, source_url: str = None):
    # 임베딩 생성
    response = client.embeddings.create(
        input=content,
        model="text-embedding-3-large"
    )
    embedding = response.data[0].embedding

    # Supabase에 삽입
    result = supabase.table('documents').insert({
        'title': title,
        'content': content,
        'source_url': source_url,
        'embedding': embedding,
        'metadata': {'word_count': len(content.split())}
    }).execute()
    return result

# 샘플 문서 삽입
insert_document(
    title="Docker Best Practices 2026",
    content="Use multi-stage builds to reduce image size...",
    source_url="https://docs.docker.com"
)

-- 순수 SQL: 가장 유사한 상위 5개 문서 찾기
SELECT
    id,
    title,
    content,
    1 - (embedding <=> :query_embedding::vector) AS similarity
FROM documents
ORDER BY embedding <=> :query_embedding::vector
LIMIT 5;

# Python: RAG 검색 함수
async def search_similar_documents(query: str, top_k: int = 5):
    # 쿼리 임베딩 생성
    response = client.embeddings.create(
        input=query,
        model="text-embedding-3-large"
    )
    query_embedding = response.data[0].embedding

    # Supabase 쿼리
    result = await supabase.rpc(
        'match_documents',
        {
            'query_embedding': query_embedding,
            'match_threshold': 0.7,
            'match_count': top_k
        }
    ).execute()
    return result.data

-- 문서 검색을 위한 저장 프로시저 생성
CREATE OR REPLACE FUNCTION match_documents(
    query_embedding VECTOR(1536),
    match_threshold FLOAT,
    match_count INT
)
RETURNS TABLE (
    id BIGINT,
    title TEXT,
    content TEXT,
    similarity FLOAT
)
LANGUAGE plpgsql
AS $$
BEGIN
    RETURN QUERY
    SELECT
        d.id,
        d.title,
        d.content,
        1 - (d.embedding <=> query_embedding) AS similarity
    FROM documents d
    WHERE 1 - (d.embedding <=> query_embedding) > match_threshold
    ORDER BY d.embedding <=> query_embedding
    LIMIT match_count;
END;
$$;

# rag_pipeline.py
from supabase import create_client
from openai import OpenAI
import json

class SupabaseRAG:
    def __init__(self, supabase_url: str, supabase_key: str, openai_key: str):
        self.supabase = create_client(supabase_url, supabase_key)
        self.openai = OpenAI(api_key=openai_key)

    def embed_and_store(self, chunks: list[dict]):
        """임베딩이 있는 문서 청크를 저장한다."""
        for chunk in chunks:
            embedding = self.openai.embeddings.create(
                input=chunk['text'],
                model="text-embedding-3-large"
            ).data[0].embedding

            self.supabase.table('documents').insert({
                'title': chunk['title'],
                'content': chunk['text'],
                'embedding': embedding,
                'metadata': chunk.get('metadata', {})
            }).execute()

    def retrieve(self, query: str, top_k: int = 5) -> list[dict]:
        """벡터 검색을 사용하여 관련 문서를 검색한다."""
        query_embedding = self.openai.embeddings.create(
            input=query,
            model="text-embedding-3-large"
        ).data[0].embedding

        results = self.supabase.rpc(
            'match_documents',
            {
                'query_embedding': query_embedding,
                'match_threshold': 0.75,
                'match_count': top_k
            }
        ).execute()
        return results.data

    def generate(self, query: str, context: list[dict]) -> str:
        """검색된 컨텍스트를 사용하여 응답을 생성한다."""
        context_text = "\n\n".join([
            f"[출처: {doc['title']}]\n{doc['content']}"
            for doc in context
        ])

        response = self.openai.chat.completions.create(
            model="gpt-4.1-mini",
            messages=[
                {
                    "role": "system",
                    "content": "도움이 되는 어시스턴트입니다. 제공된 컨텍스트만을 기반으로 답변하세요. 출처를 인용하세요."
                },
                {
                    "role": "user",
                    "content": f"컨텍스트:\n{context_text}\n\n질문: {query}"
                }
            ],
            temperature=0.3,
            max_tokens=1000
        )
        return response.choices[0].message.content

    def chat(self, query: str) -> dict:
        """엔드투엔드 RAG 파이프라인."""
        context = self.retrieve(query)
        answer = self.generate(query, context)
        return {
            'query': query,
            'answer': answer,
            'sources': [doc['title'] for doc in context],
            'similarity_scores': [doc['similarity'] for doc in context]
        }

# 사용법
rag = SupabaseRAG(SUPABASE_URL, SUPABASE_KEY, OPENAI_KEY)
result = rag.chat("Docker 모범 사례는 무엇인가?")
print(result['answer'])

-- 행 수준 보안 활성화
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;

-- 정책 생성: 사용자는 자신의 문서만 읽을 수 있음
CREATE POLICY "사용자는 자신의 문서를 읽을 수 있음"
ON documents FOR SELECT
USING (auth.uid() = user_id);

-- 정책 생성: 사용자는 자신의 문서만 삽입할 수 있음
CREATE POLICY "사용자는 자신의 문서를 삽입할 수 있음"
ON documents FOR INSERT
WITH CHECK (auth.uid() = user_id);

// 새 사용자 가입
const { data: authData, error: authError } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'secure-password-123'
})

// 로그인
const { data: session } = await supabase.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'secure-password-123'
})

// API 호출을 위한 액세스 토큰
const accessToken = session.session?.access_token

// 인증 컨텍스트가 있는 쿼리 (RLS 자동 적용)
const { data } = await supabase
  .from('documents')
  .select('*')

# Python: 서비스 역할 키를 사용한 서버 측 인증
supabase_admin = create_client(SUPABASE_URL, SERVICE_ROLE_KEY)

# 관리 작업을 위해 RLS 우회
all_docs = supabase_admin.table('documents').select('*').execute()

// 실시간 데이터베이스 변경 구독
const channel = supabase
  .channel('documents-changes')
  .on(
    'postgres_changes',
    { event: 'INSERT', schema: 'public', table: 'documents' },
    (payload) => {
      console.log('새 문서 삽입됨:', payload.new)
      // 재인덱싱, 알림 또는 UI 업데이트 트리거
    }
  )
  .subscribe()

// 완료 시 구독 취소
supabase.removeChannel(channel)

# Python asyncio 버전
import asyncio

async def subscribe_to_changes():
    channel = supabase.channel('documents-changes')
    
    def handle_insert(payload):
        print(f"새 문서: {payload['new']['title']}")
    
    channel.on(
        'postgres_changes',
        {'event': 'INSERT', 'schema': 'public', 'table': 'documents'},
        handle_insert
    ).subscribe()

asyncio.run(subscribe_to_changes())

# Edge 함수 초기화
supabase functions new ai-completion

# 생성된 파일 편집
# supabase/functions/ai-completion/index.ts

// supabase/functions/ai-completion/index.ts
import { serve } from 'https://deno.land/std@0.224.0/http/server.ts'

serve(async (req) => {
  const { prompt } = await req.json()

  // 에지에서 OpenAI API 호출
  const response = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${Deno.env.get('OPENAI_API_KEY')}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-4.1-mini',
      messages: [{ role: 'user', content: prompt }],
      max_tokens: 500
    })
  })

  const data = await response.json()

  return new Response(
    JSON.stringify({ completion: data.choices[0].message.content }),
    { headers: { 'Content-Type': 'application/json' } }
  )
})

# 비밀 설정
supabase secrets set OPENAI_API_KEY=sk-...

# 함수 배포
supabase functions deploy ai-completion

# HTTP를 통해 호출
supabase functions invoke ai-completion --data '{"prompt": "Explain RAG"}'

# docker-compose.prod.yml (발췌)
services:
  db:
    image: supabase/postgres:15.8.1.040
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      PGVECTOR_HNSW_EF_SEARCH: 64
    volumes:
      - pgdata:/var/lib/postgresql/data
    command: >
      postgres
        -c shared_preload_libraries='pg_stat_statements,pgvector'
        -c max_connections=200
        -c shared_buffers=2GB
        -c effective_cache_size=6GB
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  kong:
    image: kong:3.7
    environment:
      KONG_DATABASE: "off"
      KONG_DECLARATIVE_CONFIG: /var/lib/kong/kong.yml
    ports:
      - "8000:8000"
    depends_on:
      - auth
      - rest
      - realtime

volumes:
  pgdata:

# 프로덕션용 .env 파일
POSTGRES_PASSWORD=$(openssl rand -base64 32)
JWT_SECRET=$(openssl rand -base64 32)
ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# 인증 이메일용 SMTP
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=SG.xxx

# S3 호환 스토리지
STORAGE_S3_BUCKET=your-bucket
STORAGE_S3_ENDPOINT=s3.amazonaws.com
STORAGE_S3_ACCESS_KEY=AKIA...
STORAGE_S3_SECRET_KEY=...

# pg_dump를 사용한 자동화된 매일 백업
0 2 * * * docker exec supabase-db pg_dump -U postgres -Fc postgres > /backups/supabase-$(date +\%Y\%m\%d).dump

# 또는 Supabase의 내장 특정 시점 복구(PITR) 사용
# Pro 계층 이상에서 사용 가능

# 새 마이그레이션 생성
supabase migration new add_documents_table

# 생성된 SQL 파일 편집
# supabase/migrations/20260519000000_add_documents_table.sql

# 로컬 인스턴스에 적용
supabase db reset

# 프로덕션에 배포
supabase db push

# 스키마에서 TypeScript 타입 생성
supabase gen types typescript --local > src/types/supabase.ts