FBSimCity v0.6.0: the replication district — journal segments, commit order, and a synchronous replica that dies

FBSimCity, the explorable isometric city of Firebird internals, is at v0.6.0. This release adds a replication district.

Replication without a log

Firebird has no write-ahead log to ship, so its replication is logical — and it has to be. As each transaction commits, the changes themselves are written into a replication journal segment. When a segment fills it is sealed and queued for the replicator, and a new one opens behind it. Crucially, the segments preserve commit order, so the replica replays history exactly as the primary lived it.

That gets three buildings:

• Journal Yard — where commits are journalled. If the segments cannot be shipped, they stack up here visibly.
• Replicator — asynchronous ships at its own pace and the replica trails, so commits never wait. Synchronous makes the commit itself wait for the replica, so the primary runs at the speed of the slowest replica.
• Replica Database — a second database, drawn as its own shallower excavation, replaying the journal in commit order with its applied history filling in as it catches up.

Set the replica slow and watch the lag build, or set it unreachable and watch the segments pile up: run the replica-lag scenario. Bring it back and it resumes from the oldest unshipped segment, in order.

A synchronous replica that dies hangs commits

This is the behaviour I was most careful to get right. A synchronous replica that becomes unreachable does not quietly fall back to asynchronous. Silently downgrading would mean claiming a durability guarantee the configuration no longer has, so the commits hang instead — which is the honest behaviour, and the reason synchronous replication is a decision rather than a default. You can watch it happen.

A fourth operator decision

The replica is gone and its journal segments are accumulating on the same volume the database writes to. Nobody can say when it comes back.

• Stop replication and discard the backlog — the disk stops filling immediately, but the replica is no longer a replica. Bringing it back is a fresh backup and restore, not a resume, and until then you have no second copy.
• Keep journalling and wait — nothing is lost if it returns soon. If it does not, you are betting free space at a steady rate, and if the volume fills the primary stops too: a much larger outage than the one you were protecting against.

Both answers cost something, and the verdict quotes numbers measured from the run rather than written in advance.

Also in this release

• The test suite grew to 131 assertions, including commit-order preservation across segments and in-order catch-up after an outage. It caught the two new scenarios being undocumented before this shipped, and a version mismatch between data.js and the on-screen badge.
• The top bar had been silently wrapping to two rows on narrower screens — a regression that crept in one button per release. It is a single row again.

City: mariuz.github.io/FBSimCity
Release notes: v0.6.0
Source: github.com/mariuz/FBSimCity (MIT, plain HTML and JavaScript, no build step)

It remains a model for intuition, not an emulator. What is real, what is merely scaled and what is a plausible stand-in is all written down in the knob audit. Corrections are very welcome, particularly on the replication mechanics, which I modeled from the documentation rather than from the engine source.

FBSimCity is an independent educational project, not affiliated with or endorsed by the Firebird Project. Firebird® is a registered trademark of the Firebird Foundation Incorporated.