[[부록11_Supabase_벡터_저장소_설정_가이드|부록 11]]. Supabase 벡터 저장소 설정 가이드

[!abstract] Supabase 가입, pgvector 활성화, documents 테이블과 match_documents 함수 생성, n8n Credential 등록까지 안내합니다. 이 가이드를 따라하면 n8n에서 Supabase 벡터 저장소를 활용한 RAG 워크플로를 구축할 수 있게 되죠.

n8n의 Supabase Vector Store 노드를 사용하려면, Supabase 프로젝트를 생성하고 벡터 검색 환경을 설정해야 합니다. Supabase는 무료 플랜으로 시작할 수 있으며, 별도의 서버 설치 없이 클라우드에서 바로 사용할 수 있습니다.

이 부록은 다음 내용을 다룹니다.

• Supabase 가입 및 프로젝트 생성
• pgvector 확장 활성화 및 documents 테이블 생성
• match_documents RPC 함수 생성
• Project URL과 API Key 확인
• n8n에 Supabase Credential 등록

[!tip] 6.1.3 FAQ 챗봇 실습에서 오셨나요? 6.1.3 섹션의 Supabase RAG FAQ 챗봇 실습을 위해 이 가이드를 보고 계신다면, 아래 항목을 순서대로 모두 완료한 뒤 돌아가세요.

순서	완료할 항목	비고
1	Supabase 가입	이메일 또는 GitHub
2	프로젝트 생성	리전: Northeast Asia
3	SQL 실행	pgvector + 테이블 + 함수
4	API 정보 확인	Project URL + API Key
5	n8n Credential 등록	Supabase API 인증 정보

5단계까지 완료하면 준비 끝입니다. [[Day26_06.1.3_Supabase_RAG로_사내_FAQ_챗봇_만들기]]로 돌아가세요.

Supabase란?

Supabase는 오픈소스 기반의 클라우드 데이터베이스 플랫폼입니다. PostgreSQL 데이터베이스를 기반으로 하며, pgvector 확장을 통해 벡터 데이터 저장과 유사도 검색을 지원합니다. 쉽게 말해, ==AI가 문서를 이해하고 검색할 수 있는 저장소==를 클릭 몇 번으로 만들어주는 서비스죠.

💡 왜 Supabase인가? n8n의 벡터 저장소 노드는 Pinecone, Qdrant, Supabase 등을 지원합니다. 이 중 Supabase는 무료 플랜이 가장 넉넉하고, 별도 설치 없이 웹 대시보드에서 바로 설정할 수 있어 입문자에게 적합합니다. 신용카드 등록도 필요 없거든요.

[!info] 벡터 저장소가 뭔가요? 일반적인 데이터베이스는 "제목이 A인 행을 찾아줘"처럼 정확히 일치하는 데이터를 검색합니다. 반면 벡터 저장소는 "이 질문과 의미가 비슷한 문서를 찾아줘"라는 식의 유사도 검색이 가능합니다. AI 챗봇이 사용자 질문에 맞는 답변을 찾을 때 바로 이 벡터 저장소를 활용합니다.

Supabase 가입하기

STEP 1. Supabase 웹사이트 접속

1. 브라우저에서 supabase.com에 접속합니다.
2. 우측 상단의 Start your project 버튼을 클릭합니다.

![[그림부록11-1.png]] [그림부록11-1] Supabase 메인 페이지 — 우측 상단의 Start your project 버튼 클릭

STEP 2. 계정 생성

가입 페이지가 나타나면, 다음 방법 중 하나로 가입합니다.

GitHub 계정이 있다면 Continue with GitHub를 클릭하면 빠르게 가입됩니다. GitHub 계정이 없더라도, 이메일과 비밀번호만으로 간단히 가입할 수 있습니다.

![[그림부록11-2.png]] [그림부록11-2] Supabase 가입 화면 — Continue with GitHub 또는 이메일로 Sign Up

