Skip to content

Fly.io — Litestream v0.5.0 is Here

Summary

Ben Johnson's shipping announcement for Litestream v0.5.0 — the first batch of the 2025-05-20 "Litestream: Revamped" redesign is now in users' hands. Where the 2025-05-20 design post was forward-looking ("we're building", "it should thus be possible"), this 2025-10-02 post documents what actually shipped: the LTX file format replaces raw-WAL shipping to object storage; a three-level hierarchical compaction hierarchy (30-second → 5-minute → 1-hour windows) delivers PITR that "restore[s] a SQLite database to any point in time, using only a dozen or so files on average"; the old "generations" abstraction is fully retired in favour of a monotonically incrementing transaction ID (TXID); the LTX library now compresses per-page with an end-of-file index so individual pages can be plucked out of large LTX files without downloading the whole thing; CGO is gone (switched from mattn/go-sqlite3 to modernc.org/sqlite) — cross-compiling from macOS to x64 Linux now works out of the box; NATS JetStream joins S3, GCS, and Azure Blob as a replica type; a hard new constraint — one replica destination per database — is codified ("this probably won't affect you, since it's how most people use Litestream already"); the configuration file is fully backwards compatible; v0.5.0 cannot restore from v0.3.x WAL segment files (one-way file-format break, mitigated by the fact that v0.5.0 leaves old WAL files intact). The VFS-based read replicas teased in the 2025-05-20 post are still "we already have a proof of concept working" — not yet shipped.

Key takeaways

  1. This is the shipping post for the 2025-05-20 revamp's first batch. "A few months back, we announced plans for a major update to Litestream. I'm psyched to announce that the first batch of those changes are now 'shipping'. Litestream is faster and now supports efficient point-in-time recovery (PITR)." Confirms the design disclosures from the May post landed substantially as announced. (Source: sources/2025-10-02-flyio-litestream-v050-is-here)

  2. Three-level hierarchical compaction hierarchy shipped. "at Level 1, we compact all the changes in a 30-second time window; at Level 2, all the Level 1 files in a 5-minute window; at Level 3, all the Level 2's over an hour. Net result: we can restore a SQLite database to any point in time, using only a dozen or so files on average. Litestream performs this compaction itself. It doesn't rely on SQLite to process the WAL file. Performance is limited only by I/O throughput." The canonical time-window compaction hierarchy is now a concrete 30s / 5m / 1h ladder, not an abstract design. Restore cost bound: "a dozen or so files on average" regardless of retention depth.

  3. Generations abstraction is dead; monotonic TXIDs replace it. "LTX-backed Litestream does away with the concept entirely. Instead, when we detect a break in WAL file continuity, we re-snapshot with the next LTX file. Now we have a monotonically incrementing transaction ID. We can use it look up database state at any point in time, without searching across generations." The pre-revamp "Marvel Cinematic Universe parallel dimensions" model ("Yeah, we didn't like those movies much either") is gone. Litestream commands still work the same — user-visible CLI carries TXIDs where generation/index/offset used to appear, and litestream wal is renamed to litestream ltx.

  4. Worked motivating example — the "sandwiches" table with AUTOINCREMENT primary key. The post opens with a pedagogic worked example: a SQLite table sandwiches(id INTEGER PRIMARY KEY AUTOINCREMENT, description TEXT NOT NULL, star_rating INTEGER, reviewer_id INTEGER NOT NULL) in a "wildly popular sandwich-reviewing app" whose reviewers spend "the first couple minutes" dithering between ⭐ and ⭐⭐. The AUTOINCREMENT makes every insert hit the rightmost leaf page of the B-tree; the dithering means the same page gets rewritten repeatedly. "For SQLite itself, that's no problem. But Litestream has less information to go on: it sees only a feed of whole pages it needs to archive. Worse still, when it comes time to restore the database – something you tend to want to happen quickly – you have to individually apply those small changes, as whole pages. Your app is down, PagerDuty is freaking out, and you're sitting there watching Litestream reconstruct your Quiznos uncertainty a page (and an S3 fetch) at a time." Canonical illustration of why raw-WAL-shipping cost scaled with "raw WAL volume", not "distinct logical state."

  5. Per-page compression + end-of-file index in the LTX library. "We've beefed up the underlying LTX file format library. It used to be an LTX file was just a sorted list of pages, all compressed together. Now we compress per-page, and keep an index at the end of the LTX file to pluck individual pages out. You're not seeing it yet, but we're excited about this change: we can operate page-granularly even dealing with large LTX files. This allows for more features. A good example: we can build features that query from any point in time, without downloading the whole database." This is the structural precondition for the still-unreleased VFS-based read-replica layer — you can fetch specific pages from a large LTX file without pulling the whole file.

  6. File-format break: v0.5.0 cannot restore from v0.3.x WAL segment files. "Due to the file format changes, the new version of Litestream can't restore from old v0.3.x WAL segment files. That's OK though! The upgrade process is simple: just start using the new version. It'll leave your old WAL files intact, in case you ever need to revert to the older version. The new LTX files are stored cleanly in an ltx directory on your replica. The configuration file is fully backwards compatible." Upgrade is a cutover, not a migration — no cross-format compaction — but the old archive is preserved for rollback.

  7. One-replica-per-database constraint is now official. "We added a new constraint. You only get a single replica destination per database. This probably won't affect you, since it's how most people use Litestream already. We've made it official. The rationale: having a single source of truth simplifies development for us, and makes the tool easier to reason about. Multiple replicas can diverge and are sensitive to network availability. Conflict resolution is brain surgery." Follows directly from the CASAAS single-writer lease — multiple active destinations doesn't compose with the coordination-via-object-store move.

  8. CGO eliminated; modernc.org/sqlite wins. "CGO is now gone. We've settled the age-old contest between mattn/go-sqlite3 and modernc.org/sqlite in favor of modernc.org. This is super handy for people with automated build systems that want to run from a MacBook but deploy on an x64 server, since it lets the cross-compiler work." Quality-of-life upgrade with a concrete developer-experience payoff: GOOS=linux GOARCH=amd64 go build from a Mac now Just Works because there's no C compiler involved.

  9. NATS JetStream added as a replica type. "We've also added a replica type for NATS JetStream. Users that already have JetStream running can get Litestream going without adding an object storage dependency." Interesting framing — JetStream's persistence + at-least-once guarantees cover the same semantic surface as object-store conditional writes for users already running JetStream as their coordination / streaming substrate. Broadens the pool of "what can be a Litestream replica" beyond S3 / GCS / Azure Blob.

  10. Object-store clients bumped to latest; newer S3 APIs supported. "We've also upgraded all our clients (S3, Google Storage, & Azure Blob Storage) to their latest versions. We've also moved our code to support newer S3 APIs." Implicit reference to the 2024-11 S3 conditional writes feature that CASAAS depends on — SDKs needed to be current to take it.

  11. VFS-based read replicas are still roadmap, proof-of-concept stage. "The next major feature we're building out is a Litestream VFS for read replicas. This will let you instantly spin up a copy of the database and immediately read pages from S3 while the rest of the database is hydrating in the background. We already have a proof of concept working and we're excited to show it off when it's ready!" The read-replica layer teased in the 2025-05-20 post did not ship in v0.5.0 — v0.5.0 ships the write/archive side of the revamp plus the format changes that make read-replicas feasible; the read-replica feature itself is next.

