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 with a new 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.

• 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, 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 lag build, or 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 commits hang instead — which is the honest behaviour, and the reason synchronous replication is a decision rather than a default. 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. Stop replication and discard the backlog, and the disk stops filling but the replica needs a fresh restore rather than a resume. Keep journalling, and nothing is lost if it returns soon — but you are betting free space at a steady rate, and if the volume fills the primary stops too, which is a far larger outage than the one you were protecting against.

Both answers cost something, and the verdict quotes numbers measured from the run.

Also in this release

• The test suite grew to 131 assertions, including commit-order preservation 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/JS, no build step)

It remains a model for intuition, not an emulator. What is real, merely scaled, or a plausible stand-in is written down in the knob audit. Corrections very welcome, particularly on the replication mechanics, which I modeled from the documentation rather than 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.

node-firebird catches up: roadmap complete, issue tracker at zero

Big news for anyone using Firebird from Node.js: the pure-JavaScript node-firebird driver shipped eight releases in under a week (v2.6.0 → v2.14.0), completing its entire roadmap and closing all 47 open issues — some dating back to 2015.

The driver now stands at feature parity with the best Node.js drivers for Postgres and MySQL, while staying pure JavaScript with zero native dependencies. It supports every server from Firebird 2.5 through the 6.0 snapshots, tested on Node 20–26.

Highlights for Firebird users

