# Litestream VFS

> Clean Markdown view of GeekNews topic #25026. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=25026](https://news.hada.io/topic?id=25026)
- GeekNews Markdown: [https://news.hada.io/topic/25026.md](https://news.hada.io/topic/25026.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2025-12-13T01:37:42+09:00
- Updated: 2025-12-13T01:37:42+09:00
- Original source: [fly.io](https://fly.io/blog/litestream-vfs/)
- Points: 12
- Comments: 1

## Summary

**Litestream VFS**는 SQLite가 **S3 같은 객체 스토리지에서 직접 쿼리**를 수행할 수 있게 하는 확장 기능입니다. 데이터베이스 전체를 내려받지 않고도 원격 백업 파일을 즉시 조회하거나 **시점 복구(PITR)** 를 실행할 수 있으며, 내부적으로 **LTX 포맷**을 이용해 변경된 페이지만 효율적으로 관리합니다. SQLite의 VFS 계층을 활용해 읽기 요청을 S3 Range 호출로 매핑함으로써, 클라우드 환경에서도 거의 실시간에 가까운 복제본을 유지하고 빠른 복구를 지원합니다.

## Topic Body

- **Litestream VFS**는 SQLite 데이터베이스를 **객체 스토리지(S3 등)** 에서 직접 읽고 쿼리할 수 있게 하는 플러그인 형태의 확장 기능  
- 전체 데이터베이스를 다운로드하지 않고도 **원격 백업 파일에서 즉시 쿼리** 및 **시점 복구(Point-in-Time Recovery, PITR)** 수행 가능  
- 내부적으로 **LTX 포맷**을 사용해 변경된 페이지 집합을 효율적으로 관리하고, **중복 페이지를 건너뛰는 압축(compaction)** 으로 복구 속도를 향상  
- SQLite의 **VFS 인터페이스**를 활용해 읽기 동작만 가로채며, 쓰기 처리는 기존 Litestream 프로세스가 담당  
- 초 단위 백업과 인덱스 갱신을 통해 **거의 실시간에 가까운 복제본**을 제공, 클라우드 환경에서 빠른 쿼리 실행을 지원  

---

### Litestream VFS 개요
- **Litestream VFS**는 SQLite가 **객체 스토리지 URL**을 직접 데이터 소스로 사용할 수 있게 하는 기능  
  - SQLite 셸에서 `.load litestream.so` 와 `.open file:///my.db?vfs=litestream` 명령으로 활성화  
  - 이후 S3에 저장된 백업 파일을 기반으로 쿼리 실행 가능  
- 전체 데이터베이스를 다운로드하지 않고도 **원격 백업에서 직접 쿼리 수행** 가능  
  - 예시에서는 `SELECT * FROM sandwich_ratings` 쿼리를 통해 S3에 저장된 데이터 일부를 즉시 조회  

### 시점 복구(PITR) 기능
- `PRAGMA litestream_time = '5 minutes ago';` 명령으로 **특정 시점의 데이터 상태를 조회** 가능  
  - 상대적 시간(`5 minutes ago`) 또는 절대적 시간(`2000-01-01T00:00:00Z`) 지정 가능  
- 이를 통해 **즉시 시점 복구(Point-in-Time Recovery)** 를 SQL 수준에서 수행  
  - 예시에서는 잘못된 `UPDATE` 실행 후, 5분 전 상태로 되돌려 정상 데이터 확인  

### LTX 포맷과 데이터 압축
- **Litestream v0.5**는 **LTX(Litestream Transaction eXchange)** 포맷을 통합  
  - 이전 버전은 SQLite 페이지 전체를 전송했으나, LTX는 **순서가 있는 페이지 집합**만 전송  
- LTX의 핵심은 **“compaction”** 기능으로, 복구 시 최신 버전의 페이지만 선택  
  - 예시: `1 2 3 5 3 5 4 5 5` 중에서 가장 오른쪽의 5, 4, 3, 2, 1만 사용  
- LTX는 전체 데이터베이스뿐 아니라 **LTX 파일 집합 간에도 압축 가능**, 이를 통해 **PITR 복구**가 가능해짐  
- LTX 파일의 **트레일러(trailer)** 에는 각 페이지의 오프셋 인덱스가 포함되어 있어,  
  - 전체 파일을 다운로드하지 않고 **S3 Range 요청**으로 필요한 페이지만 읽을 수 있음  

### VFS 구현 방식
- SQLite의 **VFS(Virtual File System)** 인터페이스를 이용해 Litestream VFS 구현  
  - VFS는 SQLite의 OS 접근 계층을 추상화하는 플러그인 구조  
- Litestream VFS는 **읽기(Read)** 동작만 처리하며, **쓰기(Write)** 는 기존 Litestream 프로세스가 담당  
- SQLite가 페이지를 읽을 때, VFS는 요청된 바이트 오프셋 대신 **페이지 인덱스 기반 매핑**을 수행  
  - 인덱스에서 파일명, 실제 오프셋, 페이지 크기를 찾아 **S3 API의 Range 헤더**로 해당 블록만 다운로드  
- **LRU 캐시**를 구현해 자주 접근되는 “핫 페이지”를 메모리에 유지, S3 호출 횟수를 최소화  

### 실시간 복제 및 성능
- Litestream은 초당 한 번씩 **L0 레벨 백업**을 수행  
  - VFS는 S3 경로를 주기적으로 폴링하여 인덱스를 **점진적으로 갱신**  
  - 결과적으로 **거의 실시간에 가까운 복제본(near-realtime replica)** 생성  
- 전체 데이터베이스를 스트리밍하지 않아도 즉시 사용 가능  
- 이러한 구조 덕분에 **빠른 시작 속도**와 **짧은 복구 시간** 확보  

### 활용 및 의의
- Litestream은 데이터베이스의 모든 상태를 **초 단위 해상도**로 백업 유지  
  - `DELETE`나 `UPDATE` 실수 시, 원하는 시점으로 즉시 복원 가능  
- 객체 스토리지에서 직접 쿼리하는 구조로 **에페메럴 서버 환경**에서도 빠르게 동작  
- 복잡한 메커니즘 없이 SQLite의 기본 기능을 활용해 **단순하면서 강력한 백업·복구 체계** 제공  
- Fly.io 내부 API에서도 사용 중이며, **생산 환경에서도 안정적**으로 운용 가능

## Comments



### Comment 47654

- Author: neo
- Created: 2025-12-13T01:37:42+09:00
- Points: 1

###### [Hacker News 의견들](https://news.ycombinator.com/item?id=46234710) 
- 오, 이건 내가 만든 Go용 **sqlite vfs 모듈**을 사용하고 있음  
  내가 만든 코드가 다른 사람에게 도움이 된다는 걸 알게 될 때마다 정말 기쁨  
  [psanford/sqlite3vfs](https://github.com/psanford/sqlite3vfs)
  - 잘 작동했음. 덕분에 고마움
  - 결국 우리가 인생에서 바라는 건 이런 순간임
- 이건 정말 멋짐. **Litestream VFS**가 유닉스 철학을 그대로 담고 있음  
  SQLite는 평소처럼 작동하고, Litestream은 그 위에서 투명하게 동작함  
  즉, SQL과 SQLite pragma만으로 **즉시 시점 복구(PITR)** 를 구현할 수 있음.  
  프로덕션 데이터셋을 직접 만지지 않고도 과거 데이터를 빠르게 조회할 수 있음
- 인터페이스 디자인이 정말 깔끔함  
  환경 변수로 S3 버킷을 지정하고, SQLite에서 `.load litestream.so` 후  
  `PRAGMA litestream_time = '5 minutes ago';`로 과거 시점 데이터를 바로 조회할 수 있음
  - macOS에서는 `brew install sqlite3` 후  
    `.load litestream sqlite3_litestreamvfs_init`처럼 **init 함수 이름을 직접 지정**해야 함
- bun:sqlite로도 성공적으로 작동시켰음  
  `"LITESTREAM_REPLICA_URL"`과 **AWS 키 환경 변수**만 설정하면 됨  
  `temp.loadExtension("/path/to/litestream.dylib", "sqlite3_litestreamvfs_init")`로 확장 로드 후  
  `file:my.db?vfs=litestream`으로 열면 바로 사용 가능함
  - 이건 주로 **JavaScript 서버(bun)** 환경에서 쓰이는 용도인지 궁금함
  - 잘 작동했다니 멋짐. 그런데 `.dylib` 파일 경로는 어떻게 찾았는지 궁금함
  - 참고로, 이 예시에서 환경 변수 설정 부분은 **dotenv로는 작동하지 않음**. 반드시 실행 시 직접 지정해야 함
- 정말 멋진 기능임.  
  내 사용 사례는 S3에 저장된 **읽기 전용 SQLite DB**를 웹사이트에서 직접 사용하는 것임  
  DB는 cron 작업 등으로 갱신되고, 웹사이트는 Litestream VFS를 통해 최신 데이터를 읽기만 함  
  이런 방식으로 사용해도 괜찮은지, 그리고 Python 통합 모듈이 있는지도 궁금함  
  현재는 Flask 앱이 Google Spreadsheet에서 데이터를 가져와 SQLite로 변환 후 매일 갱신함  
  [내 앱 코드 참고](https://github.com/jgbrwn/my-upc/blob/main/app.py)
  - 작성자임. Litestream VFS는 **1초마다 백업 데이터를 자동으로 폴링**해서 최신 상태를 유지함  
    추가적인 Python 코드 없이 SQLite CLI에서도 그대로 작동함
  - 비슷한 용도로 [ZeroFS](https://github.com/Barre/ZeroFS)도 추천함  
    S3만 외부 의존성으로 사용하며 SQLite와도 잘 맞음  
    [ZeroFS SQLite 성능 참고](https://github.com/Barre/ZeroFS?#sqlite-performance)
- Go용 SQLite 드라이버에도 이미 구현해둠  
  [ncruces/go-sqlite3 예시 코드](https://github.com/ncruces/go-sqlite3/blob/main/litestream/example_test.go)  
  환경 변수 없이 **프로그램 코드로 제어**할 수 있고, 여러 DB를 동시에 다룰 수 있음  
  단, `PRAGMA litestream_time`은 **커넥션 단위**로 적용되므로 커넥션 풀 사용 시 주의 필요함
  - `.load litestream.so`를 보고 바로 ncruces/go-sqlite3가 떠올랐음  
    wasm 환경에서도 작동시키는 게 어려웠는지 궁금함
- 최근 **DuckDB**를 배우며 SQLite와의 차이를 느끼고 있음  
  DuckDB의 “DuckLake” 확장은 트랜잭션마다 **스냅샷**을 만들어 “시간 여행” 기능을 제공함  
  이는 Litestream VFS의 **PITR**과 유사함  
  OLTP에서는 이를 복구 기능이라 부르고, OLAP에서는 “Time Travel”이라 함  
  DuckLake는 외부 카탈로그 DB(PostgreSQL/MySQL/SQLite)를 이용해 다중 프로세스 접근을 조율함  
  반면 Litestream은 S3의 **불변 LTX 파일**을 통해 여러 리더가 동시에 접근 가능함  
  두 세계 모두 “공유 스토리지 + 메타데이터 + 압축(compaction)” 구조로 수렴 중임  
  이런 프로젝트 간의 **교차 협업**이 더 많아지면 좋겠음
- 샌드위치 애호가로서, 그 **샌드위치 평점 데이터**가 정말 궁금함
- 흥미롭긴 한데, 정확히 어떤 소프트웨어가 발표된 건지 헷갈림. Litestream의 새 버전인가?
  - 작성자임. 맞음, **Litestream v0.5.3**이 새로 릴리스되었고, **읽기 전용 VFS 옵션**이 추가됨  
    [v0.5.3 릴리스 노트](https://github.com/benbjohnson/litestream/releases/tag/v0.5.3)
  - 이번 버전에는 **멀티 테넌트 DB용 디렉터리 복제 지원**도 포함되어 있음. 훌륭한 추가 기능임
- sqlite 확장 기능들과도 함께 작동하는지 궁금함  
  예를 들어 **sqlite-vec**이나 **vss** 같은 벡터 검색 확장을 사용 중일 때,  
  Litestream으로 S3에 실시간 백업하고 Litestream VFS로 원격 조회가 가능한지 알고 싶음
  - 나도 궁금함. 아마 쿼리는 로컬에서 실행되고, 필요한 **페이지 단위로 S3에서 가져오는 구조**라면 그냥 작동할 듯함  
    직접 테스트해보는 수밖에 없을 것 같음
  - 가능함 (그게 전부임)