러스트 임베디드 KV 'TurboKV', 속도보다 운영 계약이 눈에 띈다

임베디드 키-값 저장소는 이미 러스트 생태계에 여럿 존재한다. 그런 상황에서 새로 공개된 TurboKV를 살펴볼 가치가 있는 이유는 단순히 '빠르다'는 주장 때문이 아니라, 라이브러리가 개발자에게 요구하는 동작 계약을 비교적 솔직하게 문서로 못 박아 두었기 때문이다. TurboKV는 러스트로 작성된 비동기 임베디드 키-값 데이터베이스로, 애플리케이션 프로세스 안에 라이브러리 형태로 내장돼 동작한다. 원자적 배치 쓰기, 바이트 순서 기반의 범위 스캔, 조정 가능한 내구성(durability), 압축, 백그라운드 컴팩션을 갖췄다. 메모리 상의 멤테이블(memtable)과 이후의 플러시·컴팩션이라는 구성은 LSM 계열 저장 엔진의 전형적인 구조를 따른다.

기본 프리셋은 64MiB 멤테이블, 64MiB 블록 캐시, LZ4 압축으로 출발하며, 데이터 디렉터리를 열기 전이라면 공개 필드를 조정해 이 값들을 바꿀 수 있다. 하위 계층인 Engine과 개별 구성 요소의 설정 타입도 고급 API로 지원되며, 전체 필드와 메서드 계약은 크레이트 문서에 정리돼 있다. 즉 간단한 프리셋으로 시작하되 필요하면 세밀하게 제어할 수 있는 이중 구조인 셈이다.

빌드와 종료에서 먼저 걸리는 지점

실무에서 가장 먼저 마주칠 함정은 빌드 설정이다. TurboKV가 디스크에 저장하는 블룸 필터 포맷은 하드웨어 AES 명령을 사용한다. 따라서 x86/x86_64 타깃은 RUSTFLAGS="-C target-feature=+aes,+sse2"로, ARM/AArch64 타깃은 "+aes,+neon"으로 빌드해야 한다. 빌드 결과물을 동일 CPU 모델이나 그 상위 기능 집합에서만 돌릴 것이라면 -C target-cpu=native로 대체할 수 있다. 여러 종류의 CPU에 배포하는 CI 파이프라인이라면 이 플래그를 빠뜨렸을 때 예상치 못한 문제가 생길 수 있으므로, 도입 초기에 확인해 둘 항목이다.

종료 규약도 명시적이다. 열려 있는 하나의 Db 또는 Engine은 자신의 데이터 디렉터리를 배타적으로 소유한다. 정상 종료를 위해서는 close() 또는 close_with_status()를 호출해야 하며, 핸들을 그냥 드롭(drop)하는 것은 깨끗한 종료로 보장되지 않는다. 러스트에서 흔히 RAII에 기대 자원 해제를 맡기는 습관이 있는데, 이 데이터베이스에서는 그 습관이 곧 데이터 정합성 문제로 이어질 수 있다는 점을 유념해야 한다.

데이터 모델과 실패 처리의 세부

키와 값은 AsRef로 전달되는 임의의 바이트열이며, 문자열은 호출자가 직접 인코딩해야 한다. 변경 API는 입력을 복사한 뒤 반환하고, WriteBatch 역시 모든 키와 값의 복사본을 소유한다. 포인트 읽기와 수집형 읽기는 소유권을 가진 Vec를 돌려준다. 특히 빈 값은 유효한 데이터이며 삭제된 키와는 구분된다는 규칙은, 존재 여부 판별 로직을 짤 때 놓치기 쉬운 부분이다.

WAL(쓰기 선행 로그)을 켜면 하나의 레코드 또는 하나의 완전한 배치가 WAL의 u32 페이로드 길이 안에 들어가야 한다는 제약이 있다. 더 주의할 점은 실패하거나 취소된 변경이라도 이미 WAL에 기록됐을 수 있다는 것이다. 따라서 멱등하지 않은 연산을 재시도하기 전에는 해당 키의 상태를 확인하거나 데이터베이스를 다시 열어 점검하는 편이 안전하다. 스캔 쪽에서는 키가 원시 바이트 기준 사전식으로 정렬되고, 모든 스캔이 일관된 시점 스냅샷을 포착한다. 다만 스캔을 만들면 비어 있지 않은 활성 멤테이블이 얼려질 수 있어, 잦은 소규모 스캔은 나중의 플러시 부담을 키운다. 스트리밍 이터레이터를 전진시키는 동작은 동기식으로 mmap 읽기, 체크섬 검증, 압축 해제, 캐시 잠금을 수반할 수 있고, 스냅샷 리더와 디렉터리 소유권을 붙들고 있으므로 되도록 빨리 드롭해야 한다.

벤치마크는 무엇을 말하고 무엇을 말하지 않나

성능 측정은 TurboKV 0.6.0, fjall 2.11.2, redb 2.6.3을 Durable 모드에서 세 차례 반복해 진행했고, 지표는 초당 확인 완료(acknowledged)된 키 수다. 프로토콜은 20바이트 키 20만 개와 400바이트 값으로, 논리 입력 84MB는 64MiB 멤테이블을 넘어서도록 설계됐다. 압축과 블록 캐시는 끈 상태였고 OS 페이지 캐시는 비우지 않았다. 측정 환경은 애플 M4(Mac16,1), 32GiB RAM, macOS 15.3.2, APFS, rustc 1.88.0이며 날짜는 2026년 8월 28일이다.

인상적인 것은 프로젝트가 스스로 비교의 한계를 밝혔다는 점이다. redb의 Durability::Eventual은 트랜잭션마다 macOS의 F_BARRIERFSYNC를 수행하는 반면, TurboKV와 fjall의 Durable 모드는 프로세스 크래시에서 복구 가능한 OS 캐시 경계에서 멈춘다. 즉 내구성 보장 수준이 서로 달라 단일 키 행의 수치는 동등 비교가 아니라 구조적 참고 자료일 뿐이며, 엔진 간 정착(settled) 타이밍은 비교하지 않았다고 명시한다. 원시 반복값과 지연 백분위, 분산, 증폭 지표 등은 별도 JSON 아티팩트와 benchmarks/README.md에 담겨 있다. 벤치마크 결과 자체를 절대 수치로 받아들이기보다, 자신의 워크로드에서 재현 명령으로 직접 돌려 확인하라는 태도로 읽는 편이 합리적이다. 결국 TurboKV의 매력은 과장된 속도 구호가 아니라, 빌드·종료·재시도·스캔 비용을 개발자가 예측할 수 있게 계약으로 드러낸 정직함에 있다.