fbrescue
Open-source Firebird recovery tool: read-only data recovery for Firebird 2.5–5.0 databases.
fbrescue reads .fdb / .gdb files directly, without the Firebird engine, and gets data out of databases that gbak cannot back up. It never modifies the source file.
Status: v0.5. info and scan analyze a database; tables and export get the schema and the data out without the engine — from intact databases, and from damaged ones as far as the pages allow (recovery rate); page shows a single page; report makes a diagnostic report without data. Not exported yet: arrays and records with 48-bit transaction numbers — reported, never silently dropped. On a damaged database, work on a copy and try gfix and gbak first: they are the engine's own tools.
When to use it
The database does not open, a query or a backup stops with one of these, and Firebird's own gfix and gbak do not get past it:
internal Firebird consistency check (decompression overran buffer (179)), (wrong record length (183)), (cannot find tip page (165))database file appears corrupt, wrong page type, page ... is of wrong type (expected 5, found 0)I/O error during "read" operation for file, Error while trying to read from filegbak: ERROR ... gbak:Exiting before completion due to errors
Or the database is fine, but there is no Firebird to open it: fbrescue exports intact databases too — see open a .fdb file without Firebird, export to CSV or Excel, move the data to PostgreSQL.
What each error means and the order of steps that saves the most data: formeo.github.io/fbrescue (по-русски).
Install
Download the archive for your system from Releases: a single binary for Windows, Linux or macOS, with nothing else to install. Each release lists SHA-256 checksums in SHA256SUMS, and every archive carries a build provenance attestation, so you can check that it was built from this repository by its release workflow:
sha256sum -c SHA256SUMS --ignore-missing
gh attestation verify fbrescue_v0.5.0_windows_amd64.zip -R formeo/fbrescue
With Go 1.24 or later: go install github.com/formeo/fbrescue/cmd/fbrescue@latest.
Usage
$ fbrescue info shop.fdb
File shop.fdb · 2.4 MB · 307 pages × 8 KB
Engine ODS 13.1 (Firebird 5.0) · dialect 3
Created 2026-10-14 08:48:59 (UTC)
Tx OIT 21 · OAT 22 · OST 22 · next 22
Attributes force write
$ fbrescue scan shop.fdb
Pages 307 total · 287 in use · 20 free
data 141 · index 61 · index root 40 · pointer 40 · generator 1 · header 1 · page inventory 1 · transaction inventory 1 · type 10 1
Transactions 1-22: committed 22 · active 0 · dead 0 · limbo 0
Table Pointer pages Data pages Records Deleted Versions
T 1 40 2700 0 386
T2 1 16 1000 250 250
(38 system tables, 3332 records)
No problems found.
$ fbrescue export shop.fdb --out rescued --format sql
T 2700 rows ✓
T2 750 rows ✓
Wrote rescued: schema.sql and 2 sql files
| Command | What it does |
|---|
info <db> | header, ODS version, flags, warnings (nbackup lock, damaged header, truncated file) |
scan <db> | page map, damage, per-table summary. Exit status 2 when it finds problems: pages holding another page's contents, pages in use with an invalid type, broken pointer page chains, data pages no table references, missing transaction inventory pages, truncated files |
tables <db> | CREATE TABLE statements for the user tables, from the stored record formats |
export <db> --out <dir> | the rows of every user table, plus schema.sql. --format csv (default), sql (INSERTs for isql) or jsonl; --excel for CSV that Excel opens by double-click where the decimal separator is a comma (UTF-8 BOM, ;, decimal comma); --table NAME to pick tables; --charset WIN1251 to decode text stored in CHARACTER SET NONE; --include-deleted to also write deleted rows whose old version is still on disk to <table>.deleted.<format>; --versions all to write every version of every row still on disk, with its transaction and that transaction's state, to <table>.versions.<format>; --ddl schema.sql for tables whose definition is lost (see below). Exit status 2 when something was left out: the reasons are printed, and rows that could not be read are listed in _errors.jsonl |
page <db> <N> | one page decoded: type and header fields; for data pages every record with its flags, transaction state, version chain and values; pointer pages list their data pages |
report <db> | a JSON report to attach to a bug report: header, page map, problems found, what exporting each table ran into. No values; table and column names are replaced by numbers |
All commands take --json. A single static binary for Windows, Linux and macOS: no fbclient, no cgo. Multi-file databases are supported: secondary files are looked up next to the main file first. A damaged header page is not fatal for info and scan: the page size is detected from the other pages.
What export handles: every column type of Firebird 2.5–5.0 except arrays — BLOBs of every level, segmented and stream; INT128, DECFLOAT, TIME/TIMESTAMP WITH TIME ZONE with region zones; text in UTF8, UNICODE_FSS and the single-byte character sets (WIN125x, KOI8R/U, ISO8859_x, DOSxxx; not CYRL and NEXT); tables altered many times (each row is read with the format it was written with, columns added later get the default the engine would show); records larger than a page; the record encodings of Firebird 2.5 to 5.0. CSV keeps NULL (empty field) apart from an empty string (""). Each row is exported as SELECT would see it after all transactions finished: the newest committed version, read through the chain of older versions, including versions stored as differences. In tests a 140 MB database exports to CSV in under a second.
BLOBs in SQL exports: values up to 1 MB are written inline as joined literals; larger ones go to <table>.blobs/<row>.<column>.txt|bin, with NULL and a comment naming the file in the INSERT. CSV and JSON Lines always hold the whole value. Firebird 2.5's isql reads statements of at most 64 KB, so SQL files with large inline values load only with isql 3.0 or later.
Damaged databases
What export does when the file is damaged, instead of stopping:
- Pointer pages or RDB$PAGES damaged: every data page records its table and its place in the table, so the pages the pointer pages no longer reach are found by reading the whole file. Only pages the page inventory marks as in use are taken, so freed pages with old rows do not come back.
- Pages in the wrong place (Firebird 3+ pages carry their own number): read from where they are, and never taken for the page whose place they occupy.
- Transaction inventory damaged: versions of transactions older than the oldest interesting one are committed by definition. For newer ones whose state is lost, the newest version is taken as committed, and the export says for how many rows.
- Header page damaged: the page size comes from the other pages, the ODS version from the system tables (the one under which they read their own names).
- Table or column definitions damaged: tables missing from RDB$RELATIONS come out as
TABLE_<id>, columns missing from RDB$RELATION_FIELDS as FIELD_<id>. When the record formats themselves are lost, --ddl takes CREATE TABLE statements — the database's creation script, isql -x output, or the schema.sql of an earlier fbrescue export — and computes the record layout the engine would give those tables. A definition is matched to its table by name, or, when the name is lost too, by the length of the table's records. It works for tables whose columns were never dropped or changed.
Anything left out or uncertain is in the summary and in _errors.jsonl, and the exit status is 2.
Recovery rate
TestRecovery damages copies of a small shop database (three tables, 21 230 rows, indexes, text blobs) in each way below, ten copies per kind on each of Firebird 2.5, 3.0, 4.0 and 5.0, exports them, and compares every row with the export of the intact database by primary key. Changed, reported: a value could not be read, was written as NULL and is listed in _errors.jsonl. Changed silently and extra rows: wrong values with no warning — bytes changed inside a record, which Firebird pages carry no checksum to detect. With --ddl: the same, given the script that created the database.
| Damage | Copies | Rows recovered | With --ddl | Changed, reported | Changed silently | Extra rows | Export failed |
|---|
| zeroed data page | 40 | 99.8% | 99.8% | 2 | 0 | 0 | 0 |
| zeroed index page | 40 | 100.0% | 100.0% | 0 | 0 | 0 | 0 |
| zeroed blob page | 40 | 99.9% | 99.9% | 40 | 0 | 0 | 0 |
| zeroed pointer page | 40 | 100.0% | 100.0% | 0 | 0 | 0 | 0 |
| zeroed system table page | 40 | 95.0% | 100.0% | 0 | 0 | 0 | 0 |
| zeroed transaction inventory page | 40 | 100.0% | 100.0% | 0 | 0 | 0 | 0 |
| zeroed page inventory page | 40 | 100.0% | 100.0% | 0 | 0 | 0 | 0 |
| zeroed header page | 40 | 100.0% | 100.0% | 0 | 0 | 0 | 0 |
Rows on a page that is zeroed or cut off are gone; the rest is recovered. The test fails if these numbers get worse.
Roadmap
| Version | Scope |
|---|
| v0.1 | info and scan: correct analysis of Firebird 2.5–5.0, damaged files open |
| v0.2 | export of intact databases: core types, CSV and SQL, tables |
| v0.3 | BLOBs, record versions, deleted rows, Firebird 4 types, page |
| v0.4 | damaged databases: page structure rebuilt from the pages, published recovery rate, --ddl, report, --versions all |
| v0.5 | export --excel; site in English, Russian and Portuguese |
| v1.0 | load into a new database, stable JSON reports, package managers |
How correctness is checked
Every assumption about the on-disk format is tested against databases created by real Firebird engines; docs/format.md lists each one and how it was verified. tools/mkcorpus/mkcorpus.sh downloads Firebird 2.5, 3.0, 4.0 and 5.0 and creates 79 test databases in embedded mode: plain data, deleted rows, each header flag fbrescue names, multi-file, three TIP pages, more than one page inventory range, every exported column type with edge values, tables altered seven times, records larger than a page, rolled-back changes and record versions left on disk, BLOBs of every level, Firebird 4 types with edge values, a shop database for the damage tests. Each engine's own gstat -h and gstat -d -r -s output is saved as the reference.
The main export test is a round trip through the engine: the SQL export is loaded into a new database by the same Firebird version, and SELECT on it must print exactly what SELECT on the original prints — every value of every row, in the engine's own formatting. CI runs all tests against the corpus, including damaged copies (zeroed, misplaced and truncated pages, broken chains) and a check that no command ever changes the database file.
# Ubuntu: sudo apt-get install libtommath1 libncurses6
tools/mkcorpus/mkcorpus.sh corpus
FBRESCUE_CORPUS=$PWD/corpus go test ./...
Background
fbrescue replaces FirebirdRepairBase, whose problems are listed in FirebirdRepairBase#10.
License
MIT
