English for LiteFS Developers
Vocabulary for developers using LiteFS to replicate SQLite across regions — primary election, transaction streaming, and lease vocabulary for distributed edge apps.
LiteFS is a distributed file system built by Fly.io that replicates SQLite databases across multiple regions, letting you run a “distributed SQLite” setup without switching to a heavier database. Its vocabulary borrows from distributed systems — primaries, leases, replication streams — applied to a database that’s traditionally thought of as single-machine. If you’re deploying an app on LiteFS, or explaining the architecture to a teammate, here’s the language you need.
Primary and Replica Vocabulary
Primary Node
The primary node is the single instance that accepts writes at any given time. All other nodes are read-only replicas that stream changes from it.
“Only the primary node can write — if a replica receives a write request, it needs to forward it to the primary rather than handling it locally.”
Replica
A replica holds a read-only copy of the database, kept in sync by streaming transactions from the primary. Replicas serve local reads with much lower latency than round-tripping to the primary region.
“Users in Sydney read from the local replica, so their dashboard loads in milliseconds instead of waiting on a round trip to the primary in Virginia.”
Primary Election
Primary election is the process of choosing a new primary when the current one becomes unavailable — coordinated through a lease system (often backed by Consul in LiteFS deployments).
“When the primary’s health check failed, primary election picked a new node within a few seconds, and writes resumed automatically.”
Lease
A lease is a time-limited claim a node holds to act as primary. If the lease isn’t renewed before it expires, another node can win the election and take over.
“The primary renews its lease every few seconds — if it goes silent, the lease expires and a replica takes over as the new primary.”
Replication Mechanics
Transaction streaming — LiteFS captures each committed SQLite transaction as a compact set of page changes and streams them to replicas in order.
“Transaction streaming means replicas apply the exact same page-level changes as the primary — they stay byte-for-byte identical.”
Write-ahead log (WAL) — SQLite’s mechanism for recording changes before committing them to the main database file; LiteFS taps into this to capture transactions for replication.
“LiteFS intercepts the WAL frames as SQLite writes them, which is how it captures every transaction without modifying the SQLite engine itself.”
Replication lag — the delay between a transaction committing on the primary and a replica applying that same transaction.
“We monitor replication lag closely — if it grows past a few hundred milliseconds, we alert, because stale reads start becoming noticeable to users.”
Checksum verification — a background process that confirms a replica’s database file matches the primary bit-for-bit, catching silent corruption early.
Read and Write Patterns
Read-your-writes consistency — a guarantee that after a user makes a write, their subsequent reads reflect that write, even if served from a replica.
“We route the request back to the primary region for a short window after any write, to guarantee read-your-writes consistency for that user.”
Write forwarding — when a replica receives a write request and proxies it to the primary, so the client doesn’t need to know which node is the true primary.
“Write forwarding means our app code doesn’t need any primary-awareness logic — LiteFS’s proxy handles the redirect transparently.”
Fly-Replay header — a mechanism specific to Fly.io that lets an app running near the user redirect a single HTTP request to the primary region, rather than forwarding at the database layer.
“We use the Fly-Replay header for write endpoints, so the write request itself gets rerouted to the primary’s region before it even reaches our app code.”
Operational Vocabulary
Snapshot — a full copy of the database used to bootstrap a new replica quickly, instead of replaying every transaction from the beginning.
“When we added a new region, LiteFS pulled a snapshot first and only streamed transactions from that point forward — much faster than a full replay.”
Split-brain — a dangerous scenario where two nodes both believe they’re the primary simultaneously, usually due to a lease or networking bug; LiteFS’s lease system is designed specifically to prevent this.
“We audited our lease timeout configuration carefully after reading about split-brain risks — a too-short timeout under network jitter could, in theory, cause two primaries.”
Failover — the act of switching operation to a new primary after the previous one fails, ideally with minimal write downtime.
“Our failover time is under five seconds in the worst case we’ve tested — short enough that most users never notice.”
Explaining the Architecture
| Situation | Phrase |
|---|---|
| Explaining the value proposition | ”We get SQLite’s simplicity with multi-region reads — the trade-off is that all writes still go through a single primary.” |
| Reporting replication lag in an incident | ”Replication lag briefly spiked to 800ms during the primary election — reads from replicas could have been slightly stale for about ten seconds.” |
| Justifying the architecture in a design review | ”For our read-heavy, geographically distributed traffic, LiteFS gives us low-latency local reads without adopting a heavier distributed database.” |
| Describing a failover event | ”The primary’s lease expired after a network blip, a replica was elected as the new primary within four seconds, and writes resumed automatically.” |
Common Mistakes
- Saying “the database is distributed” without clarifying that only one node accepts writes — LiteFS is a single-writer, multi-reader system, not a multi-master database.
- Confusing replication lag with failover time — one measures staleness during normal operation, the other measures downtime during a primary change.
- Describing write forwarding as “load balancing” — load balancing distributes work across multiple targets; write forwarding redirects everything to one target.
Practice Exercise
- Explain, in two sentences, why an app using LiteFS might still need to think about write latency for users far from the primary region.
- Write a short incident summary describing a primary election event and its impact on read consistency.
- Draft an explanation, for a teammate unfamiliar with distributed SQLite, of what a “lease” does in this system.