---
title: "Tracking Application-Level Consistency with LiteFS"
description: "LiteFS must keep an application’s view consistent when a write reaches a primary and a subsequent read is served by a lagging replica. The project first considered making applications track each database’s replication position—a TXID paired with a post-apply checksum—and wait for replicas to catch up, but rejected that complexity and abandoned language-specific libraries. It instead introduces a thin HTTP proxy in front of the application: method-based request inspection routes writes to the primary, attaches the committed TXID in a cookie, and delays reads until the local replica reaches that position or times out. The proxy also exposes lag through health checks, allowing Fly.io to remove unhealthy replicas from rotation and restore them after reconnection. This design provides read-your-writes guarantees with little application change, but depends on cookies and conventional HTTP request/response traffic, limiting use with some applications and websocket-heavy frameworks."
---

# Tracking Application-Level Consistency with LiteFS

[Fly.io](https://yomu.fyi/company/fly-io) · Aug 30, 2023

**Type:** Problem & solution

## Summary

LiteFS must keep an application’s view consistent when a write reaches a primary and a subsequent read is served by a lagging replica. The project first considered making applications track each database’s replication position—a TXID paired with a post-apply checksum—and wait for replicas to catch up, but rejected that complexity and abandoned language-specific libraries. It instead introduces a thin HTTP proxy in front of the application: method-based request inspection routes writes to the primary, attaches the committed TXID in a cookie, and delays reads until the local replica reaches that position or times out. The proxy also exposes lag through health checks, allowing Fly.io to remove unhealthy replicas from rotation and restore them after reconnection. This design provides read-your-writes guarantees with little application change, but depends on cookies and conventional HTTP request/response traffic, limiting use with some applications and websocket-heavy frameworks.

## Context

LiteFS replicates write transactions from a primary to read-only replicas asynchronously. A user’s subsequent read can reach a replica before the write has arrived, exposing stale database state. Making each application track replication positions and coordinate reads would require substantial distributed-systems complexity.

## Approach / What changed

A thin HTTP proxy sits in front of the application and uses HTTP methods to distinguish reads from writes. It forwards writes to the primary, places the committed TXID in a response cookie, and makes later reads wait until the local replica reaches that TXID or times out. It also uses heartbeat-based health checks to identify lagging replicas.

## Takeaways

- A LiteFS replication position combines a monotonically increasing TXID with a post-apply checksum; together, the values let replicas compare progress and detect divergence.
- The proxy routes POST, PUT, DELETE, and other write methods to the primary, while GET requests can wait for the local replica to reach the TXID stored in the client cookie.
- The read-your-writes guarantee depends on cookies and conventional HTTP request/response traffic, so the proxy does not fit applications that cannot use cookies or rely heavily on websockets.

**Tags:** [LiteFS](https://yomu.fyi/topic/litefs), [SQLite](https://yomu.fyi/topic/sqlite)

- Source: [Fly.io](https://fly.io/blog/tracking-consistency-with-litefs)
- Source URL: https://fly.io/blog/tracking-consistency-with-litefs
- Ingested by Yomu: 2026-09-03T01:25:12.037Z

[Read original post](https://fly.io/blog/tracking-consistency-with-litefs)