---
title: "Litestream VFS"
description: "Litestream VFS lets SQLite query a Litestream-backed database directly from object storage, including historical states selected with SQL pragmas, without first downloading the complete database. It is a loadable SQLite VFS plugin: Litestream v0.5 uses the LTX data-shipping format, whose compaction removes superseded page versions, while index trailers map database pages to remote file offsets. The VFS fetches only requested page ranges through S3, uses an LRU cache, and can poll second-level L0 backups to maintain a near-realtime replica. Writes remain handled by the regular Litestream Unix program, and the existing SQLite library is unchanged. The result is fast querying and instantaneous point-in-time recovery from arbitrary relative or absolute timestamps, while the optional VFS preserves Litestream’s conventional backup and restore workflow."
---

# Litestream VFS

[Fly.io](https://yomu.fyi/company/fly-io) · Dec 11, 2025

**Type:** Explainer

## Summary

Litestream VFS lets SQLite query a Litestream-backed database directly from object storage, including historical states selected with SQL pragmas, without first downloading the complete database. It is a loadable SQLite VFS plugin: Litestream v0.5 uses the LTX data-shipping format, whose compaction removes superseded page versions, while index trailers map database pages to remote file offsets. The VFS fetches only requested page ranges through S3, uses an LRU cache, and can poll second-level L0 backups to maintain a near-realtime replica. Writes remain handled by the regular Litestream Unix program, and the existing SQLite library is unchanged. The result is fast querying and instantaneous point-in-time recovery from arbitrary relative or absolute timestamps, while the optional VFS preserves Litestream’s conventional backup and restore workflow.

## Context

The work addresses quick queries and sanity checks against production or historical SQLite data without shelling into a production server or performing a full database restore. It also supports recovering from accidental writes, such as an UPDATE that omitted its WHERE clause.

## Approach / What changed

Litestream v0.5 integrates the LTX format and exposes a loadable SQLite VFS that reads database pages directly from LTX files in S3. It compacts page histories, uses LTX trailers to build page indexes, fetches page ranges with S3 byte-range requests, caches hot pages with LRU, and polls L0 backups for incremental updates. The regular Litestream Unix program continues handling writes.

## Takeaways

- LTX compaction reads page histories backward and skips superseded versions, reducing the data needed when restoring a database.
- LTX trailers occupy about 1% of each LTX file and provide page offsets, allowing the VFS to fetch individual SQLite pages from S3 rather than downloading the full database.
- The VFS supports arbitrary relative or absolute timestamps through the litestream\_time pragma and can incrementally follow once-per-second L0 backups for a near-realtime replica.

**Tags:** [Litestream](https://yomu.fyi/topic/litestream), [Object Storage](https://yomu.fyi/topic/object-storage), [SQLite](https://yomu.fyi/topic/sqlite)

- Source: [Fly.io](https://fly.io/blog/litestream-vfs)
- Source URL: https://fly.io/blog/litestream-vfs
- Ingested by Yomu: 2026-09-02T11:57:34.688Z

[Read original post](https://fly.io/blog/litestream-vfs)