Systems extended

  • Litestream — this post is the shipping-post counterpart to the 2025-05-20 design post. Confirms: LTX replaces shadow-WAL (shipped), hierarchical compaction 30s/5m/1h (shipped), TXID replaces generations (shipped), per-page compression + EOF index (shipped), CGO removal via modernc.org/sqlite (shipped), NATS JetStream replica (shipped), one-replica-per-database constraint (shipped), file-format break from v0.3.x (shipped). VFS read replicas (not shipped — proof-of-concept only). [extends]
  • LiteFS — the LTX format shipped in Litestream v0.5.0 is the same format LiteFS has used for node-to-node replication; the architectural convergence foreshadowed in the 2025-05-20 post is now concrete in the shipping artifact. [extends]
  • SQLite — this post confirms the modernc.org/sqlite (pure-Go) CGO-free SQLite port as the library Litestream now links, not mattn/go-sqlite3. Downstream-ecosystem signal: modernc.org/sqlite is considered production-grade for at-least write-log-tailing workloads. [extends]
  • NATS — NATS JetStream gains a new wiki role: Litestream v0.5.0 replica type. Distinct from the at-most-once core-NATS role the 2024-03-12 JIT-WireGuard + 2025-03-27 tkdb posts retire; JetStream is the at-least-once / persistent layer that can carry Litestream's archive semantic without needing an object store. First wiki instance of NATS JetStream specifically (vs core NATS). [extends]
  • S3 — implicit consumer: Litestream v0.5.0's "newer S3 APIs" upgrade is the downstream hook for the 2024-11 conditional-writes feature that CASAAS depends on. No explicit new S3-side disclosure in this post. [extends]

