SurrealKit -- SurrealDB 앱을 위한 스키마 관리
SurrealKit은 SurrealDB 애플리케이션 스키마를 원하는 상태의 .surql 파일로 관리하며,
개발용 임시 데이터베이스와 공유 또는 프로덕션 롤아웃을 위한 별도 경로를 제공합니다.
추적된 업스트림 스냅샷: v0.6.3 프리릴리스 (7771b93ea563, 2026-05-13).
v0.6.1 -> v0.6.3 패치 라인은 라이브러리 잠금 수정, 템플릿 변수,
주석 제거 정리, DROP ... IF EXISTS 처리, BUCKET, SEQUENCE, CONFIG에 대한 DEFINE 범위를 추가했습니다.
빠른 시작
# 설치
cargo binstall surrealkit
# 또는: cargo install surrealkit
# 프로젝트 구조 스캐폴딩
surrealkit init
# 로컬/임시 데이터베이스를 로컬 스키마 파일에 맞춤
surrealkit sync
# 공유/프로덕션용 검토된 롤아웃 생성 및 적용
surrealkit rollout plan --name add_customer_indexes
surrealkit rollout start 20260410120000__add_customer_indexes
surrealkit rollout complete 20260410120000__add_customer_indexes
핵심 명령어
| 명령어 | 용도 |
|---|---|
surrealkit sync | 로컬, 미리보기, 또는 임시 DB에 대한 원하는 상태 조정 |
surrealkit sync --watch | 파일 감시와 함께 로컬 개발 루프 |
surrealkit rollout baseline | 기존 공유 DB에 롤아웃 추적 설정 |
surrealkit rollout plan --name <name> | 현재 스키마 차이로부터 검토된 매니페스트 생성 |
surrealkit rollout start <id> | 확장 단계 적용 |
surrealkit rollout complete <id> | 전환 후 축소/파괴 단계 적용 |
surrealkit rollout rollback <id> | 진행 중인 롤아웃 롤백 |
surrealkit rollout lint <id> | DB를 변경하지 않고 롤아웃 검증 |
surrealkit rollout status | DB에 저장된 롤아웃 상태 확인 |
surrealkit seed | 시드 데이터 적용 |
surrealkit test | 선언적 스키마, 권한, API 테스트 실행 |
사용 시점
sync는 데이터베이스가 로컬 파일을 즉시 미러링해야 할 때 사용합니다.rollout은 변경 사항에 단계 준비, 검토, 롤백, 또는 통제된 전환이 필요할 때 사용합니다.seed는 결정론적 픽스처 데이터를 위해 사용합니다.test는 CI에서 권한, 스키마 동작, API 계약을 검증하기 위해 사용합니다.
환경 변수
SurrealKit은 다음 변수를 읽습니다:
SURREALDB_HOST(대체:DATABASE_HOST)SURREALDB_NAME(대체:DATABASE_NAME)SURREALDB_NAMESPACE(대체:DATABASE_NAMESPACE)SURREALDB_USER(대체:DATABASE_USER)SURREALDB_PASSWORD(대체:DATABASE_PASSWORD)SURREALDB_AUTH_LEVEL(대체:DATABASE_AUTH_LEVEL)
테스트
database/tests/suites/*.toml의 선언적 스위트는 다음을 지원합니다:
sql_expectpermissions_matrixschema_metadataschema_behaviorapi_request
예시:
surrealkit test --fail-fast --json-out artifacts/surrealkit-tests.json
전체 문서
전체 운영 가이드는 주요 스킬 규칙을 참조하세요:
- rules/surrealkit.md -- sync와 rollout 전략, 환경 변수, 시드, 선언적 테스트, CI 패턴
- surrealdb/surrealkit -- 업스트림 저장소