Tag: fbsimcity

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

Leave a comment

Correction (added 9 August 2026): the section below headed “A synchronous replica that dies hangs commits” is wrong. Dmitry Sibiryakov pointed this out on firebird-general, and the source confirms it. In src/jrd/replication/Publisher.cpp, checkStatus() is called with canThrow = false on the commit path, so it cannot throw; disable_on_error (default true) instead clears the replicating flags, disposes the replicator and logs STOP_ERROR. The commit succeeds and replication tears itself down.

The reason it can do that without misleading anyone is the part I had missed: Firebird’s synchronous replication is not two-phase commit, so there was never a durability guarantee to protect. The real failure mode is arguably worse than the hang I described — replication stops, commits keep succeeding, nobody is told, and the replica quietly rots until somebody notices. Fixed in v0.6.1. The original text is left below unchanged.

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.

FBSimCity v0.4.0: the backup yard — gbak pins the OIT, nbackup fills the delta

Leave a comment

FBSimCity, the explorable isometric city of Firebird internals, is at v0.4.0. This release adds a whole backup yard, built around what gbak and nbackup actually do.

gbak: the backup that pins your OIT

gbak takes a logical backup online: it attaches like any other client and reads every table through a snapshot transaction. That snapshot is the interesting part, because it pins the OIT for the entire run. Garbage collection stalls, cooperative GC refuses to demolish anything, and the record version towers climb until the backup finishes.

This is why a nightly gbak against a busy database and a mysteriously bloating database are so often the same story. Now you can watch it happen instead of inferring it from gstat -h: run the nightly gbak scenario.

nbackup and the difference file

nbackup is the other half: a physical backup, incremental by level. Level 0 copies the whole file, level 1 only the pages changed since level 0, and so on. The chain is enforced in the model just as it is in reality: ask for a level 1 without a level 0 and it refuses, and Restore chain reports which levels a restore would have to apply, in order. Lose level 0 and the rest are waste paper.

Locking the database with nbackup -L freezes the main file so it can be copied safely while the server keeps running. Every page written from that moment lands in the difference file instead, a new orange pit beside the main excavation that fills up visibly and merges back on unlock. Forget to unlock and it grows for as long as you watch: see a locked database filling its delta.

Dirty pages stopped being free

This release also fixes a genuine falsehood in the simulation. Evicting a dirty buffer used to cost nothing, which quietly understated write pressure. It now writes the page out first, so a reader that needs a frame pays for somebody else’s write.

The interesting part is what that does not cause. Because commits flush their page under forced writes, which is Firebird’s default, dirty evictions stay rare on a healthy database at around 1% of evictions, and only start biting when the cache is too small for the working set, reaching roughly 5% at 16 buffers. The honest lesson is “your cache is undersized”, not “writes are bad”, and the new evictions (dirty N) readout shows exactly that.

A knob audit

Since the whole point is intuition rather than emulation, v0.4.0 documents itself. docs/KNOBS.md lists every control and readout, what it does to the model, and whether the mechanism is real, merely scaled, or a plausible modeled stand-in, followed by the deliberate simplifications. Sweep here is time-triggered rather than transaction-gap-triggered; lock contention is a probability rather than a wait-for graph; no SQL is parsed at all. It is all in the table, so nobody has to discover it by reading the source.

Also in this release

  • Subsystem controls now live on the subsystem: start a sweep from the GC depot, run backup levels or lock the database from the nbackup vault, forget to commit a transaction from the Transaction Hall.
  • The screenshot driver no longer leaks browser profiles, and form controls are 16px so iOS Safari stops zooming the page.

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

Corrections are very welcome, especially on the backup 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.