Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

Why local-first, and how sync loses edits

After this lesson: I can explain why a last-writer-wins sync loses edits.

60 min lesson2 commandsCRDT lab: local-first sync with counters, sets, vector clocks and text in Python

A note that works on the train

You edit a shared shopping list on the train, with no signal. The app should not freeze or say "try again later". It should save your change at once and send it when the signal comes back.

Apps built this way are called local-first. The hard part is the moment two changed copies meet.

By the end of this lesson

Note

I can explain why a last-writer-wins sync loses edits.

Key words

WordWhat it meansExample
Local-firstthe copy on your device is the one you work on
Replicaone copy of the shared data
Syncsending changes between replicas
Last writer winsthe change with the latest time is keptLWW
Concurrent editschanges made without knowing about each other

The cells students fill in are left blank in this preview.

Three reasons to work locally first

Offline: the app keeps working with no network, on a train or in a basement. Speed: a change is saved on the device at once, with no round trip to a server. Ownership: your data lives on your device, so it is still yours if a server goes away.

The price is that two replicas can change the same data at the same time. Module 18, Distributed systems, called this eventual consistency.

The obvious sync keeps one whole copy

The simplest sync compares the time each copy was saved and keeps the newer copy. It looks fair.

But it throws away every change in the older copy, even changes to fields the newer copy never touched. The lab shows this with a note edited on a phone and a laptop.

Lose an edit with a naive sync

Command
docker exec jupyter python3 steps/lostedit.py

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Worked example: what the lab printed

CopyChangedSavedAfter naive sync
Phonetitle to "Trip to York"10:05Lost
Laptopbody to "Pack bags, book hotel"10:07Kept
Field by fieldboth fieldsnoneTitle and body both kept

The cells students fill in are left blank in this preview.

Try it: two cooks edit one recipe

Code: python
base = {"name": "Soup", "salt": "1 tsp", "time": "20 min"}

mine = dict(base)
mine["salt"] = "half a tsp"      # changed offline, saved at 14:10
mine_saved = 1410

yours = dict(base)
yours["time"] = "25 min"         # changed offline, saved at 14:12
yours_saved = 1412

# Whole copy, last saved wins
kept = yours if yours_saved > mine_saved else mine
print("whole copy keeps:", kept)

# Field by field: keep every field somebody changed
merged = dict(base)
for copy in (mine, yours):
    for field in copy:
        if copy[field] != base[field]:
            merged[field] = copy[field]
print("field by field:", merged)
# Now change yours["salt"] too. Which salt does field by field keep?

When both change the same field

Field by field fixes edits to different fields. When both replicas change the same field, one value has to win.

A last-writer-wins register keeps the value with the larger stamp, a pair of time and replica name. The name breaks a tie, so every replica picks the same winner.

See a register pick a winner

Command
docker exec jupyter python3 steps/register.py

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

A common mistake

Warning

Many people think the latest time always means the latest change. A device clock can be wrong. In the lab the phone's clock was slow, so its later write of purple, stamped 98, lost to green at 105. Use time to break ties only when losing a value is acceptable.

About this lab and its source: CRDT lab: local-first sync with counters, sets, vector clocks and text in Python

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.