TrueTime in Google Spanner

1
# Real-world timeline:
2
# 11:00:00.000 - T1 commits
3
# 11:00:00.500 - T2 starts
4
# 11:00:01.000 - T2 commits
5

6
# External consistency guarantee:
7
# T1.commit_timestamp < T2.commit_timestamp
8

9
# This seems obvious, but it's incredibly hard without TrueTime!

1
class SpannerTransaction:
2
    def __init__(self):
3
        self.start_time = TT.now().latest  # Pessimistic: latest possible time
4
        self.writes = []
5

6
    def add_write(self, key, value):
7
        """Buffer write operations."""
8
        self.writes.append((key, value))
9

10
    def commit(self):
11
        """
12
        Commit transaction using TrueTime.
13

14
        This implements the critical 'commit wait' protocol.
15
        """
16
        # Step 1: Assign commit timestamp
17
        # Use the latest bound to ensure this timestamp is >= all reads/writes
18
        interval = TT.now()
19
        s = interval.latest  # Assign commit timestamp
20

21
        print(f"Assigned commit timestamp: {s}")
22

23
        # Step 2: Apply writes to storage with timestamp 's'
24
        for key, value in self.writes:
25
            storage.write(key, value, timestamp=s)
26

27
        # Step 3: *** COMMIT WAIT ***
28
        # Wait until we're certain 's' is in the past at ALL servers
29
        # This ensures external consistency!
30
        while not TT.after(s):
31
            time.sleep(0.001)  # Sleep 1ms, check again
32

33
        print(f"Commit wait complete. Transaction is now visible.")
34

35
        # Step 4: Transaction is now committed and visible
36
        # Any future transaction will see this commit
37
        return s
38

39
# Example usage
40
tx = SpannerTransaction()
41
tx.add_write("account:123:balance", 1000)
42
commit_ts = tx.commit()
43

44
# The commit wait ensures that when this returns,
45
# ALL servers in the world agree this transaction happened in the past

1
Server A: Assigns commit timestamp = 100
2
Server A: Clock says current time = 95 (clock is ahead!)
3
Server B: Asks "what's the latest committed data?"
4
Server A: Returns data with timestamp 100
5
Server B: Its clock says current time = 98
6
Server B: Thinks the data is from the future! 🤯

1
# Time    Event                                    TT.now()
2
# ----    -----                                    --------
3
# 0ms     Transaction starts                       [98, 102]
4
# 5ms     All writes buffered                      [103, 107]
5
# 10ms    Call commit()                            [108, 112]
6
#         ↳ Assign s = 112 (latest bound)
7
#         ↳ Apply writes to storage
8
#         ↳ Start commit wait
9

10
# 11ms    Check TT.after(112)                      [109, 113]
11
#         ↳ 112 < 109? No → keep waiting
12

13
# 12ms    Check TT.after(112)                      [110, 114]
14
#         ↳ 112 < 110? No → keep waiting
15

16
# 13ms    Check TT.after(112)                      [111, 115]
17
#         ↳ 112 < 111? No → keep waiting
18

19
# 14ms    Check TT.after(112)                      [112, 116]
20
#         ↳ 112 < 112? No → keep waiting
21

22
# 15ms    Check TT.after(112)                      [113, 117]
23
#         ↳ 112 < 113? YES! → commit complete
24

25
# Total wait: ~5ms (roughly equal to ε)

1
class SnapshotRead:
2
    def __init__(self):
3
        # Choose a snapshot time that's safe
4
        # Use earliest bound to ensure data exists
5
        self.snapshot_timestamp = TT.now().earliest
6

7
    def read(self, key):
8
        """
9
        Read data as of the snapshot timestamp.
10

11
        No locks needed! Just read the most recent version
12
        with timestamp <= snapshot_timestamp.
13
        """
14
        return storage.read(key, timestamp=self.snapshot_timestamp)
15

16
# Example: Read account balances across multiple datacenters
17
snapshot = SnapshotRead()
18
balance_ny = snapshot.read("account:123:balance")  # New York
19
balance_london = snapshot.read("account:456:balance")  # London
20

21
# Both reads see a globally consistent snapshot!
22
# No locks, no coordination, works across continents.

1
Timeline:
2

3
Write Transaction (datacenter A):
4
  Start: 100    Commit: 112    Commit Wait: 117
5
         |-------writes-------|----wait----|
6
                                           ↑
7
                        ALL servers agree 112 is in past
8

9
Read Transaction (datacenter B):
10
  Start: 115    Snapshot: 113
11
         |--reads@113--|
12
                ↑
13
         Reads see all data committed before 113

1
Read latency (single datacenter):
2
  - Network RTT: ~1ms
3
  - Disk read: ~1ms (SSD)
4
  - Total: ~2-5ms ✅
5

6
Write latency (single datacenter):
7
  - Network RTT: ~1ms
8
  - Disk write: ~1ms
9
  - Commit wait: ~4ms ⚠️
10
  - Total: ~6-10ms
11

12
Cross-continental write:
13
  - Network RTT: ~100-150ms
14
  - Disk writes: ~1ms
15
  - Commit wait: ~4ms
16
  - Total: ~105-160ms

1
# Uncertainty impact on reads
2
interval = TT.now()
3
snapshot_timestamp = interval.earliest
4

5
# In the worst case, this snapshot could be up to ε old
6
max_staleness = interval.uncertainty  # ~4ms typical
7

8
# For most applications, 4ms staleness is imperceptible!

1
class BankTransfer:
2
    """Transfer money between accounts using Spanner."""
3

4
    def transfer(self, from_account, to_account, amount):
5
        # Start read-write transaction
6
        interval = TT.now()
7
        tx_start = interval.latest
8

9
        print(f"Transaction start: {tx_start}")
10
        print(f"Uncertainty: ±{interval.uncertainty/2}ms")
11

12
        # Read current balances (with timestamp)
13
        from_balance = storage.read(from_account, tx_start)
14
        to_balance = storage.read(to_account, tx_start)
15

16
        # Validate sufficient funds
17
        if from_balance < amount:
18
            raise InsufficientFunds()
19

20
        # Buffer writes
21
        writes = [
22
            (from_account, from_balance - amount),
23
            (to_account, to_balance + amount)
24
        ]
25

26
        # Commit with TrueTime
27
        commit_interval = TT.now()
28
        commit_ts = commit_interval.latest
29

30
        # Apply all writes
31
        for key, value in writes:
32
            storage.write(key, value, commit_ts)
33

34
        print(f"Commit timestamp: {commit_ts}")
35
        print(f"Starting commit wait...")
36

37
        # COMMIT WAIT
38
        wait_start = time.now()
39
        while not TT.after(commit_ts):
40
            time.sleep(0.001)
41
        wait_duration = time.now() - wait_start
42

43
        print(f"Commit wait completed in {wait_duration}ms")
44
        print(f"Transaction committed!")
45

46
        return commit_ts
47

48
# Execute transfer
49
transfer = BankTransfer()
50
ts = transfer.transfer("account:alice", "account:bob", 100)
51

52
# Output:
53
# Transaction start: 1700000112000
54
# Uncertainty: ±3ms
55
# Commit timestamp: 1700000118000
56
# Starting commit wait...
57
# Commit wait completed in 4.2ms
58
# Transaction committed!