Local-First English: ElectricSQL and Sync Architecture
Learn the English vocabulary of local-first architecture and ElectricSQL — CRDTs, sync state, conflict resolution, data shapes, and replication lag explained.
Introduction
Local-first is a software architecture philosophy where data lives on the user’s device first, and the server is used for synchronisation rather than as the primary data store. ElectricSQL is one of the tools that makes this practical for PostgreSQL-backed applications. This approach introduces a vocabulary unlike anything in traditional client-server development — terms like CRDT, eventual consistency, and replication slot come from distributed systems research but are now entering mainstream web development. This post teaches you to understand and use this vocabulary fluently.
Offline Capability and the Local-First Promise
Offline capability means an application can be read and written to even when there is no internet connection. When connectivity returns, changes are synchronised automatically. “We added offline capability to the field inspection app so that engineers can record findings even in areas with no signal.”
The broader design principle is offline-first — designing the application to work offline as the default case, treating network access as an enhancement rather than a requirement. “Building offline-first means you must think about conflict resolution from the very beginning of the project, not as an afterthought.”
An optimistic update is when the UI immediately shows the result of a user action before the server has confirmed it. The assumption is that the operation will succeed. “With optimistic updates, clicking the ‘like’ button feels instant — the counter increments immediately, and the sync catches up in the background.” If the sync later reports a conflict, the UI must reconcile the difference.
Sync State and Data Shapes
Sync state describes the current status of synchronisation between a local database and the server. A client might be fully synced, syncing, behind, or offline. “Display the sync state in the UI so that users know whether their latest changes have reached the server.”
A data shape (or shape subscription in ElectricSQL) is a declaration of exactly which subset of data the client wants to receive. Rather than syncing an entire table, you subscribe to a shape — for example, only the rows belonging to the current user. “Define a narrow data shape for the mobile client so it does not download the entire orders table — only orders from the last 30 days.”
Replication lag is the delay between when a change is written on one node (usually the server) and when it appears on another node (usually the client). “In our tests, replication lag was under 200 milliseconds on a good connection, but could reach several seconds on a slow mobile network.”
A replication slot is a server-side mechanism in PostgreSQL that tracks how far a subscriber (like ElectricSQL) has consumed the database’s change log. “If a replication slot falls too far behind, PostgreSQL may block the deletion of old WAL files, causing disk space issues.”
Conflict Resolution and CRDTs
Conflict resolution is the process of deciding what happens when the same piece of data is changed in two places simultaneously — on the device while offline and on the server. “Our conflict resolution strategy uses a last-write-wins rule for simple text fields, but a CRDT for shared counters.”
A CRDT — Conflict-Free Replicated Data Type — is a data structure designed so that concurrent changes from multiple sources can always be merged automatically without conflicts. Common examples include counters, sets, and collaborative text documents. “We chose a CRDT for the shared task list so that two users adding items at the same time never produces a conflict.”
Eventual consistency means that all replicas (copies) of the data will converge to the same state given enough time, even if they temporarily disagree. It is a weaker guarantee than strong consistency, but it enables offline capability. “Eventual consistency is acceptable for a collaborative note-taking app, but you would not use it for a bank balance.”
A sync protocol is the set of rules that govern how changes travel between client and server — what format to use, how to order updates, how to handle conflicts. “ElectricSQL’s sync protocol is built on top of PostgreSQL’s logical replication, so it inherits its reliability guarantees.”
Key Vocabulary
| Term | Definition |
|---|---|
| offline capability | The ability to read and write data without an internet connection |
| optimistic update | Showing the result of an action in the UI before the server confirms it |
| sync state | The current status of synchronisation between local and remote data |
| data shape | A declared subset of data that a client subscribes to receive |
| replication lag | The delay between a change being written and appearing on all replicas |
| CRDT | A data structure that can be merged from concurrent changes without conflicts |
| eventual consistency | A guarantee that all replicas will converge to the same state over time |
| conflict resolution | The strategy for reconciling data that was changed in multiple places simultaneously |
Practice Tips
-
Use “sync” as both a noun and a verb. In English, we say “the sync failed” (noun) and “the app will sync when online” (verb). Both usages are natural. You can also say “to synchronise” (more formal) or “to sync” (everyday technical speech).
-
Explain eventual consistency with an analogy. A helpful English analogy is: “Eventual consistency is like two people editing a shared document offline — they may have different versions for a while, but when they reconnect, the changes merge.” Practising explanations like this builds both vocabulary and communication skills.
-
Learn “lag” in technical contexts. In everyday English, “lag” means a delay. In distributed systems, “replication lag” and “sync lag” describe delays between nodes. Also common: “network lag” and “input lag” in gaming. Notice how the word combines with different nouns.
-
Practise using “subscribe” correctly. In local-first architecture, clients subscribe to data shapes. The preposition is “to”. “The client subscribes to a shape that includes only the current project’s tasks.” This is the same preposition as in “subscribe to a newsletter.”
Conclusion
Local-first architecture and tools like ElectricSQL represent a significant shift in how we think about data, connectivity, and user experience. The vocabulary — CRDTs, eventual consistency, data shapes, sync state, conflict resolution — reflects deep ideas from distributed systems research now applied to everyday applications. Understanding and using this language accurately will help you contribute to technical discussions, write clear architecture documents, and ask the right questions when evaluating whether local-first is the right choice for your project.