Concepts extended

  • LTX file format — this post adds two concrete shipping-level facts to the LTX concept: (1) per-page compression replaces whole-file compression; (2) end-of-file index makes LTX files random-accessible at page granularity ("pluck individual pages out"). Enables querying from any point in time without downloading the whole database. Previously-described file format is now the format v0.5.0 implements. [extends]
  • Shadow WAL — retired-as-announced. v0.5.0 ships without the shadow-WAL mechanism; old v0.3.x WAL segment files are preserved for rollback but cannot be restored by v0.5.0. The legacy mechanism is now historical on the wiki, not current-pre-retirement. [extends]
  • Write-ahead logging — this post renames the user-facing CLI from litestream wal to litestream ltx, making the format transition visible at the command-line surface. WAL is still SQLite's write-ahead log; what changed is what Litestream ships (LTX, not raw WAL frames). [extends]
  • LSM-tree compaction — this post gives the lived shape of LSM-style compaction applied to LTX: a three-level hierarchy with a "dozen or so files on average" restore-cost invariant. Concrete numerical specification of what the 2025-05-20 post described in the abstract. [extends]
  • Monotonic transaction ID (TXID) — new framing the post introduces as the replacement for the "generation / index / offset" addressing scheme: "a monotonically incrementing transaction ID. We can use it look up database state at any point in time, without searching across generations." Not a new standalone wiki concept (monotonic identifiers are a general primitive), but a load-bearing detail of the revamp.

Patterns extended

  • LTX compaction — gains its canonical shipping-level time-window ladder: 30s → 5m → 1h, three levels. The previously-theoretical pattern now has a concrete production instantiation. [extends]
  • Hierarchical time-window compaction — the three-level ladder is a specialisation of LSM-style leveled compaction with time-window (not size-threshold) level boundaries. Complements patterns/ltx-compaction at one level of abstraction up — the ladder shape is reusable beyond SQLite/LTX (any merge-compactable sorted-run format over an append workload can use it). Not promoted to its own page yet — this post is the first corpus-wide disclosure of the specific ladder; will promote on a second independent source.
  • SQLite + LiteFS + Litestream — the canonical three-layer stack, whose Litestream leg is now v0.5.0 with the LTX / CASAAS / TXID / hierarchical-compaction shape. [extends]

Operational numbers

  • Restore cost: "a dozen or so files on average" regardless of retention depth (compaction hierarchy result).
  • Compaction hierarchy: 30-second (Level 1) → 5-minute (Level 2) → 1-hour (Level 3) time windows.
  • HN: 430 points, item 45453936.
  • No latency numbers disclosed (restore time, compaction CPU cost, per-page-compression ratio).
  • No size-delta numbers disclosed (LTX total bytes vs. raw-WAL shipping bytes under a representative workload).
  • No throughput numbers disclosed (write-rate ceiling, compaction-throughput vs. write-rate).

Caveats

  • No post-mortem or "how it went in production" content. This is a shipping-announcement post. Despite being 4+ months after the 2025-05-20 design post, the narrative is "it shipped and here's what's in it", not "here's what surprised us after turning it on". No early-deployment incident retrospective, no performance-vs-estimate comparison.
  • No numerical comparison with the v0.3.x shadow-WAL design. Pre/post-revamp restore-time numbers, archive-size ratios, and compaction-overhead numbers are all undisclosed. The 2025-05-20 design post also declined to quote these; v0.5.0 ships and still declines to quote.
  • VFS read-replicas are still not shipped. "We already have a proof of concept working." The read-side half of the 2025-05-20 design is roadmap.
  • Migration path from v0.3.x is a cutover, not a cross-format restore. "The new version of Litestream can't restore from old v0.3.x WAL segment files." Mitigated by v0.5.0 leaving old WAL files intact (rollback-possible), but there is no bridge that can serve PITR spanning the format boundary.
  • One-replica-per-database is a new hard constraint. Users who ran Litestream with multiple replica destinations (rare but non-zero) must pick one when upgrading. "This probably won't affect you, since it's how most people use Litestream already" — self-reported, no deployment-survey numbers.
  • NATS JetStream replica type disclosed without operational detail. No throughput ceiling, retention semantics, stream-configuration guidance, or JetStream-vs-S3 trade-off discussion.
  • CGO removal is a downstream-library bet. modernc.org/sqlite is a separate project from SQLite itself; Litestream's upgrade is a vendor dependency change, not a SQLite-upstream change. Implicit assumption that modernc.org/sqlite keeps pace with SQLite releases.
  • Ship date not explicitly stamped inside the post — the feed-level published: 2025-10-02 is the publication-date datum; no separate git-tag or release-notes URL is cited.

Source

Last updated · 200 distilled / 1,178 read