Firebird 6.0 Protocol 20, fully supported (v2.10.0). The long-standing Protocol 20 prepare hang was root-caused and fixed; Protocol 20 is now negotiated by default on Firebird 6 servers, including per-column schema metadata and the new owner option for CREATE DATABASE (firebird#7718).

The sporadic Srp failure, solved (v2.8.1). Srp/Srp256 attaches randomly failed with "Your user name and password are not defined" on ~1.2–1.7% of connections. Two SRP proof-serialization mismatches with the engine were fixed — 0 failures in 1000-attach loops afterwards. If you run Firebird 3+ with retry-on-attach workarounds, you can retire them.

Real single-byte codepage support (v2.13.0). WIN1250–WIN1258, ISO8859_2–9/13, KOI8R/KOI8U and DOS866 now encode and decode correctly — columns, parameters, literals and blobs. This also fixed parameters being silently sent as UTF-8 on non-UTF8 connections, and made the stock employee.fdb queryable under the default UTF8 connection.

Firebird 4 batch API put to work. Bulk inserts via executeBatch (v2.7.0, typically 5–10× faster than row-by-row) and a new batchStream writable stream (v2.13.0) — the COPY FROM analogue, with backpressure and all-or-nothing transaction semantics.

Replication-ready pooling (v2.14.0). Firebird.poolCluster targets primary/replica topologies built on Firebird 4+ logical replication: per-node pools, transparent failover, round-robin selection and node lifecycle events. Rounded out by pool events, live metrics and idle reaping (v2.8.0).

Modern API ergonomics. Injection-safe tagged-template queries, savepoints, affectedRows/result metadata via withMeta, server warnings surfaced as events, nestTables for JOIN column collisions, query cancellation with AbortSignal, first-class ESM, and ISC_USER/ISC_PASSWORD environment defaults.

One thing to check

Versions 2.7.0–2.9.0 serialised parallelWorkers with the wrong DPB tag — isc_dpb_set_db_replica — silently switching the attached database into replica mode. Fixed in v2.10.0; if you used that option, check MON$REPLICA_MODE on your databases.

Get it

npm install node-firebird

• GitHub: github.com/hgourvest/node-firebird
• npm: npmjs.com/package/node-firebird
• Releases & changelogs: github.com/hgourvest/node-firebird/releases

The issue tracker is empty and waiting for your feedback.

Announcing cl-firebird v1.0.0: Pure Common Lisp Driver with Full node-firebird Parity & Multi-Version CI Matrix

We are excited to announce the release of cl-firebird v1.0.0 — a pure Common Lisp database driver for Firebird 3.0, 4.0, 5.0, and 6.0+. Featuring full 1:1 feature parity with node-firebird, this release brings 12-factor connection URIs, thread-safe connection pooling, named placeholder parameter binding, custom type parsers (type-cast), streaming cursors, database events (POST_EVENT), Service Manager support, Firebird 6.0 tablespaces/schemas, and an automated GitHub Actions testing matrix.

Key Highlights

1. Pure Common Lisp Wire Protocol (Zero C / FFI Dependencies)

cl-firebird communicates directly over TCP sockets using Firebird's remote protocol (negotiating up to Protocol 20). It runs natively across ANSI Common Lisp implementations (SBCL, CCL, etc.) without requiring external C libraries or native shared objects (libfbclient).

2. 12-Factor Connection URIs & attach-or-create

Configure connections using standard URIs or traditional connection strings:

• URI syntax: firebird://user:pass@host:port/database?pageSize=8192&lowercase-keys=true (including IPv6 [::1])
• Traditional DSN: host/port:path
• attach-or-create: Connects to an existing database or automatically creates it if it does not yet exist.

3. Named Placeholders & SQL Injection Protection

• Named parameters (:name): Bind SQL parameters using property lists ((:name "Val")), association lists ((("name" . "Val"))), or hash-tables.
• SQL Escaping (escape / escape-string): Protects against SQL injection across strings, numbers, booleans, dates, octet vectors, and NULLs.

4. Built-in Thread-Safe Connection Pooling

Manage connection lifecycles with pool.lisp:

• Auto-reaping idle connections after configurable timeouts.
• Safe queueing and slot recovery under heavy concurrency.
• Live metrics getters: pool-total-count, pool-idle-count, pool-active-count, pool-waiting-count.

5. Custom Type Parsers (type-cast) & Statement Caching

• type-cast: Pass a custom decoder function (lambda (col default-fn) ...) to format values per column type (e.g., converting INT64 or DATE fields into custom representations).
• statement-cache-size: Transparently reuses prepared server-side statements per connection to eliminate redundant prepare round-trips.

6. High-Performance Streaming & Bulk Batch Execution

• sequentially: Stream large query results row-by-row with minimal memory footprint.
• execute-batch: Bulk parameter execution for high-throughput batch inserts and updates.

7. Firebird 6.0 Features & Protocol 20

• Native support for Firebird 6.0 physical tablespaces (create-tablespace, alter-tablespace, drop-tablespace) and schemas (create-schema).
• Session search paths (searchPath), default schemas (defaultSchema), and custom database ownership.

8. Database Events (POST_EVENT) & Service Manager

• Database Events: attach-event / detach-event listener for PSQL POST_EVENT signals.
• Service Manager: Administration API for backup/restore (.fbk), user management (service-add-user, service-get-users, etc.), trace sessions, and server diagnostics.

9. Comprehensive Testing & CI Matrix

Includes a 66-check FiveAM test suite and an automated GitHub Actions CI Matrix testing across Firebird 3.0, 4.0, 5.0, and 6.0-snapshot.

Code Examples

1. Connecting & Named Placeholder Queries

(use-package :cl-firebird)

(with-connection ("firebird://SYSDBA:masterkey@localhost:3050/employee?named-placeholders=true&lowercase-keys=true")
  (let ((users (query "SELECT id, name FROM users WHERE role = :role AND age > :age"
                      '(:role "admin" :age 25))))
    (dolist (u users)
      (format t "User: ~a (ID: ~a)~%" (getf u :name) (getf u :id)))))

2. Connection Pooling & Real-time Metrics

;; Create pool of up to 10 connections (minimum 2 idle, 30s timeout)
(defvar *pool* (create-pool 10 "firebird://SYSDBA:masterkey@localhost:3050/employee?min=2&idleTimeoutMillis=30000"))

(with-pooled-connection (conn *pool*)
  (query "SELECT * FROM employee"))

;; Inspect pool status
(format t "Active: ~a, Idle: ~a, Total: ~a~%"
        (pool-active-count *pool*)
        (pool-idle-count *pool*)
        (pool-total-count *pool*))

3. Custom Type Decoding (type-cast)

(defvar *conn*
  (connect "firebird://SYSDBA:masterkey@localhost:3050/employee"
           :type-cast (lambda (col default-fn)
                        (cond
                          ((eq (getf col :type-name) :int64)
                           (format nil "BIGINT-~a" (funcall default-fn)))
                          (t (funcall default-fn))))))

Links & Installation

• GitHub Repository: mariuz/cl-firebird
• Release Tag: v1.0.0
• Quicklisp Load: (ql:quickload :cl-firebird)
• Run Test Suite: sbcl --load test/run-matrix.lisp --quit

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

FBSimCity — the explorable isometric city of Firebird internals — is at v0.4.0, and 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 — 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 (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

I also fixed 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 consequence is what it does not do. Because commits flush their page under forced writes (Firebird's default), dirty evictions stay rare on a healthy database — around 1% of evictions — and only start biting when the cache is too small for the working set, reaching about 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 of this thing is intuition rather than emulation, v0.4.0 also 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, written down so nobody has to discover them by reading sim.js. Sweep here is time-triggered rather than transaction-gap-triggered; lock contention is a probability, not a wait-for graph; no SQL is parsed. It is all in the table.

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/JS, no build step)

Corrections are very welcome, especially on the backup mechanics — I modeled those 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: an explorable city that shows how Firebird works

I've published FBSimCity, an interactive visualization of Firebird internals: an explorable isometric city where every 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.

The simulation is Firebird-flavored throughout:

• MGA record versions stack a floor on a tower with every UPDATE, and the towers redden as chains grow.
• Next / OAT / OIT counters run live on the Transaction Hall facade. Flip on a long-running transaction and watch the OIT pin garbage collection while the version towers pile up — Firebird's version of bloat, visible in about twenty seconds.
• Cooperative GC and a sweep truck tour the tables, correctly refusing to demolish anything the OIT still protects.
• A page cache flashes hits and misses above the excavation that is the database file, where careful write ordering — not a WAL — keeps things consistent.
• Lock waits and deadlock rollbacks queue at the lock manager tower.

Version 0.3.0 adds a live version-chain inspector: click the Record Version Towers and watch the busiest table's chain update in real time, each version tagged with the transaction that wrote it and marked reachable or garbage against the current OIT. There is also a guided tour, a step-by-step query trace that walks one UPDATE through every station, six scenario presets (cache thrash, stuck OIT, lock contention, rush hour...), and a data-page anatomy diagram.

If you prefer reading to clicking, The life of a query is the same sixteen-station pipeline as an accessible, keyboard-navigable page that works with a screen reader.

You can share a reproducible state with deep links, for example this one drops you into a stuck-OIT city fifty simulated seconds in, with the chain inspector already open.

Try it: mariuz.github.io/FBSimCity
Source: github.com/mariuz/FBSimCity (MIT, plain HTML/JS, no build step, no dependencies)

Inspired by PGSimCity, the PostgreSQL equivalent. It is a scaled model for intuition, not an emulator — no SQL is parsed and no Firebird code runs in your browser — so corrections from people who know the engine internals are very welcome.

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.

Announcing node-firebird v2.6.0: TypeScript 7, Query Cancellation, Firebird 6.0 Support, and More

We are thrilled to share the journey of our last 7 releases (from v2.3.3 to v2.6.0), which mark one of the most transformative periods in the history of the node-firebird driver.

With this series of releases, we’ve migrated the driver to native TypeScript 7, implemented native Promise & async/await APIs, added support for Firebird 5.0 and 6.0 features, and introduced robust query cancellation support.

Here is a comprehensive summary of what's new and why you should upgrade today!

---

🌟 Key Highlights & Milestones

1. The TypeScript 7 Era

In v2.4.0, we successfully converted the entire project to native TypeScript 7. This ensures type safety across the driver, provides a better developer experience, and guarantees native compilation without overhead.

2. Modern Promises & async/await API

Beginning in v2.5.0 (TypeScript Phase B), we introduced a modern Promise-based API alongside the classic callback structure. You can now write clean, modern asynchronous code using async/await naturally.

3. Query Cancellation via AbortSignal

With the release of v2.6.0, we’ve added full query cancellation support. By using standard JavaScript AbortSignal, you can cancel long-running queries via op_cancel protocol interactions.

4. Firebird 6.0 & 5.0 Feature Parity

node-firebird now fully supports modern database engines:

• Firebird 6.0 Support: SQL Schemas, Tablespaces, Native JSON, Named Arguments mapping, ROW types, and Protocol Version List Limit (maxNegotiatedProtocols).
• Firebird 5.0 Support: Scrollable Cursors, RETURNING Multi-Rows, SKIP LOCKED operations, Parallel Workers, and Inline BLOBs.

---

📅 Release-by-Release Breakdown

🚀 v2.6.0 — Query Cancellation

• Query Cancellation: Full implementation of op_cancel allowing you to pass an AbortSignal to cancel queries mid-flight.
• Release Page: v2.6.0 Release Notes

🚀 v2.5.0 — TypeScript Phase B & Safety

• Promises/async-await: Expanded TypeScript Phase B compiler improvements to support async/await structures.
• Security & Logging: SRP handshake logging is now gated strictly behind FIREBIRD_DEBUG, ensuring database credentials and secrets are never leaked in logs.
• Roadmap Updates: Added a comprehensive driver-parity comparison against popular database drivers (like pg and mysql2).
• Release Page: v2.5.0 Release Notes

🚀 v2.4.2 — Documentation Refresher

• Developer Resources: Added a complete table of contents, community/resources index, and a comprehensive contributing guide to encourage community participation.
• Release Page: v2.4.2 Release Notes

🚀 v2.4.1 — Clean Up & Refinement

• Modern Tooling: Refreshed README and ROADMAP for the TypeScript 7 era and tidied up the repository root.
• Release Page: v2.4.1 Release Notes

🚀 v2.4.0 — The Big Upgrade: TypeScript 7 & Firebird 6.0

Our largest release in recent history, packing major feature upgrades:

• TypeScript 7 Migration: Moved the compiler and codebases to native TS7.
• Firebird 6.0 Features: Added SQL Schemas, Tablespaces, Native JSON, ROW type, named argument mappings, and protocol negotiating limits.
• Firebird 5.0 Features: Scrollable Cursors, inline BLOBs, SKIP LOCKED support, and RETURNING clause enhancements.
• Authentication & Wire Encryption: Dynamic srp256/384/512 authentication and modern chacha/chacha64 wire encryption support.
• Stability Fixes: Corrected in-flight event notification duplications, fixed preparation hangs on Firebird 6.0, and prevented callbacks from hanging when a connection is abruptly lost mid-flight.
• Release Page: v2.4.0 Release Notes

🚀 v2.3.4 — Dependency Maintenance

• Lockfile Updates: Routine maintenance and package lock updates to ensure clean and secure builds.
• Release Page: v2.3.4 Release Notes

🚀 v2.3.3 — Protocol Adjustments & Stability

• Connection & Encoding: Connection-level character set mapping fixes, TCP keep-alive settings, and a new connectTimeout parameter.
• BLOB Enhancements: Implemented blobReadChunkSize and serialized blob reading internally to prevent deadlocks under Firebird's concurrent handle limits.
• Platform Support: Added a proxy trap to bind socket methods for seamless compatibility with Deno.
• Release Page: v2.3.3 Release Notes

---

🛠️ Upgrading

Getting the latest improvements is as simple as upgrading via npm:

npm install node-firebird@latest

We want to thank all our contributors and the community for their feedback, bug reports, and pull requests that helped make this modern era of node-firebird possible!

Have questions or want to help contribute? Head over to the GitHub Repository and join the discussion.

Working on new Firebird VS code extension , still work in progress

Not bad for a few days of work , There are still lot's of bugs and UI inconsistencies 

ps: It's a fork of existing extension but using updated node drivers and updated roadmap (Firebird 6 support / Typescript 6.x)

pps: I need to recover my MFA Azure Developer account to publish it soon 

Going Native-Free: Introducing the Pure Node.js Wire Driver for Firebird

Published in Engineering • Pull Request #168 Summary

If you have ever built Node.js applications that communicate with a Firebird database, you are likely familiar with the standard setup routine. Traditionally, high-level drivers depended heavily on the native client library (fbclient).

While highly optimized, relying on a native dynamic link library (.dll, .so, or .dylib) frequently meant dealing with tedious cross-platform installation headaches, complex environment paths, and architecture mismatches.

That era is coming to a close. With the merging of Pull Request #168, the node-firebird-drivers ecosystem is taking a massive leap forward by introducing a completely native-free, pure TypeScript/JavaScript implementation: node-firebird-driver-wire.

The Problem: The Heavy Weight of Native Clients

Up until now, configuring Firebird in a modern Node.js environment usually required pointing your package to a local installation of the Firebird client. If you deployed your application inside a streamlined Docker container or onto a serverless environment (like AWS Lambda), getting those native client binaries to coordinate correctly could be a major chore.

The Solution: PR #168 and node-firebird-driver-wire

PR #168 fulfills a highly anticipated community request (tracked under Issue #166) to introduce a pure Node.js wire protocol driver.

Instead of wrapping around C++ bindings or hooking into a local fbclient library, this driver implements Firebird's native network protocol completely from scratch using standard Node.js TCP sockets (net.Socket).

What this means for developers:

• Zero Native Dependencies: You no longer need to ensure that fbclient is installed on your host system.
• Seamless Cross-Platform Portability: Written in pure JS/TS, the code runs identically on Windows, Linux, and macOS without local compilation.
• Streamlined Container Deployment: Building lightweight Docker containers (like Node-Alpine) is straightforward without OS-level database packages.

Architectural Overview

Under the hood, PR #168 establishes a modular separation within the monorepo:

1. node-firebird-driver: The shared interface layer containing universal definitions.
2. node-firebird-driver-native: The legacy client layer that directly talks to the native C++ API.
3. node-firebird-driver-wire (New!): The pure JS/TS layer that encodes and decodes the wire protocol over raw network sockets.

How to Use It

Switching to the wire driver mirrors the syntax of its native counterpart:

import { createWireClient } from 'node-firebird-driver-wire';

async function main() {
    const client = createWireClient();
    
    const attachment = await client.connect('localhost:3050/your-database.fdb', {
        username: 'SYSDBA',
        password: 'masterkey'
    });

    const transaction = await attachment.startTransaction();
    const resultSet = await attachment.execute(transaction, 'SELECT * FROM USERS');
    
    // ... process database logic ...

    await transaction.commit();
    await attachment.disconnect();
}

---

Wrapping Up

PR #168 marks a significant milestone for the Node.js and Firebird developer communities. By shedding the requirement for native underlying libraries, node-firebird-driver-wire positions Firebird as a modern, nimble, and serverless-friendly option for JavaScript developers.