GitHub 로그인을 선택하면 GitHub 인증 화면이 나타납니다. Authorize supabase 버튼을 클릭하여 Supabase에 GitHub 계정 접근을 허용합니다.

![[그림부록11-3.png]] [그림부록11-3] GitHub 인증 화면 — Authorize supabase 버튼 클릭

인증이 완료되면 Supabase 대시보드로 자동 이동합니다.

새 프로젝트 생성하기

STEP 3. 대시보드에서 New project 클릭

가입 후 대시보드에 진입하면, 화면 중앙 또는 우측 상단의 New project 버튼을 클릭합니다.

![[그림부록11-4.png]] [그림부록11-4] Supabase 대시보드 — New project 버튼 위치

STEP 4. 프로젝트 정보 입력

프로젝트 생성 폼이 나타나면, 다음 항목을 입력합니다.

![[그림부록11-5.png]] [그림부록11-5] 새 프로젝트 생성 폼 — 이름, 비밀번호, 리전 입력 화면

각 항목을 모두 입력한 뒤, 하단의 Create new project 버튼을 클릭합니다.

![[그림부록11-6.png]] [그림부록11-6] Database Password — Generate a password 버튼으로 안전한 비밀번호 자동 생성

⚠️ 주의: Database Password는 프로젝트 생성 후 변경이 어렵습니다. 반드시 메모해 두세요. 이 비밀번호는 n8n 연동에는 사용하지 않지만, 추후 데이터베이스에 직접 접속할 때 필요합니다.

![[그림부록11-7.png]] [그림부록11-7] Region 선택 — Northeast Asia (Tokyo) 선택

STEP 5. 프로젝트 생성 대기

Create new project 버튼을 클릭하면, 프로젝트 셋업이 시작됩니다. "Setting up project..." 메시지와 함께 약 1~2분이 소요됩니다.

![[그림부록11-8.png]] [그림부록11-8] 프로젝트 생성 진행 중 — Setting up project 메시지

진행 바가 완료되면 프로젝트 대시보드가 나타납니다. 이 화면이 보이면 프로젝트 생성이 성공한 것입니다.

![[그림부록11-9.png]] [그림부록11-9] 프로젝트 생성 완료 — 프로젝트 대시보드 첫 화면

pgvector 활성화 및 테이블 생성

이제 방금 만든 프로젝트에 벡터 검색 환경을 설정합니다. SQL 쿼리 세 줄이면 되니, 코드가 낯설더라도 걱정하지 마세요. 복사해서 붙여넣기만 하면 됩니다.

STEP 6. SQL Editor 열기

프로젝트 대시보드 좌측 사이드바에서 SQL Editor 아이콘을 클릭합니다. 데이터베이스 아이콘 모양이며, 마우스를 올리면 "SQL Editor" 텍스트가 표시됩니다.

![[그림부록11-10.png]] [그림부록11-10] 좌측 사이드바 — SQL Editor 메뉴 위치 (코드 아이콘)

SQL Editor가 열리면, 빈 쿼리 입력 영역이 나타납니다. 여기에 SQL을 입력하고 실행할 수 있습니다.

![[그림부록11-11.png]] [그림부록11-11] SQL Editor 초기 화면 — 빈 쿼리 입력 영역

STEP 7. SQL 전체 복사 및 붙여넣기

아래 SQL을 처음부터 끝까지 전체 복사하여 SQL Editor에 붙여넣습니다. 이 SQL은 세 가지 작업을 한 번에 수행합니다:

-- ============================================
-- 1. pgvector 확장 활성화
-- PostgreSQL에서 벡터 데이터를 다룰 수 있게 해줍니다
-- ============================================
create extension if not exists vector;

-- ============================================
-- 2. documents 테이블 생성
-- AI 임베딩 데이터를 저장하는 테이블입니다
-- ============================================
create table if not exists documents (
  id bigserial primary key,
  content text,
  metadata jsonb,
  embedding vector(3072)
);

