Terminal
Terminal/Skill
Helps developers avoid stale reads right after a write, such as from a replica, cache or search index that has not caught up.
By Trigger.dev
Works with
npx skills add triggerdotdev/staff-engineering-skills --skill staff-engineering-skills-consistency-modelsYou wrote data. You read it back. You got the old value. Before writing any code that reads after writing, ask: could the read hit a different instance than the write?
Almost every consistency bug has the same shape: data written to system A, read from system B, and B hasn't caught up.
| Gap | What happens | Typical delay |
|---|---|---|
| Replica lag | Write to primary, read hits replica | 10-500ms (async replication) |
| Cache staleness | Write to database, read hits cache | Seconds to minutes (TTL-based) |
| Index delay | Write to database, search reads index | 1-30s (Elasticsearch, Algolia) |
Stop and check consistency if you see:
findMany that should include the new record -- if findMany hits a replica, the new record may be missing.The fix is NOT "make everything strongly consistent" -- that's expensive and usually unnecessary. Route reads to the appropriate backend based on freshness requirements.
| Read type | Consistency needed | Source |
|---|---|---|
| User viewing own data after editing | Strong (read-after-write) | Primary, or return written data |
| Browsing other users' content | Eventual | Read replica, cache |
| Full-text search results | Eventual | Search index |
| Dashboard analytics | Eventual | Read replica, materialized view |
| Account balance after transfer | Strong | Primary, write-through cache |
| "My recent orders" after placing one | Strong (read-after-write) | Primary or optimistic UI |
app.post("/api/profile", async (req, res) => {
const updated = await db.user.update({
where: { id: req.user.id },
data: { name: req.body.name, bio: req.body.bio },
});
res.json(updated); // Return what we wrote. No second read needed.
});
No read-after-write means no consistency problem. Best pattern whenever the API can return the mutated entity.
async function updateProfile(data: ProfileUpdate) {
setLocalProfile(prev => ({ ...prev, ...data })); // Show immediately
const response = await fetch("/api/profile", {
method: "PUT",
body: JSON.stringify(data),
});
if (!response.ok) {
setLocalProfile(previousProfile); // Revert on failure
showError("Failed to save");
}
// Don't re-fetch. Trust local state. Others see it when read models catch up.
}
The writer sees the change immediately -- no round-trip, no gap. Standard for modern SPAs.
app.post("/api/profile", async (req, res) => {
await db.user.update({ where: { id: req.user.id }, data: req.body });
res.cookie("_read_primary", "1", { maxAge: 5000 }); // tell read path to use primary
res.redirect(`/profile/${req.user.id}`);
});
app.get("/profile/:id", async (req, res) => {
const forcePrimary = req.cookies._read_primary === "1";
const user = await db.user.findUnique({
where: { id: req.params.id },
...(forcePrimary && { replicaRead: false }), // framework-specific
});
res.render("profile", { user });
});
Only the user who wrote gets the primary read; once the cookie expires, reads return to replicas. Everyone else stays on replicas throughout.
async function updateUser(userId: string, data: Partial<User>) {
const updated = await db.user.update({ where: { id: userId }, data });
// Set cache to the known-correct value, don't just delete it.
await redis.set(`user:${userId}`, JSON.stringify(updated), "EX", 300);
return updated;
}
Write-through beats delete-then-repopulate: if you delete the key, the next request can read from a stale replica and repopulate with old data.
app.get("/api/documents", async (req, res) => {
if (req.query.q) {
// Search: index (eventual, expected for search)
res.json(await searchIndex.search("documents", req.query.q));
} else if (req.query.mine) {
// My documents: primary (strong for own data)
res.json(await db.document.findMany({
where: { authorId: req.user.id }, orderBy: { createdAt: "desc" },
}));
} else {
// Browse all: replica (eventual, fine for discovery)
res.json(await readReplica.document.findMany({
orderBy: { createdAt: "desc" }, take: 50,
}));
}
});
Different reads, different consistency requirements, different backends.
Every database has a default consistency model. Assume stronger guarantees than you have and you'll write stale-read bugs. Defaults and the trap for each:
insert_quorum forces synchronous writes to N replicas; select_sequential_consistency=1 forces reads to wait for latest -- both expensive. ReplicatedMergeTree still replicates async. MergeTree merges run in the background, so queries can see duplicate rows until merge completes unless you use ReplacingMergeTree with FINAL (or OPTIMIZE TABLE ... FINAL, expensive). Trap: write-then-immediately-query works single-node in dev, fails with distributed tables in prod -- assume reads are stale unless quorum writes are configured."local" (default, may be stale), "majority", "linearizable" (strongest, slowest). Trap: default "local" read + default w:1 write means you can lose acknowledged writes if the primary fails before replication.GetItem/Query need ConsistentRead: true (2x read cost) to see the latest. Global tables resolve cross-region conflicts last-writer-wins. Trap: SDK defaults give eventual consistency silently -- a GetItem that must see a prior PutItem needs ConsistentRead: true.refresh=wait_for forces a refresh before returning, at a latency cost. Trap: "just indexed, can't find it" -- the index hasn't refreshed; consistency is traded for search throughput.// Dangerous: create then redirect. /orders/:id reads a replica; order may not be there yet.
app.post("/api/orders", async (req, res) => {
const order = await db.order.create({ data: req.body });
res.redirect(`/orders/${order.id}`);
});
// Dangerous: update database, read from cache on next request (stale until TTL expires)
await db.user.update({ where: { id }, data: { name: "New Name" } });
const cached = await redis.get(`user:${id}`); // still "Old Name"
// Dangerous: create in database, immediately search for it (index hasn't refreshed)
await db.document.create({ data: { title: "Q4 Report", content: "..." } });
await searchIndex.index("documents", doc.id, doc);
// User searches "Q4 Report" -- not found
// Dangerous: publish event, query read model on next page (consumer hasn't run)
await eventBus.publish("order.created", order);
res.redirect("/orders");