pgvector 2026: PostgreSQL을 고성능 벡터 데이터베이스로 전환 — 설치, 튜닝 및 RAG 통합 가이드

-- HNSW 인덱스 (대부분의 워크로드에 권장)
CREATE INDEX ON documents
  USING hnsw (embedding vector_l2_ops)
  WITH (m = 16, ef_construction = 64);

-- IVFFlat 인덱스 (빌드가 더 빠르지만 리콜이 낮음)
CREATE INDEX ON documents
  USING ivfflat (embedding vector_l2_ops)
  WITH (lists = 100);

-- L2 거리 (작을수록 더 유사)
SELECT id, embedding <-> query_vec AS distance
FROM documents ORDER BY distance LIMIT 10;

-- 코사인 거리 (정규화된 임베딩용)
SELECT id, embedding <=> query_vec AS distance
FROM documents ORDER BY distance LIMIT 10;

docker run -d \
  --name pgvector-demo \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_DB=vectordb \
  -p 5432:5432 \
  pgvector/pgvector:0.8.2-pg18

# 확인
docker exec pgvector-demo psql -U postgres -d vectordb -c "SELECT * FROM pg_extension WHERE extname = 'vector';"

# 빌드 종속성 설치 (Ubuntu/Debian)
sudo apt-get install postgresql-server-dev-18 build-essential git

# pgvector 클론 및 빌드
git clone --branch v0.8.2 https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

# 데이터베이스에서 확장 활성화
psql -U postgres -d mydb -c "CREATE EXTENSION IF NOT EXISTS vector;"

-- pgvector는 Supabase에 사전 설치되어 있음. 활성화만 하면 됨:
CREATE EXTENSION IF NOT EXISTS vector;

-- 버전 확인
SELECT extversion FROM pg_extension WHERE extname = 'vector';
-- 반환: 0.8.2

-- RDS PostgreSQL 18에서 pgvector는 확장으로 사용 가능
CREATE EXTENSION IF NOT EXISTS vector;

-- 필요시 사용 가능한 확장 확인
SELECT * FROM pg_available_extensions WHERE name = 'vector';

-- pgvector 버전 확인
SELECT extversion FROM pg_extension WHERE extname = 'vector';
-- 예상: 0.8.2

-- 벡터 타입 테스트
SELECT '[1,2,3]'::vector(3) <-> '[4,5,6]'::vector(3) AS l2_distance;
-- 예상: ~5.196

-- 벡터 컬럼이 있는 테이블 생성 (1536 차원 = OpenAI 임베딩)
CREATE TABLE documents (
    id          BIGSERIAL PRIMARY KEY,
    title       VARCHAR(512) NOT NULL,
    content     TEXT,
    embedding   vector(1536),
    metadata    JSONB DEFAULT '{}',
    created_at  TIMESTAMPTZ DEFAULT NOW(),
    tenant_id   INTEGER NOT NULL DEFAULT 0
);

-- 일반적인 필터 컬럼에 인덱스 추가
CREATE INDEX idx_docs_tenant ON documents(tenant_id);
CREATE INDEX idx_docs_created ON documents(created_at);

-- 임베딩이 있는 단일 문서 삽입
INSERT INTO documents (title, content, embedding, metadata, tenant_id)
VALUES (
    'Introduction to pgvector',
    'pgvector adds vector support to PostgreSQL...',
    ARRAY_FILL(0.0::real, ARRAY[1536])::vector(1536),  -- 플레이스홀더
    '{"author": "dibi8", "category": "database"}',
    1
);

-- 실제 OpenAI 임베딩으로 삽입 (Python에서)
-- 전체 예제는 아래 RAG 통합 섹션 참조

# Python에서 벡터 일괄 삽입
import psycopg2
import numpy as np

conn = psycopg2.connect("dbname=vectordb user=postgres password=mysecretpassword host=localhost")
cur = conn.cursor()

-- 샘플로 1만 개의 랜덤 벡터 생성
batch_size = 10000
titles = [f"document_{i}" for i in range(batch_size)]
contents = [f"Content for document {i}" for i in range(batch_size)]
embeddings = np.random.randn(batch_size, 1536).astype(np.float32)
tenant_ids = [i % 10 for i in range(batch_size)]

# 일괄 삽입을 위해 executemany 사용
args = [(titles[i], contents[i], embeddings[i].tolist(), tenant_ids[i]) for i in range(batch_size)]
cur.executemany(
    "INSERT INTO documents (title, content, embedding, tenant_id) VALUES (%s, %s, %s::vector, %s)",
    args
)
conn.commit()
print(f"{batch_size}개 문서 삽입 완료")