-- ============================================
-- 3. 유사도 검색 함수 생성
-- n8n의 Supabase Vector Store 노드가
-- 자동으로 호출하는 함수입니다
-- ============================================
create or replace function match_documents (
  query_embedding vector(3072),
  match_count int default 5,
  filter jsonb default '{}'
) returns table (
  id bigint,
  content text,
  metadata jsonb,
  similarity float
)
language plpgsql
as $
#variable_conflict use_column
begin
  return query
  select
    documents.id,
    documents.content,
    documents.metadata,
    1 - (documents.embedding <=> query_embedding) as similarity
  from documents
  where documents.metadata @> filter
  order by documents.embedding <=> query_embedding
  limit match_count;
end;
$;

![[그림부록11-12.png]] [그림부록11-12] SQL Editor에 전체 SQL을 붙여넣은 모습

[!info] SQL이 낯설어도 괜찮습니다 위 SQL은 한 번만 실행하면 됩니다. 이후에는 n8n이 자동으로 데이터를 저장하고 검색하므로, SQL을 직접 다룰 일은 없습니다. 각 줄이 무슨 역할을 하는지 궁금하다면 아래 용어 설명을 참고하세요.

STEP 8. SQL 실행하기

SQL을 붙여넣었으면, 우측 하단의 Run 버튼을 클릭합니다. 키보드 단축키 Ctrl + Enter (Mac: Cmd + Enter)로도 실행할 수 있습니다.

![[그림부록11-13.png]] [그림부록11-13] Run 버튼 클릭 — 우측 하단에 위치

실행이 성공하면 하단에 Success. No rows returned 메시지가 표시됩니다. 이 메시지는 "SQL이 정상 실행됐고, 조회 결과는 없다"는 뜻입니다. 테이블과 함수를 생성하는 SQL이므로 조회 결과가 없는 것이 정상입니다.

![[그림부록11-14.png]] [그림부록11-14] SQL 실행 성공 — Success. No rows returned 메시지 확인

📖 SQL 용어 설명

용어	설명
pgvector	PostgreSQL에서 벡터 데이터를 저장하고 검색할 수 있게 해주는 확장 기능입니다. Supabase에 기본 내장되어 있어 create extension 한 줄로 활성화됩니다
vector(3072)	3,072차원의 벡터를 저장하는 컬럼 타입입니다. Google Gemini Embedding 모델(gemini-embedding-001)이 3,072차원 벡터를 생성하므로 이 값을 사용합니다
bigserial	자동으로 1, 2, 3... 순서대로 증가하는 숫자 ID입니다. 각 행을 구분하는 고유 번호 역할을 합니다
jsonb	JSON 형식의 데이터를 저장하는 타입입니다. 문서의 출처, 카테고리 등 부가 정보를 저장합니다
<=> 연산자	코사인 거리(Cosine Distance)를 계산하는 pgvector의 연산자입니다. 값이 작을수록 두 벡터가 의미적으로 비슷합니다
match_documents	n8n의 Supabase Vector Store 노드가 유사도 검색 시 자동으로 호출하는 함수입니다. 직접 호출할 필요 없이, n8n이 알아서 사용합니다

⚠️ 임베딩 차원 안내: vector(3072)의 3072는 사용할 임베딩 모델에 따라 달라집니다. 이 가이드에서는 Google Gemini Embedding(gemini-embedding-001, 3,072차원)을 기준으로 합니다.

임베딩 모델	차원	vector() 값
Google gemini-embedding-001	3,072	vector(3072)
OpenAI text-embedding-3-small	1,536	vector(1536)
Google text-embedding-004	768	vector(768)

다른 모델을 사용하시는 경우, SQL의 vector(3072) 부분을 해당 모델의 차원으로 수정하세요. 테이블과 함수 두 곳 모두 변경해야 합니다.

STEP 9. 테이블 생성 확인

SQL 실행이 성공했으면, 실제로 테이블이 잘 만들어졌는지 확인해 봅시다.

