SurrealDB 3 전문가 스킬
GitHub Copilot을 위한 SurrealDB 3 아키텍처, 개발 및 운영 전문가 수준 지원.
Copilot이 이 스킬을 사용해야 하는 경우
사용자가 다음과 같은 작업을 할 때 자동으로 활성화됩니다:
- SurrealQL 쿼리를 작성하거나 질문할 때
.surql파일을 작업할 때- SurrealDB 데이터베이스 스키마를 설계할 때
- SurrealDB 배포 또는 Docker를 구성할 때
- SurrealDB SDK(JavaScript, Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift, Ruby)를 사용할 때
- 그래프 관계(RELATE, 탐색)를 작업할 때
- 벡터 검색이나 RAG 패턴을 구현할 때
- 보안, 권한, 접근 제어를 구성할 때
- Surrealism WASM 확장을 구축할 때
- 다른 데이터베이스에서 SurrealDB로 데이터를 마이그레이션할 때
- SurrealDB를 MCP 호스트, n8n, AI 프레임워크, 맞춤 편집기에 연결할 때
규칙 참조
이 스킬은 18개의 상세 규칙 파일을 포함합니다. 사용자의 요청이 특정 도메인과 일치하면 해당 규칙 파일을 읽으세요:
| 규칙 파일 | 로드해야 할 때 | 도메인 |
|---|---|---|
| surrealql.md | SurrealQL 쿼리 작성 또는 디버깅 | 전체 SurrealQL 언어 참조 |
| data-modeling.md | 스키마 설계, 필드 유형 선택, 레코드 ID | 멀티모델 스키마 설계 패턴 |
| graph-queries.md | RELATE, 그래프 탐색, 경로 표현식 | 그래프 엣지 및 탐색 패턴 |
| vector-search.md | HNSW 인덱스, 유사도 검색, 임베딩 | 벡터 검색 및 RAG 파이프라인 |
| security.md | 권한, 인증, JWT, 접근 제어 | 행 수준 보안 및 인증 흐름 |
| deployment.md | SurrealDB 설치, 구성, 실행 | 스토리지 엔진, Docker, Kubernetes |
| performance.md | 느린 쿼리, 인덱스 전략, EXPLAIN | 성능 튜닝 및 최적화 |
| sdks.md | 애플리케이션 코드에서 SurrealDB 사용 | JS, Python, Go, Rust, Java, Kotlin, .NET, C, PHP, Swift, Ruby 패턴 |
| surrealism.md | WASM 확장 작성 | Rust to WASM 확장 개발 |
| surrealml.md | SurrealML 관련 작업 | .surml 경계 및 네이티브 종속성 경고 미리보기 |
| surrealmcp.md | AI 호스트 연결 | MCP 도구 카탈로그 및 배포 |
| editor-tooling.md | 편집기 / IDE 지원 | LSP, tree-sitter, CodeMirror, 편집기 확장 |
| langchain.md | LangChain RAG | Python 벡터 저장소 API |
| ecosystem-integrations.md | n8n / 프레임워크 포인터 | n8n, AI 프레임워크 문서, Spectron 경계, Agent Skills |
| surrealist.md | Surrealist IDE/GUI 사용 | IDE 기능 및 스키마 디자이너 |
| surreal-sync.md | 다른 데이터베이스에서 마이그레이션 | Postgres, Mongo 등에서 CDC 동기화 |
| surrealfs.md | AI 에이전트 파일 시스템 작업 | SurrealDB 기반 가상 파일 시스템 |
| surrealkit.md | 스키마 동기화, 롤아웃, 시드, 선언형 테스트 | SurrealDB 앱을 위한 원하는 상태 스키마 관리 |
빠른 참조
SurrealQL 필수 사항
-- 레코드 생성
CREATE person:alice SET name = 'Alice', age = 30;
-- 그래프 엣지
RELATE person:alice->follows->person:bob SET since = time::now();
-- 그래프 탐색
SELECT ->follows->person.name AS following FROM person:alice;
-- 벡터 검색 (HNSW)
DEFINE INDEX idx_embed ON document FIELDS embedding HNSW DIMENSION 1536 DIST COSINE;
SELECT * FROM document WHERE embedding <|10,40|> $query_vector;
-- 행 수준 권한
DEFINE TABLE post SCHEMALESS PERMISSIONS
FOR select WHERE published = true OR user = $auth.id
FOR create, update WHERE user = $auth.id;
-- 실시간 쿼리
LIVE SELECT * FROM person WHERE age > 25;
주요 개념
- 레코드 ID:
table:id(예:person:alice) -- 일급 시민, JOIN 불필요 - 멀티모델: 문서 + 그래프 + 벡터 + 시계열 + 지리공간을 하나의 DB에서 지원
- 그래프 연산자:
->(나가는 방향),<-(들어오는 방향),<->(양방향) - KNN 연산자:
<|K,EF|>여기서 K=이웃 수, EF=검색 매개변수 (거리 측정 기준이 아님) - 스토리지 엔진: 메모리, RocksDB, SurrealKV(시간 이동), TiKV(분산)
- WASM 확장: v3의 새로운 기능 -- Rust로 작성하고 WASM으로 컴파일한 후 DEFINE MODULE로 등록
스크립트
# 상태 확인
uv run scripts/doctor.py
# 스키마 인트로스펙션
uv run scripts/schema.py introspect
# 업스트림 업데이트 확인
uv run scripts/check_upstream.py
보안 참고 사항
- 예제는 로컬 개발 전용으로
root/root를 사용합니다. 프로덕션에서는 범위가 지정된 자격 증명을 사용하세요. - 스크립트는 사용자가 지정한 엔드포인트에만 연결됩니다. 타사 네트워크 호출은 없습니다.
- 테이블 이름은 쿼리 보간 전에
[a-zA-Z_][a-zA-Z0-9_]*정규식에 대해 검증됩니다. - 원격 셸 설치 프로그램보다 패키지 관리자 또는 컨테이너 설치를 선호하세요.