Struct Stats 

#[non_exhaustive]
pub struct Stats {
    pub handle_count: u64,
    pub total_pages: u64,
    pub file_size_bytes: u64,
    pub spillway_logical_bytes: Option<u64>,
    pub spillway_max_bytes: Option<u64>,
}

Read-only summary of database size/usage. Populated by the transaction manager; no methods here because there are no invariants to enforce.

I36 (ISSUES.md, 2026-05-22): #[non_exhaustive] so adding a fifth summary field (e.g. live-handle/total-handle ratio for retirement pressure) is not a breaking change. The companion ChiselCounters has carried the same attribute since the bench-suite series landed.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

handle_count: u64

Number of live handles (u64 ids currently mapped in the handle table).

total_pages: u64

Total allocated pages in the file, matching Superblock.total_pages.

file_size_bytes: u64

Raw size of the database file on disk. May exceed total_pages * PAGE_SIZE when a previous crash left orphan pages in the file tail — the last-durable superblock’s total_pages is authoritative, anything beyond it is dead weight that the next allocation will overwrite (see I4). Chisel is single-writer, so there is no concurrent commit that could cause a transient divergence.

spillway_logical_bytes: Option<u64>

I74 (ISSUES.md, 2026-05-22): current spillway logical-bytes in flight (PAGE_SIZE × LIVE resident spilled pages — a page read back and respilled within a transaction is not double-counted). None when the spillway has never been opened — it is lazily constructed on the first overflow spill, so None means “no overflow has happened yet on this handle.” Some(0) means “spillway exists but is empty (just truncated by commit / rollback).” The distinction matters for monitoring: a long-lived None says “this workload fits comfortably in cache,” whereas Some(0) says “we have spilled before, might again.”

spillway_max_bytes: Option<u64>

I74: the spillway’s max_bytes cap. Same None-vs-Some(0) distinction as spillway_logical_bytes. Operators predict SpillwayFull by watching spillway_logical_bytes / spillway_max_bytes climb across commits.

Trait Implementations

impl Clone for Stats

fn clone(&self) -> Stats

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Stats

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

Formats the value using the given formatter.