1. 좌측 사이드바에서 Table Editor 아이콘을 클릭합니다.

![[그림부록11-15.png]] [그림부록11-15] 좌측 사이드바 — Table Editor 메뉴 위치

2. 좌측 테이블 목록에서 documents 테이블이 보이면 성공입니다.

![[그림부록11-16.png]] [그림부록11-16] Table Editor — documents 테이블이 목록에 표시된 모습

3. documents 테이블을 클릭하면, 4개의 컬럼(id, content, metadata, embedding)이 보입니다. 아직 데이터는 없으며, n8n 워크플로에서 FAQ 데이터를 적재하면 여기에 행이 추가됩니다.

![[그림부록11-17.png]] [그림부록11-17] documents 테이블 구조 — id, content, metadata, embedding 4개 컬럼 확인

💡 함수도 확인하고 싶다면: 좌측 사이드바에서 Database → Functions를 클릭하면 match_documents 함수가 등록된 것을 확인할 수 있습니다.

![[그림부록11-18.png]] [그림부록11-18] Database → Functions — match_documents 함수가 등록된 모습

Project URL과 API Key 확인하기

n8n에서 Supabase에 접속하려면 Project URL과 API Key 두 가지가 필요합니다. 이 두 정보는 Supabase 대시보드의 서로 다른 메뉴에 있으므로, 아래 순서대로 확인합니다.

STEP 10. Project URL 확인

1. 좌측 사이드바 하단의 톱니바퀴 아이콘 (Project Settings)을 클릭합니다.

![[그림부록11-19.png]] [그림부록11-19] 좌측 사이드바 하단 — Project Settings (톱니바퀴) 아이콘

2. 설정 페이지가 열리면, 좌측 메뉴에서 Data API를 클릭합니다.

![[그림부록11-20.png]] [그림부록11-20] Project Settings 좌측 메뉴 — Data API 클릭

3. Project URL 항목에 표시된 URL을 복사합니다. 우측의 Copy 버튼을 클릭하면 클립보드에 복사됩니다.
   • 예: https://qraxybpglcqxgafywgbu.supabase.co

![[그림부록11-21.png]] [그림부록11-21] Data API 페이지 — Project URL 복사 (Copy 버튼 클릭)

STEP 11. API Key 확인

같은 페이지를 아래로 스크롤하면 Project API keys 섹션이 보입니다.

1. anon public 라벨이 붙은 키 옆의 Copy 버튼을 클릭하여 복사합니다.

![[그림부록11-22.png]] [그림부록11-22] Project API keys — anon public 키의 Copy 버튼 클릭

확인한 두 가지 정보를 정리하면 다음과 같습니다.

⚠️ anon 키와 service_role 키의 차이: API Key는 두 종류가 있습니다. n8n 연동에는 anon (public) 키를 사용합니다. service_role 키는 관리자 전용 권한이므로, 보안상 일반적인 용도에서는 사용하지 않습니다. 혹시 service_role 키를 복사했다면, anon public 키로 다시 복사해 주세요.

💡 팁: 메모장이나 텍스트 편집기에 Project URL과 API Key를 미리 붙여넣어 두면 다음 단계에서 바로 사용할 수 있어 편리합니다.

n8n에 Supabase Credential 등록하기

이제 마지막 단계입니다. 앞에서 확인한 Project URL과 API Key를 n8n에 등록하면, n8n이 Supabase에 접속하여 데이터를 저장하고 검색할 수 있게 됩니다.

STEP 12. Credential 생성 화면 열기

1. n8n 화면 좌측 사이드바에서 Credentials 메뉴를 클릭합니다.

![[그림부록11-23.png]] [그림부록11-23] n8n 좌측 사이드바 — Credentials 메뉴 클릭

2. 우측 상단의 Add Credential 버튼을 클릭합니다.

![[그림부록11-24.png]] [그림부록11-24] Credentials 페이지 — Add Credential 버튼 클릭

