Header page structure

by Ann Harrison

A Firebird database has one header page per file, but the first one is by far the most important. When Firebird opens a database, it reads the first 1024 bytes of the file to determine whether the file is actually a database, whether its format (i.e. On Disk Structure or ODS) is one that the current engine understands, the size of a database page, whether the database is read/only, whether forced writes are required, and many other important bits of information. Subsequent header pages contain only the page number of the header of the next file, the sequence number of this file in the database, and the name of the next file.

The individual fields on the primary header page
Field type Size in bytes Function
hdr_header 16 This structure is defined on every page and includes the information below
hdr_page_size 2 length of a database page in bytes
hdr_ods_version 2 major and minor On Disk Structure version number
hdr_PAGES 4 the page number of the first pointer page for the RDB$PAGES table. The format format of the RDB$PAGES table is fixed for any ODS. The first pointer page allows the system to read the RDB$PAGES table and find all other parts of the metadata.
hdr_next_page 4 page number of header page of the next file in the database
hdr_oldest_transaction 4 oldest uncommitted transaction, whether rolled back, limbo, or active
hdr_oldest_active 4 oldest transaction active when any active transaction started
hdr_next_transaction 4 transaction id to be assigned to the next transaction when it starts
hdr_sequence 2 sequence number of this file in the database
hdr_flags 4 flag settings
hdr_creation_date 8 timestamp of database creation
hdr_attachment_id 4 identifier to assign to the next connection
hdr_shadow_count 4 event count for shadow synchronization
hdr_implementation 2 implementation numberof the database engine which created the database
hdr_ods_minor 2 current minor on disk structure version number
hdr_ods_minor_original 2 minor on disk structure version at the time of database creation
hdr_end 2 offset of the last entry in the variable length portion of the header
hdr_page_buffers 4 maximum number of pages in the database cache
hdr_bumped_transaction 4 unused, part of the abandoned write-ahead log
hdr_oldest_snapshot 4 confusing and redundant variant of oldest active
hdr_backup_pages 4 number of pages in files locked for backup (Nbak?)
hdr_misc 12 stuff to be named later, present for alignment, I think
hdr_data[1] 1 Clumplet data

Header page clumplets

Clumplets are optional extensions of the header information and start at the end of the fixed portion of the header. Clumplet data items have the format:

<type_byte>  <length_byte>  <data...>

New clumplet types can be added without invalidating the on disk structure because the engine skips unrecognized clumplets.

Clumplet types
Clumplet name value Meaning
HDR_end 0 last clumplet in the header
HDR_root_file_name 1 Original name of root file
HDR_journal_server 2 Name of journal server
HDR_file 3 Secondary file
HDR_last_page 4 Last logical page number of file
HDR_unlicensed 5 Count of unlicensed activity
HDR_sweep_interval 6 Transactions between sweeps
HDR_log_name 7 replay log name
HDR_journal_file 8 Intermediate journal file
HDR_password_file_key 9 Key to compare to password db
HDR_backup_info 10 WAL backup information
HDR_cache_file 11 Shared cache file - unused
HDR_max 11 Maximum HDR_clump value

Standard Page Header

Every page in the database starts with the standard page header, containing the following fields. The values present in the standard header for the first header page of a database are listed.

Page header fields
Field type Size in bytes Function
page type 1 value 1 meaning header page
page flags 1 not used for header pages
page checksum 2 the value 12345
page generation 4 a value incremented each time the page is written)
page sequence number 4 reserved for future use
page offset 4 reserved for future use

Header Page Flags

Possible settings for the flag field in the database header
Flag name Hex value Decimal value Meaning
hdr_active_shadow 0x1 1 file is an active shadow file
hdr_force_write 0x2 2 forced writes are enabled if this flag is set
hdr_short_journal 0x4 4 short-term journalling. Part of an abandoned journalling subsystem
hdr_long_journal 0x8 8 long-term journalling. Part of an abandoned journalling subsystem
hdr_no_checksums 0x10 16 don't calculate checksums. Checksums are no longer calculated
hdr_no_reserve 0x20 32 don't reserve space on each page for record versions created by updates and deletes
hdr_disable_cache 0x40 64 disable shared cache file. Another abandoned project.
hdr_shutdown 0x80 128 database is shutdown
hdr_SQL_dialect_3 0x100 256 database SQL dialect 3
hdr_read_only 0x200 512 Database in ReadOnly. If not set, DB is RW