-- 병렬 인덱스 빌드용 파라미터 설정
SET maintenance_work_mem = '8GB';
SET max_parallel_maintenance_workers = 4;

-- 튜닝된 파라미터로 HNSW 인덱스 구축
CREATE INDEX idx_docs_embedding_hnsw ON documents
  USING hnsw (embedding vector_l2_ops)
  WITH (
    m = 16,              -- 레이어별 연결 수 (기본값: 16)
    ef_construction = 128  -- 동적 후보 목록 크기 (기본값: 64)
  );

-- 인덱스 크기 확인
SELECT pg_size_pretty(pg_relation_size('idx_docs_embedding_hnsw'));
-- 일반적: 1536 차원의 10만 벡터에 대해 ~450 MB

-- 기본 ANN 검색
SELECT id, title, embedding <-> $1::vector AS distance
FROM documents
ORDER BY embedding <-> $1::vector
LIMIT 10;

-- 필터링된 벡터 검색 (가장 일반적인 프로덕션 패턴)
SELECT id, title, embedding <-> $1::vector AS distance
FROM documents
WHERE tenant_id = 42
  AND created_at > NOW() - INTERVAL '30 days'
  AND metadata->>'category' = 'tech'
ORDER BY embedding <-> $1::vector
LIMIT 20;

-- 먼저 전문 검색을 위해 pg_trgm 활성화
CREATE EXTENSION IF NOT EXISTS pg_trgm;

-- 벡터 유사성 + 텍스트 관련성 결합
SELECT
    d.id,
    d.title,
    d.embedding <-> $1::vector AS vec_distance,
    similarity(d.title, $2) AS text_similarity
FROM documents d
WHERE d.title % $2  -- trigram 유사성 필터
ORDER BY
    (d.embedding <-> $1::vector) * 0.7 + (1 - similarity(d.title, $2)) * 0.3
LIMIT 10;

-- 리콜 대 지연 시간을 위한 ef_search 튜닝
-- 높을수록 = 리콜이 더 좋지만 쿼리가 더 느림
SET hnsw.ef_search = 100;  -- 기본값은 40; 프로덕션에서는 64-128이 일반적

-- 실제 쿼리 계획 확인
EXPLAIN (ANALYZE, BUFFERS)
SELECT id, title, embedding <-> $1::vector AS distance
FROM documents
ORDER BY embedding <-> $1::vector
LIMIT 10;
-- 표시되어야 함: Index Scan using idx_docs_embedding_hnsw

-- 양자화된 스토리지를 위한 halfvec 컬럼 추가
ALTER TABLE documents ADD COLUMN embedding_half halfvec(1536);

-- 전체 정밀도에서 변환
UPDATE documents SET embedding_half = embedding::halfvec;

-- halfvec에 HNSW 인덱스 생성
CREATE INDEX idx_docs_embedding_half_hnsw ON documents
  USING hnsw (embedding_half halfvec_l2_ops);

-- halfvec을 사용한 쿼리 (거의 동일한 결과)
SELECT id, title, embedding_half <-> $1::halfvec AS distance
FROM documents
ORDER BY embedding_half <-> $1::halfvec
LIMIT 10;

-- 공간 절약 확인
SELECT
    pg_size_pretty(pg_relation_size('idx_docs_embedding_hnsw')) AS full_size,
    pg_size_pretty(pg_relation_size('idx_docs_embedding_half_hnsw')) AS half_size;
-- half_size는 일반적으로 full_size의 ~45-50%

; pgvector 워크로드를 위한 pgbouncer.ini
[databases]
vectordb = host=localhost port=5432 dbname=vectordb

[pgbouncer]
pool_mode = transaction
max_client_conn = 10000
default_pool_size = 50
reserve_pool_size = 10

pip install langchain-postgres==0.0.13 langchain-openai==0.3.0

from langchain_postgres import PGVector
from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(model="text-embedding-3-large")

vector_store = PGVector(
    connection="postgresql://postgres:mysecretpassword@localhost:5432/vectordb",
    embeddings=embeddings,
    collection_name="documents",
    use_jsonb=True,
)

# 문서 추가
from langchain_core.documents import Document
docs = [
    Document(page_content="pgvector turns PostgreSQL into a vector database", metadata={"source": "blog"}),
    Document(page_content="HNSW indexes provide fast ANN search", metadata={"source": "docs"}),
]
vector_store.add_documents(docs)

# 필터가 있는 유사성 검색
results = vector_store.similarity_search(
    "vector database for RAG",
    k=5,
    filter={"source": "blog"}
)
for doc in results:
    print(f"Content: {doc.page_content}")