3. 검색란에 **Supabase**를 입력하면 Supabase API가 나타납니다. 이를 클릭합니다.

![[그림부록11-25.png]] [그림부록11-25] Credential 검색 — Supabase 입력 후 Supabase API 선택

STEP 13. 연결 정보 입력 및 테스트

Credential 설정 화면이 나타나면, 두 개의 필드를 채웁니다.

![[그림부록11-26.png]] [그림부록11-26] Supabase API Credential 설정 화면 — Host와 Service Role Secret 필드

[!info] 필드 이름이 Service Role Secret인데, anon 키를 넣어도 되나요? 네, 괜찮습니다. n8n의 Supabase Credential 필드 이름은 Service Role Secret이지만, anon (public) 키를 입력해도 정상 동작합니다. anon 키는 보안 수준이 낮아 외부 노출에 비교적 안전하고, 일반적인 데이터 읽기/쓰기에 충분합니다. service_role 키는 모든 보안 정책을 우회하는 관리자 키이므로, 꼭 필요한 경우가 아니면 사용을 피하세요.

입력을 마쳤으면:

1. Save 버튼을 클릭합니다.
2. 상단에 Connection tested successfully 메시지가 초록색으로 표시되면 연결 성공입니다.

![[그림부록11-27.png]] [그림부록11-27] Connection tested successfully — 연결 테스트 성공 메시지 (초록색)

💡 Credential 이름 변경하기: 화면 상단의 Credential 이름을 FAQ 챗봇 Supabase처럼 구체적으로 변경해 두면, 여러 프로젝트를 관리할 때 어떤 Supabase 프로젝트인지 바로 구분할 수 있어 편리합니다.

![[그림부록11-28.png]] [그림부록11-28] Credential 이름 변경 — 상단 이름을 클릭하여 구체적인 이름으로 수정

정리하며

이 부록의 핵심을 정리하면 다음과 같습니다.

1. 무료 플랜 + Tokyo 리전: 신용카드 없이 가입 가능하고, Northeast Asia (Tokyo) 리전이 한국에서 가장 빠릅니다.
2. SQL은 한 번만 실행: pgvector 활성화 → documents 테이블 → match_documents 함수까지 한 SQL 블록으로 끝납니다. 이후엔 n8n이 자동으로 데이터를 읽고 씁니다.
3. 벡터 차원은 임베딩 모델과 일치: Gemini Embedding은 3,072차원(vector(3072)), OpenAI text-embedding-3-small은 1,536차원. 모델 변경 시 테이블·함수 두 곳 모두 수정해야 합니다.
4. n8n에서는 anon (public) 키 사용: 필드 이름이 "Service Role Secret"이지만 anon 키로 정상 동작합니다. service_role 키는 보안 정책을 우회하는 관리자 키이므로 일반 사용엔 적합하지 않습니다.
5. Database Password와 API Key는 다른 것: 데이터베이스 직접 접속 비밀번호와, API 호출용 키는 별개입니다. n8n 연동에는 API Key만 사용합니다.

설정 완료 체크리스트

• Supabase 계정이 생성되었는가?
• 프로젝트가 생성되고 리전이 **Northeast Asia (Tokyo)**인가?
• SQL Editor에서 SQL이 Success 메시지와 함께 실행되었는가?
• Table Editor에서 documents 테이블이 보이는가?
• Project URL을 복사해 두었는가?
• **API Key (anon public)**를 복사해 두었는가?
• n8n에 Supabase API Credential이 등록되고 Connection tested successfully가 표시되었는가?

자주 하는 실수와 해결법

💡 다음 단계: 로컬 PC에서 실행 중인 n8n을 외부에서 접근 가능하게 만들고 싶다면 Cloudflare Tunnel을 활용할 수 있습니다. 다음으로 [[부록12_Cloudflare_Tunnel_로컬_n8n_외부_공개_가이드|부록 12. Cloudflare Tunnel — 로컬 n8n 외부 공개 가이드]]를 참고하세요.