05-infrastructure-falkordb

Dec 7, 2025

FalkorDB 연결 및 설정

코드: lib/graph/config.ts, lib/graph/client.ts

왜 FalkorDB인가?

선택 이유

Redis 프로토콜 호환: 기존 Redis 인프라/도구 활용 가능
Cypher 쿼리 지원: Neo4j와 동일한 쿼리 언어
벡터 인덱스 내장: 별도 벡터 DB 없이 임베딩 검색 가능
경량화: Neo4j 대비 리소스 사용량 적음
오픈소스: MIT 라이센스

고려했던 대안

DB	장점	단점	선택하지 않은 이유
Neo4j	성숙한 생태계, 강력한 쿼리	무거움, 라이센스 비용	리소스 과다
DGraph	분산 처리	학습 곡선	단일 노드에서 오버킬
Memgraph	실시간 스트리밍	커뮤니티 작음	문서/예제 부족

설계 결정

1. 싱글톤 패턴

// lib/graph/client.ts
declare global {
  var __falkordb_client: FalkorDBClient | undefined;
}

왜?

Next.js의 Hot Module Reload(HMR)에서 모듈이 다시 로드될 때마다 새 연결 생성 방지
global 객체는 HMR에서도 유지됨

대안: 매번 새 연결

장점: 코드 단순
단점: 연결 풀 고갈, 성능 저하
선택하지 않음: 실제 운영에서 문제 발생

2. Lazy Connection

async query<T>(cypher: string, params?: QueryParams): Promise<QueryResult<T>> {
  await this.ensureConnected();  // 첫 쿼리 시 연결
  // ...
}

왜?

앱 시작 시간 단축 (DB 연결 대기 없음)
DB가 다운되어 있어도 앱은 시작 가능
실제 쿼리 필요 시점까지 연결 지연

대안: import 시 즉시 연결

장점: 시작 시점에 연결 오류 감지
단점: 앱 시작 지연, 불필요한 연결
선택하지 않음: 서버리스 환경에서 Cold Start 영향

3. 지수 백오프 재연결

const delay = this.cfg.retryDelay * Math.pow(2, this.retryCount - 1);
// 1초 → 2초 → 4초 → ...

왜?

일시적 네트워크 오류 복구
DB 재시작 시 자동 복구
급격한 재시도로 인한 부하 방지

사용 예시

기본 쿼리

import { client } from '@/lib/graph';

// 노드 생성
const result = await client.query(
  'CREATE (n:Memory {id: $id, content: $content}) RETURN n',
  { id: 'mem-123', content: '회의록' }
);

console.log(result.metadata.nodesCreated); // 1

읽기 전용 쿼리

// roQuery는 RO_QUERY 명령 사용 (읽기 복제본에서 실행 가능)
const result = await client.roQuery(
  'MATCH (n:Memory) WHERE n.id = $id RETURN n',
  { id: 'mem-123' }
);

연결 상태 확인

import { client } from '@/lib/graph';

console.log(client.state);      // 'disconnected' | 'connecting' | 'connected' | 'error'
console.log(client.isConnected); // boolean

환경 변수

변수	기본값	설명
`FALKORDB_HOST`	`localhost`	호스트
`FALKORDB_PORT`	`6379`	포트
`FALKORDB_PASSWORD`	(없음)	인증 비밀번호
`FALKORDB_GRAPH_NAME`	`momo`	그래프 이름
`FALKORDB_CONNECTION_TIMEOUT`	`5000`	연결 타임아웃 (ms)
`FALKORDB_MAX_RETRIES`	`3`	최대 재시도 횟수
`FALKORDB_RETRY_DELAY`	`1000`	재시도 간격 (ms)

운영 가이드

Docker로 실행

# FalkorDB 시작
docker compose up -d falkordb

# 연결 확인
docker exec momo-falkordb redis-cli ping
# PONG

# Cypher 쿼리 테스트
docker exec momo-falkordb redis-cli GRAPH.QUERY momo "RETURN 1"

데이터 백업

# RDB 스냅샷 (Docker 볼륨에서)
docker exec momo-falkordb redis-cli BGSAVE

모니터링

# 메모리 사용량
docker exec momo-falkordb redis-cli INFO memory

# 그래프 통계
docker exec momo-falkordb redis-cli GRAPH.QUERY momo "MATCH (n) RETURN count(n)"

다음 문서

노드 스키마 - MemoryNode 등 노드 타입 정의
관계 타입 - 노드 간 관계 정의

‹

›