pip install llama-index-vector-stores-postgres==0.4.2

from llama_index.vector_stores.postgres import PGVectorStore
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.embeddings.openai import OpenAIEmbedding

vector_store = PGVectorStore.from_params(
    host="localhost",
    port=5432,
    database="vectordb",
    user="postgres",
    password="mysecretpassword",
    table_name="llama_index_docs",
    embed_dim=1536,
    hnsw_kwargs={
        "hnsw_m": 16,
        "hnsw_ef_construction": 128,
        "hnsw_ef_search": 100,
        "hnsw_dist_method": "vector_l2_ops",
    },
)

# 문서 로드
documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents, vector_store=vector_store)

# 쿼리
query_engine = index.as_query_engine()
response = query_engine.query("How does pgvector work?")
print(response)

import psycopg2
from openai import OpenAI
import numpy as np

client = OpenAI()
conn = psycopg2.connect("dbname=vectordb user=postgres password=mysecretpassword host=localhost")

def get_embedding(text: str) -> list[float]:
    resp = client.embeddings.create(
        model="text-embedding-3-large", input=text, dimensions=1536
    )
    return resp.data[0].embedding

def retrieve_documents(query: str, top_k: int = 5, tenant_id: int = 1):
    query_vec = get_embedding(query)
    cur = conn.cursor()
    cur.execute("""
        SELECT title, content, embedding <=> %s::vector AS distance
        FROM documents
        WHERE tenant_id = %s
        ORDER BY embedding <=> %s::vector
        LIMIT %s
    """, (query_vec, tenant_id, query_vec, top_k))
    return cur.fetchall()

# 전체 RAG 파이프라인
def rag_query(user_question: str) -> str:
    docs = retrieve_documents(user_question, top_k=5)
    context = "\n\n".join([f"Title: {d[0]}\n{d[1]}" for d in docs])
    
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "Answer based on the provided context."},
            {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {user_question}"}
        ]
    )
    return response.choices[0].message.content

print(rag_query("What is pgvector used for?"))

-- RLS 활성화
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;

-- 정책: 테넌트는 자신의 문서만 볼 수 있음
CREATE POLICY tenant_isolation ON documents
    USING (tenant_id = current_setting('app.current_tenant')::INTEGER);

-- 세션별 테넌트 설정
SET app.current_tenant = '42';

-- 이제 모든 쿼리가 자동으로 테넌트별로 필터링됨
SELECT * FROM documents;  -- 테넌트 42의 문서만 표시

-- 느린 벡터 쿼리 추적
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- 지연 시간별 상위 벡터 쿼리 찾기
SELECT query, mean_exec_time, calls
FROM pg_stat_statements
WHERE query LIKE '%<->%'
ORDER BY mean_exec_time DESC
LIMIT 10;

# postgresql.conf에서 pg_stat_statements 활성화
shared_preload_libraries = 'pg_stat_statements'
pg_stat_statements.track = all
pg_stat_statements.max = 10000

# 벡터 데이터를 포함한 전체 백업
pg_dump -h localhost -U postgres -d vectordb -Fc > vectordb_backup.dump

# 복원
pg_restore -h localhost -U postgres -d vectordb_restore vectordb_backup.dump

# 벡터는 텍스트 배열로 백업되고 정확하게 복원됨

# 프로덕션 워크로드를 위한 연결 풀링 사용
from psycopg2 import pool

conn_pool = pool.ThreadedConnectionPool(
    minconn=5,
    maxconn=50,
    host="localhost",
    database="vectordb",
    user="postgres",
    password="mysecretpassword"
)

def search_with_pool(query_vec, limit=10):
    conn = conn_pool.getconn()
    try:
        cur = conn.cursor()
        cur.execute(
            "SELECT id, title FROM documents ORDER BY embedding <-> %s::vector LIMIT %s",
            (query_vec, limit)
        )
        return cur.fetchall()
    finally:
        conn_pool.putconn(conn)

SELECT title, embedding <-> $1::vector AS distance
FROM documents
WHERE tenant_id = 42
  AND created_at > NOW() - INTERVAL '7 days'
  AND metadata @> '{"status": "published"}'
ORDER BY embedding <-> $1::vector
LIMIT 10;

-- ef_search 값 벤치마크
SET hnsw.ef_search = 64;
EXPLAIN ANALYZE SELECT ... ORDER BY embedding <-> $1 LIMIT 10;

SET hnsw.ef_search = 128;
EXPLAIN ANALYZE SELECT ... ORDER BY embedding <-> $1 LIMIT 10;