Struct DatabaseHeader 

pub struct DatabaseHeader {

    pub page_size: PageSize,
    pub write_version: u8,
    pub read_version: u8,
    pub reserved_per_page: u8,
    pub change_counter: u32,
    pub page_count: u32,
    pub freelist_trunk: u32,
    pub freelist_count: u32,
    pub schema_cookie: u32,
    pub schema_format: u32,
    pub default_cache_size: i32,
    pub largest_root_page: u32,
    pub text_encoding: TextEncoding,
    pub user_version: u32,
    pub incremental_vacuum: u32,
    pub application_id: u32,
    pub format_version: u32,
    pub db_file_id: [u8; 16],
    pub version_valid_for: u32,
    pub sqlite_version: u32,
}

The 100-byte database file header layout.

This struct represents the parsed content of the first 100 bytes of a SQLite database file.

Fields

page_size: PageSize

Page size in bytes (stored as big-endian u16 at offset 16; value 1 means 65536).

write_version: u8

File format write version (1 = legacy, 2 = WAL).

read_version: u8

File format read version (1 = legacy, 2 = WAL).

reserved_per_page: u8

Reserved bytes per page (at offset 20).

change_counter: u32

File change counter (at offset 24).

page_count: u32

Total number of pages in the database file.

freelist_trunk: u32

Page number of the first freelist trunk page (0 if none).

freelist_count: u32

Total number of freelist pages.

schema_cookie: u32

Schema cookie (incremented on schema changes).

schema_format: u32

Schema format number (currently 4).

default_cache_size: i32

Persistent suggested default page-cache size, from an explicit PRAGMA default_cache_size (header bytes 48..52, big-endian i32).

This is the persisted field, not the runtime cache size. Stock SQLite leaves it 0 (“unset”) unless the application explicitly sets the pragma; when it reads 0 the runtime default (-2000, i.e. ~2 MiB via crate::limits::DEFAULT_CACHE_SIZE) applies without being written back. A freshly created database must therefore carry 0 here, so it is byte-faithful to stock and does not look like a client requested a cache size it never asked for (GH#354).

largest_root_page: u32

Largest root page number for auto-vacuum/incremental-vacuum (0 if not auto-vacuum).

text_encoding: TextEncoding

Database text encoding (1=UTF8, 2=UTF16le, 3=UTF16be).

user_version: u32

User version (from PRAGMA user_version).

incremental_vacuum: u32

Non-zero for incremental vacuum mode.

application_id: u32

Application ID (from PRAGMA application_id).

format_version: u32

FrankenSQLite on-disk format version, stored big-endian at header bytes 72..76 inside SQLite’s “reserved for expansion” region (bytes 72..=91).

Stock SQLite ignores that region, so stamping a non-zero value keeps the file readable by stock C SQLite — the rollback-safety handshake (bd-yaomh.6). A value of 0 means “never stamped” and is treated as the legacy/v1 format that every build can open. A build refuses to open a database whose format_version exceeds CURRENT_FSQLITE_FORMAT_VERSION so a downgraded binary cannot silently corrupt a database written by a newer release.

db_file_id: [u8; 16]

FrankenSQLite creation-stable database-file identity, stored as 16 raw bytes at header bytes 76..92 inside SQLite’s “reserved for expansion” region (bytes 72..=91), immediately after Self::format_version (72..76).

Stock SQLite ignores that region, so a non-zero identity keeps the file readable by stock C SQLite and never triggers any open-time refusal (unlike format_version, this field is read but never validated). It is generated once from OS randomness when a database is first created and is carried forward unchanged by every header round-trip and by VACUUM, so it stays stable for the physical life of the file. [0u8; 16] means “never stamped” and marks a legacy/pre-identity database.

The durable parallel-WAL commit certificate (-wal-cert / -wal-cert-head sidecars) binds to this identity so a stale certificate left behind across a database-file replacement cannot re-extend a fresh, smaller database to the replaced file’s committed page count (bd-85x9y / GH#364).

version_valid_for: u32

Version-valid-for number (the change counter value when the version number was stored).

sqlite_version: u32

SQLite version number that created the database.

Implementations

impl DatabaseHeader

pub fn from_bytes(buf: &[u8; 100]) -> Result<Self, DatabaseHeaderError>

Parse and validate a 100-byte database header.

pub const fn open_mode( &self, max_supported: u8, ) -> Result<DatabaseOpenMode, DatabaseHeaderError>

Compute the open mode implied by the header’s read/write version bytes.

pub const fn is_page_count_stale(&self) -> bool

Check whether the header-derived database size might be stale.

When version_valid_for != change_counter, header-derived fields like page_count may be stale and should be recomputed from the actual file size. This protects against partial header writes or external modification.

pub const fn page_count_from_file_size(&self, file_size: u64) -> Option<u32>

Compute the page count from the actual file size.

This should be used when is_page_count_stale() returns true. Returns None if the file size is not a multiple of the page size or would exceed u32::MAX pages.

pub fn write_to_bytes( &self, out: &mut [u8; 100], ) -> Result<(), DatabaseHeaderError>

Serialize this header into a 100-byte buffer.

pub fn to_bytes(&self) -> Result<[u8; 100], DatabaseHeaderError>

Serialize this header to bytes.

pub const fn set_format_version(&mut self, version: u32)

Stamp a specific FrankenSQLite on-disk format version into the header.

This is the write-side of the rollback-safety handshake (bd-yaomh.6): a build that first creates a newer on-disk artifact (for example the first .fsqlite-history sidecar) stamps the matching version here, so a later downgraded binary refuses to open the database instead of silently corrupting it. Until such an artifact exists, headers keep format_version == 0 (legacy) and stay byte-faithful to stock C SQLite.

Callers must only stamp a version this build can itself read back — i.e. version <= CURRENT_FSQLITE_FORMAT_VERSION — otherwise this very build would refuse to reopen the database it just wrote. The PRAGMA surface that gates the bump (fsqlite_enable_format_v2) is wired separately.

pub const fn set_db_file_id(&mut self, id: [u8; 16])

Stamp a creation-stable db-file identity into the header (bd-85x9y / GH#364).

Callers that create a brand new database stamp a value generated from OS randomness here. The identity is read but never validated on open (stock SQLite ignores the reserved region), so stamping is fully backward- and forward-compatible. An all-zero value keeps the header byte-faithful to a legacy/pre-identity database and is treated as “never stamped”.

Trait Implementations

impl Clone for DatabaseHeader

fn clone(&self) -> DatabaseHeader

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DatabaseHeader

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DatabaseHeader

fn default() -> Self

Returns the “default value” for a type.

impl Eq for DatabaseHeader

impl PartialEq for DatabaseHeader

fn eq(&self, other: &DatabaseHeader) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for DatabaseHeader