FBSimCity — an explorable city that shows how Firebird works

[Adrian Marius Popa]

Hi all,

I've published FBSimCity, an interactive visualization of Firebird's internals: an explorable isometric "city" where each building is a subsystem from the classic "Conceptual Architecture for Firebird" paper (Chan & Yashkir), and queries commute through the pipeline as glowing particles — REMOTE harbor -> Y-valve -> DSQL -> JRD, with the lock manager tower watching over it.

It simulates the fun parts in scaled form: MGA record versions (every UPDATE stacks a floor on a tower), live Next/OAT/OIT counters — flip on a long-running transaction and watch the OIT pin garbage collection — cooperative GC plus a sweep truck, a page cache with realistic hit ratios, lock waits and deadlock rollbacks. There's a guided tour, a step-by-step "trace a query" mode, scenario presets, and a data-page anatomy diagram.

Try it: https://mariuz.github.io/FBSimCity/

Source: https://github.com/mariuz/FBSimCity (MIT, plain HTML/JS, no build step)

Inspired by PGSimCity, the PostgreSQL equivalent. It's a model for intuition, not an emulator — corrections from people who know the engine internals are very welcome.

Marius

[Adrian Marius Popa]

A quick update: FBSimCity v0.3.0 is out.

New since the announcement:

- Live version-chain inspector: version chains now carry the real id of the transaction that wrote each version. Click the Record Version Towers and watch the busiest table's chain update live — current version, versions kept for older snapshots, and garbage below the OIT. Chains go honestly non-monotonic when concurrent updates overtake each other in flight.

- "The life of a query": the whole sixteen-station pipeline (client -> Y-valve -> DSQL -> CMP -> EXE -> cache -> careful writes -> lock -> new version -> TIP commit -> home) as an accessible, keyboard-navigable, screen-reader-friendly text page: https://mariuz.github.io/FBSimCity/lifecycle.html

- Close-range orientation: zoom in and a chip names the building at screen center ("You are at: Execution Hall - EXE").

- Deep links for sharing a reproducible state, e.g. https://mariuz.github.io/FBSimCity/?scenario=stuckoit&warp=50&panel=mvcc drops you into a stuck-OIT city 50 simulated seconds in, with the chain inspector open.

Full release notes: https://github.com/mariuz/FBSimCity/releases

Marius

[Adrian Marius Popa]

Another update: FBSimCity v0.4.0 adds a backup yard, built around what gbak and nbackup actually do.

- gbak runs a logical backup online, and its snapshot transaction pins the OIT for the entire run. Start one against a busy city and watch garbage collection stall while the version towers climb — the reason a nightly backup and a mysteriously bloating database are so often the same story. You can watch it happen here:

  https://mariuz.github.io/FBSimCity/?scenario=nightlygbak&panel=gbak

- nbackup does physical backup by level. Level 0 is the whole file, level 1 only the pages changed since level 0, and the chain is enforced: asking for L1 without an L0 is refused, and "restore chain" reports which levels a restore would apply, in order.

- The difference file is a new pit beside the excavation. Locking the database (nbackup -L) freezes the main file and every page write diverts into the delta, which fills up visibly and merges back on unlock. Forget to unlock and it grows forever — shareable as a link:

  https://mariuz.github.io/FBSimCity/?scenario=steady&lock=1&warp=60&panel=delta

I also fixed a real falsehood in the simulation: evicting a dirty buffer used to cost nothing. It now writes the page out first, so a reader pays for someone else's write. Since commits flush their page under forced writes, dirty evictions stay rare on a healthy database and only start to bite when the cache is too small for the working set.

There is now also a knob audit that documents every control as real, merely scaled, or a modeled stand-in, together with the deliberate simplifications, so nobody has to read the source to find out what is honest:

  https://github.com/mariuz/FBSimCity/blob/main/docs/KNOBS.md

Full release notes: https://github.com/mariuz/FBSimCity/releases/tag/v0.4.0

Corrections are very welcome, especially on the backup mechanics — I modeled those from the documentation rather than from the engine source.

Marius