SurrealDB 3 기술(스킬)
SurrealDB 3의 아키텍처, 개발, 운영에 대한 전문가 수준의 기술을 제공합니다. SurrealQL, 멀티모델 데이터 모델링, 그래프 탐색, 벡터 검색, 보안, 배포, 성능 튜닝, SDK 통합, 그리고 SurrealKit, SurrealMCP, n8n, CodeMirror, 에이전트 기술 표면을 포함한 광범위한 SurrealDB 생태계를 다룹니다.
AI 에이전트를 위한 정보
전체 기능 매니페스트, 의사 결정 트리, 출력 계약을 확인하려면 다음 명령어를 실행하세요:
uv run {baseDir}/scripts/onboard.py --agent
완전한 구조화된 브리핑은 AGENTS.md를 참조하세요.
| 명령어 | 기능 |
|---|---|
uv run {baseDir}/scripts/doctor.py | 상태 확인: surreald CLI, 연결성, 버전 확인 |
uv run {baseDir}/scripts/doctor.py --check | 빠른 통과/실패 확인 (종료 코드만 반환) |
uv run {baseDir}/scripts/schema.py introspect | 실행 중인 SurrealDB 인스턴스의 전체 스키마 덤프 |
uv run {baseDir}/scripts/schema.py tables | 필드 수와 인덱스가 포함된 모든 테이블 목록 |
uv run {baseDir}/scripts/onboard.py --agent | 에이전트 통합용 JSON 기능 매니페스트 |
사전 요구 사항
- surreal CLI --
brew install surrealdb/tap/surreal(macOS) 또는 설치 문서 참조 - Python 3.10+ -- 기술 스크립트 실행에 필요
- uv --
brew install uv(macOS) 또는pip install uv또는 uv 문서 참조
선택 사항:
- Docker -- 컨테이너화된 SurrealDB 인스턴스용 (
docker run surrealdb/surrealdb:v3) - 선호하는 SDK -- JavaScript, Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift 또는 Ruby
보안 참고사항: 이 기술은 패키지 관리자 및 컨테이너 설치만 문서화합니다. 원격의 한 줄 셸 설치 프로그램보다 Homebrew, apt/dnf, Cargo, npm 또는 Docker를 통한 감사 가능한 설치를 선호합니다.
빠른 시작
자격 증명 경고: 아래 예제는 로컬 개발 전용으로
root/root를 사용합니다. 프로덕션 또는 공유 인스턴스에는 기본 자격 증명을 절대 사용하지 마세요. 비로컬 환경에는 범위가 지정된 최소 권한 사용자를 생성하세요.
# 로컬 개발 전용으로 SurrealDB를 인메모리로 시작
surreal start memory --user root --pass root --bind 127.0.0.1:8000
# 지속적인 RocksDB 스토리지로 시작 (로컬 개발)
surreal start rocksdb://data/mydb.db --user root --pass root
# SurrealKV로 시작 (시간 여행 쿼리 지원, 로컬 개발)
surreal start surrealkv://data/mydb --user root --pass root
# CLI REPL을 통해 연결 (로컬 개발)
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test
# SurrealQL 파일 가져오기
surreal import --endpoint http://localhost:8000 --user root --pass root --ns test --db test schema.surql
# 데이터베이스 내보내기
surreal export --endpoint http://localhost:8000 --user root --pass root --ns test --db test backup.surql
# 버전 확인
surreal version
# 기술 상태 확인 실행
uv run {baseDir}/scripts/doctor.py
환경 변수
| 변수 | 설명 | 기본값 |
|---|---|---|
SURREAL_ENDPOINT | SurrealDB 서버 URL | http://localhost:8000 |
SURREAL_USER | 루트 또는 네임스페이스 사용자 이름 | root |
SURREAL_PASS | 루트 또는 네임스페이스 비밀번호 | root |
SURREAL_NS | 기본 네임스페이스 | test |
SURREAL_DB | 기본 데이터베이스 | test |
이 변수들은 surreal sql CLI 플래그 (--endpoint, --user, --pass, --ns, --db)에 직접 매핑되며 공식 SurrealDB SDK에서 인식합니다.
핵심 기능
SurrealQL 숙달
SurrealQL 쿼리 언어의 전체 범위: CREATE, SELECT, UPDATE, UPSERT, DELETE, RELATE, INSERT, LIVE SELECT, DEFINE, REMOVE, INFO, 서브쿼리, 트랜잭션, 퓨처, 그리고 모든 내장 함수 (배열, 암호화, 기간, 지리, 수학, 메타, 객체, 파싱, 랜덤, 문자열, 시간, 타입, 벡터)를 다룹니다.
참조: rules/surrealql.md
멀티모델 데이터 모델링
SurrealDB의 멀티모델 기능을 활용하는 스키마 설계 -- 문서 컬렉션, 그래프 엣지, 관계형 참조, 벡터 임베딩, 시계열 데이터, 지리공간 좌표 -- 모두 단일 데이터베이스와 단일 쿼리 언어로 처리합니다.
참조: rules/data-modeling.md
그래프 쿼리
JOIN 없이 일급 그래프 탐색. RELATE는 레코드 간에 타입이 지정된 엣지를 생성합니다. -> (나가는 방향), <- (들어오는 방향), <-> (양방향) 연산자로 탐색합니다. 모든 깊이에서 필터링, 집계, 재귀가 가능합니다.
참조: rules/graph-queries.md
벡터 검색
HNSW 인덱스(v3 벡터 인덱스 타입; 인덱스 빌드/재빌드 중 폴백으로 brute-force 사용 가능)를 사용한 내장 벡터 유사도 검색. 벡터 필드를 정의하고, 구성 가능한 거리 메트릭(코사인, 유클리드, 맨해튼, 민코프스키)으로 인덱스를 생성하고, vector::similarity::* 함수로 쿼리합니다. SurrealQL에서 직접 RAG 파이프라인과 시맨틱 검색을 구축하세요.
참조: rules/vector-search.md
보안 및 권한
DEFINE TABLE ... PERMISSIONS를 통한 행 수준 보안, 네임스페이스/데이터베이스/레코드 수준 액세스 제어, JWT/토큰 기반 인증을 위한 DEFINE ACCESS, 시스템 사용자를 위한 DEFINE USER, 그리고 권한 조건자를 위한 $auth/$session 런타임 변수.
참조: rules/security.md
배포 및 운영
단일 바이너리 배포, Docker, Kubernetes (Helm 차트), 스토리지 엔진 선택(memory, RocksDB, SurrealKV, 분산용 TiKV), 백업/복원, 모니터링, 프로덕션 강화.
참조: rules/deployment.md
성능 튜닝
인덱스 전략(unique, search, vector HNSW), EXPLAIN을 사용한 쿼리 최적화, 연결 풀링, 스토리지 엔진 트레이드오프, 배치 작업, 리소스 제한.
참조: rules/performance.md
SDK 통합
JavaScript/TypeScript (Node.js, Deno, Bun, 브라우저), Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift (iOS/macOS/visionOS), Ruby용 공식 SDK. 소스 전용 C 바인딩, Python v3 미출시 API 경계, .NET v0.10.2 베타 표면, 연결 프로토콜, 인증 흐름, 라이브 쿼리 구독, 타입이 지정된 레코드 처리를 포함합니다.
참조: rules/sdks.md
Surrealism WASM 확장
SurrealDB 3의 새로운 기능: Rust로 작성되고 WASM으로 컴파일된 사용자 정의 함수, 분석기, 로직으로 데이터베이스를 확장합니다. Surrealism 모듈을 정의, 배포, 관리합니다.
참조: rules/surrealism.md
SurrealML 데이터베이스 내 추론 (프리뷰 / 불안정)
surrealml은 이 스냅샷 기준으로 GitHub v0.1.2 릴리스가 있지만 PyPI는 여전히 surrealml 0.0.4를 최신 패키지로 노출합니다. .surml 아티팩트 형식과 [sklearn], [torch], [tensorflow] 엑스트라는 안정적인 문서화된 경계입니다. DEFINE MODEL, INFO FOR MODEL, REMOVE MODEL, ml::name<version>(...), surreal ml import, db.upload_ml(...) 및 SurMlFile.from_<framework>(...) 팩토리 메서드에 대한 v1.4.0 문서는 v1.4.1에서 철회되었습니다. 현재 Python 설정 경로는 LOCAL_BUILD=TRUE가 설정되지 않는 한 GitHub 릴리스에서 네이티브 라이브러리를 다운로드하므로 프로덕션 사용 전에 고정 및 감사를 수행하세요.
참조: rules/surrealml.md
SurrealMCP -- 모델 컨텍스트 프로토콜 서버
공식 MCP 서버 (surrealdb/surrealmcp)는 MCP 호환 AI 호스트(Claude Desktop, Cursor, VS Code의 GitHub Copilot, Zed, n8n)가 하나의 구성 항목을 통해 SurrealDB를 읽고 쓸 수 있게 합니다. 소스(cargo install --path .) 또는 Docker에서 설치; crates.io나 npm에는 없습니다. 바이너리는 start 서브커맨드가 필요합니다. 도구 와이어 이름은 snake_case입니다: query, select, insert, create, upsert, update, delete, relate, connect_endpoint, use_namespace, use_database, list_namespaces, list_databases, disconnect_endpoint, 그리고 클라우드 도구.
참조: rules/surrealmcp.md, skills/surrealmcp/SKILL.md
편집기 도구
surrealql-language-server v0.1.3은 자사 LSP 기준선입니다; surql-lsp v0.1.1은 별도의 커뮤니티 크레이트로 남아 있습니다. 이 규칙은 tree-sitter, 자사 편집기 확장, 그리고 사용자 정의 웹 편집기를 위한 @surrealdb/codemirror / @surrealdb/lezer v1.0.5를 추적합니다. 확장별 명령 팔레트 및 설정은 여전히 각 확장 README를 진실 공급원으로 사용해야 합니다.
참조: rules/editor-tooling.md
LangChain 통합 (Python 전용)
langchain-surrealdb 0.2.1 (Python; langchain-core ~= 1.1.0, surrealdb ~= 1.0.8 v1 SDK)은 생성자 SurrealDBVectorStore(embeddings, conn)를 통해 SurrealDB를 벡터 스토어로 노출합니다. v1.4.0의 JS 패키지, async 클래스, 채팅 기록, 하이브리드 리트리버는 v1.4.1에서 철회되었습니다.
참조: rules/langchain.md
생태계 통합
아직 전용 규칙이 없는 공식 문서 및 자사 인접 표면: 자체 호스팅 n8n을 위한 @surrealdb/n8n-nodes-surrealdb v0.6.0, 공식 AI 프레임워크 문서 인덱스, 로드맵 전용인 Spectron / Agent Memory Context, CodeMirror 패키지, 공식 surrealdb/agent-skills 저장소. 이 규칙을 사용하여 로드맵 또는 포인터 페이지를 프로덕션 API로 제시하지 않도록 하세요.
참조: rules/ecosystem-integrations.md
생태계 도구
- Surrealist -- SurrealDB용 공식 IDE 및 GUI (스키마 디자이너, 쿼리 편집기, 그래프 시각화 도구)
- Surreal-Sync -- 다른 데이터베이스에서 마이그레이션을 위한 변경 데이터 캡처(CDC)
- SurrealFS -- SurrealDB 기반 AI 에이전트 파일 시스템
- SurrealKit -- 원하는 상태 스키마 동기화, 롤아웃 기반 마이그레이션, 시딩, 선언적 테스트
- SurrealML -- 프리뷰 단계
.surml아티팩트 도구; 서버 호출 표면은 여전히 불안정 - SurrealMCP -- AI 에이전트용 모델 컨텍스트 프로토콜 서버
- n8n -- 자체 호스팅 n8n 워크플로우를 위한 공식 범위 커뮤니티 패키지
- CodeMirror -- 사용자 정의 편집기를 위한 공식 SurrealQL 구문 패키지
- setup-surreal -- CI 워크플로우에서 SurrealDB를 실행하기 위한 공식 GitHub Action (
surrealdb/setup-surreal@v2). CLI 부트스트랩이 아닙니다(v1.4.0 문서에서 CLI 부트스트랩으로 설명되었지만 v1.4.2에서 철회됨)
참조: rules/surrealist.md, rules/surreal-sync.md, rules/surrealfs.md, rules/surrealkit.md, rules/surrealml.md, rules/surrealmcp.md, rules/ecosystem-integrations.md, rules/deployment.md (setup-surreal 부분)
진단 / 상태 확인
# 전체 진단 (stderr에 Rich 출력, stdout에 JSON)
uv run {baseDir}/scripts/doctor.py
# 빠른 확인 (종료 코드 0 = 정상, 1 = 문제 발견)
uv run {baseDir}/scripts/doctor.py --check
# 특정 엔드포인트 확인
uv run {baseDir}/scripts/doctor.py --endpoint http://my-server:8000
의사 스크립트는 다음을 확인합니다: surreald CLI 설치 및 PATH에 있음, 서버 연결 가능, 인증 성공, 네임스페이스 및 데이터베이스 존재, 버전 호환성, 스토리지 엔진 상태.
스키마 내부 조사
# 전체 스키마 덤프 (모든 테이블, 필드, 인덱스, 이벤트, 액세스)
uv run {baseDir}/scripts/schema.py introspect
# 요약과 함께 테이블 목록
uv run {baseDir}/scripts/schema.py tables
# 특정 테이블 검사
uv run {baseDir}/scripts/schema.py table <table_name>
# 스키마를 SurrealQL로 내보내기 (재현 가능한 DEFINE 문)
uv run {baseDir}/scripts/schema.py export --format surql
# 스키마를 JSON으로 내보내기
uv run {baseDir}/scripts/schema.py export --format json
내부 조사는 INFO FOR DB, INFO FOR TABLE, INFO FOR NS를 사용하여 전체 스키마를 재구성합니다.
규칙 참조
| 규칙 파일 | 범위 |
|---|---|
rules/surrealql.md | SurrealQL 구문, 문, 함수, 연산자, 관용구 |
rules/data-modeling.md | 스키마 디자인, 레코드 ID, 필드 타입, 관계, 정규화 |
rules/graph-queries.md | RELATE, 그래프 탐색 연산자, 경로 표현식, 재귀 쿼리 |
rules/vector-search.md | 벡터 필드, HNSW 인덱스(v3 벡터 인덱스 타입), 유사도 함수, RAG 패턴 |
rules/security.md | 권한, 액세스 제어, 인증, JWT, 행 수준 보안 |
rules/deployment.md | 설치, 스토리지 엔진, Docker, Kubernetes, 프로덕션 구성; surrealdb/setup-surreal@v2 GitHub Action (CI 전용; CLI 부트스트랩 아님) |
rules/performance.md | 인덱스, EXPLAIN, 쿼리 최적화, 배치 작업, 리소스 튜닝 |
rules/sdks.md | JS/TS, Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift, Ruby SDK 사용법, 연결 패턴, 라이브 쿼리 |
rules/surrealism.md | WASM 확장, 사용자 정의 함수, Surrealism 모듈 작성 |
rules/surrealml.md | SurrealML 프리뷰 범위, .surml 아티팩트, 패키지/릴리스 경계, 네이티브 종속성 경고 |
rules/surrealmcp.md | 모델 컨텍스트 프로토콜 서버: 도구 카탈로그, 호스트 구성, 전송, 배포 |
rules/editor-tooling.md | LSP, tree-sitter 문법, CodeMirror, VS Code / JetBrains / Neovim / Helix / Sublime / Zed 확장 |
rules/langchain.md | LangChain Python 통합: 벡터 스토어, 생성자 API, custom_filter 경계 |
rules/ecosystem-integrations.md | n8n, AI 프레임워크 문서 인덱스, Spectron 로드맵 경계, CodeMirror, 공식 Agent Skills 저장소 |
rules/surrealist.md | Surrealist IDE/GUI 사용법, 스키마 디자이너, 쿼리 편집기 |
rules/surreal-sync.md | CDC 마이그레이션 도구, 소스/대상 커넥터, 마이그레이션 워크플로우 |
rules/surrealfs.md | AI 에이전트 파일 시스템, 파일 스토리지, 메타데이터, 검색 패턴 |
rules/surrealkit.md | 원하는 상태 스키마 동기화, 롤아웃 기반 마이그레이션, 시딩, 선언적 DB 테스트 |
rules/gotchas.md | 도메인 간 에지 케이스 및 주의사항: 업그레이드, 그래프, 벡터, 보안, MCP, SDK (v3.1.4+) |
워크플로우 예제
모든 워크플로우 예제는 로컬 개발 전용으로
root/root를 사용합니다. 프로덕션의 경우 범위가 지정된 최소 권한 자격 증명으로DEFINE USER를 사용하세요.
새 프로젝트 설정
# 1. 환경 확인
uv run {baseDir}/scripts/doctor.py
# 2. SurrealDB 시작
surreal start rocksdb://data/myproject.db --user root --pass root
# 3. 스키마 설계 (지침은 rules/data-modeling.md 참조)
# 4. 초기 스키마 가져오기
surreal import --endpoint http://localhost:8000 --user root --pass root \
--ns myapp --db production schema.surql
# 5. 내부 조사로 확인
uv run {baseDir}/scripts/schema.py introspect
기존 데이터베이스에서 마이그레이션
…
[번역을 위해 잘림]