English for Turso Embedded Replicas

Turso’s embedded replicas let applications read from a local copy of a SQLite database while writes still go to a central primary, which is a genuinely different mental model from a typical client-server database setup. Describing this architecture accurately — knowing “sync interval” from “write-through” — matters when you’re explaining latency characteristics or debugging stale reads. This guide covers the vocabulary.

Key Vocabulary

Embedded replica — a local copy of a libSQL database that lives alongside your application, allowing reads to happen with near-zero latency without a network round trip. “Reads are effectively instant now that we’re using an embedded replica instead of querying the remote database directly.”

Primary database — the authoritative, centrally hosted database that receives all writes and is the source of truth that replicas sync from. “All writes route to the primary database, even from services that also hold an embedded replica for reads.”

Sync interval — the configured frequency at which an embedded replica pulls the latest changes from the primary database to stay up to date. “We shortened the sync interval because a five-second staleness window was too long for this particular feature.”

Write-through — a pattern where write operations are sent directly to the primary database rather than the local replica, ensuring writes are immediately durable and consistent. “Because writes are write-through to the primary, you’ll never accidentally write to a replica that then silently discards the change.”

Replication lag — the delay between a write landing on the primary database and that change becoming visible in an embedded replica. “The bug was caused by replication lag — the UI read from the replica right after a write, before the sync had caught up.”

Local-first reads — an architecture pattern where read queries are served from a local data copy whenever possible, falling back to the remote source only when necessary. “Local-first reads are why this app still feels responsive even on a flaky mobile connection — most queries never leave the device.”

Common Phrases

• “Is this read coming from the embedded replica, or are we still hitting the primary directly?”
• “That’s replication lag, not a bug — the write succeeded, but the replica hasn’t synced yet.”
• “Shorten the sync interval if this feature can’t tolerate even a few seconds of staleness.”
• “Remember, writes are always write-through — don’t try to write directly to the replica.”
• “Local-first reads cut our average query latency dramatically once we rolled this out.”

Example Sentences

Explaining the architecture to a new engineer: “Every instance of our service holds an embedded replica of the database, so most reads never leave the machine. Writes still go to the primary database, and the replica syncs the change shortly afterward based on our configured sync interval.”

Debugging a stale-read report: “The user reported seeing their old profile picture right after uploading a new one. That’s replication lag — the write landed on the primary immediately, but their session was reading from a replica that hadn’t synced yet. We’re shortening the interval for that read path.”

Describing a performance win to stakeholders: “Switching to embedded replicas for local-first reads cut our median query latency by an order of magnitude, since most requests are now served from memory on the same machine instead of over the network to a remote database.”

Professional Tips

• Use “replication lag” specifically to describe temporary staleness after a write — it’s a more precise, less alarming term than “the database is out of sync,” which can sound like a persistent error.
• When proposing a shorter sync interval, quantify the trade-off explicitly (more frequent network calls vs. lower staleness) so reviewers can weigh the cost.
• Say “write-through” to clarify that writes bypass the replica entirely — this prevents confusion for engineers used to write-back caching patterns, which behave differently.
• Distinguish local-first reads (an architectural choice) from embedded replica (the specific mechanism enabling it) when writing documentation, since the pattern could theoretically be implemented differently.

Practice Exercise

1. Explain, in two sentences, why writes go to the primary database while reads can be served from an embedded replica.
2. Write a one-sentence bug report describing a stale read caused by replication lag.
3. Describe, to a teammate, what would happen if the sync interval were set far too long for a real-time feature.