🥮 mooncakes.io

    pagelens

    Read-only SQLite database and WAL file analyzer written in MoonBit

    sqlite
    wal
    database
    forensics
    parser
    Download zip
    Author
    Version
    0.1.0
    License
    Apache-2.0
    Repository
    Last updated
    last month
    Downloads
    8

    Dependencies

    #PageLens

    PageLens is a read-only SQLite database file and write-ahead log (WAL) analyzer written primarily in MoonBit.

    It parses bytes directly. It does not execute SQL and never modifies the database or WAL supplied by the user.

    #Why PageLens

    SQLite is often embedded behind an application, so a failed migration, a truncated copy, or an unexpected WAL can be hard to reason about without opening the database in a full SQL engine. PageLens exposes the on-disk structures themselves: headers, pages, B-trees, records, overflow chains, freelists, WAL transactions, and committed page overlays.

    The project is useful for file-format learning, database fault diagnosis, consistency triage, recovery teaching, and deterministic local inspection. Its boundary is deliberately narrow: offline, read-only structural analysis.

    #Features

    • Bounds-checked binary reader with big/little-endian integers, signed conversions, slicing, offset management, truncation errors, and SQLite varints.
    • Strict parsing of the 100-byte SQLite database header and all requested metadata fields.
    • Page addressing, all four B-tree page types, cell pointer arrays, freeblocks, fragmented bytes, payload layout, and child-page traversal.
    • SQLite record headers and serial types: NULL, signed integers, IEEE-754 floats, UTF-8/UTF-16 text, blobs, and the special integer constants.
    • Overflow payload sizing and guarded chain traversal with range, cycle, duplicate, and premature-end checks.
    • Freelist trunk/leaf traversal with count, loop, duplicate-reference, and header-consistency diagnostics.
    • WAL headers, both checksum byte orders, frame salts, rolling checksums, commit boundaries, transaction grouping, truncated tails, and uncommitted frames.
    • Immutable database/WAL snapshots at the newest valid commit, latest-frame page lookup, and byte-range change summaries.
    • INFO, WARNING, and ERROR consistency findings across database, B-tree, record, overflow, freelist, ownership, and WAL structures.
    • Human-readable and machine-readable JSON output.
    • Reproducible SQLite fixtures and CI smoke tests for every CLI command.

    #Installation

    Prerequisites:

    • A current stable MoonBit toolchain providing moon, moonc, and moonrun.
    • A native C toolchain when using the native CLI target.
    • Python 3 only when regenerating the example SQLite fixtures.

    Clone and resolve the one declared dependency:

    git clone https://github.com/geniuszby/pagelens.git
cd pagelens
moon update

    After the first mooncakes.io release, the library can be added to another MoonBit module with:

    moon add geniuszby/pagelens@0.1.0

    #Quick Start

    Generate the project-owned example databases, then inspect one:

    python3 scripts/generate_fixtures.py
moon run --target native cmd/pagelens -- inspect fixtures/generated/sample.db

    On Windows, use python instead of python3 when that is the installed command. Fixture generation is optional when analyzing your own files.

    #Usage

    pagelens inspect <database> [--json]
pagelens wal <wal-file> [--json]
pagelens snapshot <database> [--wal <wal-file>] [--json]
pagelens check <database> [--wal <wal-file>] [--json]

    During development, replace pagelens with:

    moon run --target native cmd/pagelens --

    The snapshot and check commands look for database-path-wal by default. Pass --wal to select another file. Check succeeds without a WAL when the default file does not exist; snapshot requires a WAL.

    #CLI

    #Inspect a database

    moon run --target native cmd/pagelens -- inspect app.db
moon run --target native cmd/pagelens -- inspect app.db --json

    The report includes every database-header field, physical page count, page 1 layout, schema B-tree reachability, freelist totals, and diagnostics.

    #Inspect a WAL

    moon run --target native cmd/pagelens -- wal app.db-wal

    Each frame reports its page number, commit database size, salt validity, and rolling-checksum validity. Frames are grouped into committed transactions or an uncommitted tail.

    #Build a committed snapshot

    moon run --target native cmd/pagelens -- snapshot app.db
moon run --target native cmd/pagelens -- snapshot app.db --wal saved.wal --json

    Only valid frames at or before the newest valid commit boundary are overlaid. The command reports changed pages and byte ranges; it does not write a merged database.

    #Check consistency

    moon run --target native cmd/pagelens -- check app.db
moon run --target native cmd/pagelens -- check app.db --wal app.db-wal --json

    Exit status is 0 when no ERROR diagnostic exists, 1 for a completed check with errors, and 2 for invalid command usage or an input that cannot be parsed.

    #Examples

    The generator creates four license-clean cases under fixtures/generated:

    • sample.db: tables, index records, deleted space, UTF-8 text, blobs, and an overflow payload.
    • snapshot.db plus snapshot.db-wal: a committed five-frame WAL pair.
    • invalid-magic.db: a database with a damaged magic header.
    • truncated.db: a deliberately shortened database.

    The current generated WAL produces five valid frames, two transactions, and three changed pages in the committed snapshot. See examples/README.md for copyable commands and expected facts. CI regenerates these files and runs all four commands.

    #Architecture

    file bytes
  -> BinaryReader
  -> database header / page layout
  -> B-tree cells / records / overflow / freelist
  -> WAL frames and commit boundaries
  -> immutable SnapshotView
  -> IntegrityReport
  -> text or JSON CLI reports

    The core library accepts immutable Bytes values and has no filesystem write API. Filesystem access exists only in cmd/pagelens. Major source files map directly to responsibilities:

    • binary.mbt and error.mbt: safe primitives and typed errors.
    • header.mbt and page.mbt: database and page metadata.
    • btree.mbt, record.mbt, overflow.mbt, freelist.mbt: storage structures.
    • wal.mbt and snapshot.mbt: WAL validation and committed overlays.
    • checker.mbt and report.mbt: aggregate analysis and presentation.
    • cmd/pagelens: argument parsing and read-only file loading.

    More detail is available in docs/architecture.md and docs/sqlite-format.md.

    #Testing

    Run the same checks used by CI:

    moon fmt --check
moon check --deny-warn
moon build
moon test --deny-warn
python3 scripts/generate_fixtures.py
moon run --target native cmd/pagelens -- check fixtures/generated/sample.db

    The suite covers valid and damaged headers, empty/truncated/non-SQLite inputs, varint boundaries, all B-tree page classes, records and serial types, overflow chains, freelists, WAL checksums and commit boundaries, snapshots, error aggregation, and report rendering. See docs/testing.md.

    #Build

    Portable library build:

    moon build --deny-warn

    Native command-line build:

    moon build --target native --deny-warn

    Packaging preview:

    moon package --list
moon publish --dry-run

    #Limitations

    • PageLens is not a SQL parser or execution engine.
    • It never writes, repairs, checkpoints, or recovers a database.
    • Rollback journals and the transient WAL-index/shm format are not parsed.
    • Pointer-map and lock-byte pages are reported as unclassified rather than decoded.
    • Encrypted or application-transformed SQLite pages are not decrypted.
    • Text decoding is loss-tolerant; the checker focuses on structural bounds and serial-type validity rather than proving semantic text correctness.
    • The first release provides structural recovery evidence, not a complete forensic or automated data-recovery product.

    #Roadmap

    • Detailed pointer-map reports for auto-vacuum databases.
    • Schema-object listing and optional row-oriented exploration.
    • User-selectable historical committed WAL boundaries.
    • Streaming access for files too large to hold in one immutable byte buffer.
    • Stable library API documentation generated for mooncakes.io.

    #Contributing

    Open an issue before changing the supported file-format boundary. Contributions should include focused tests, preserve read-only behavior, pass formatting, check, build, and test, and document any new dependency and its license. Do not commit private databases or files containing personal information.

    #License

    PageLens is licensed under the Apache License 2.0. See LICENSE. The only runtime dependency is moonbitlang/x, also Apache-2.0. The parser is an original implementation based on SQLite's public file-format specification; it does not contain SQLite or third-party parser source. Full attribution and dependency notes are in docs/third-party-notices.md.

    ParseError

    source
    pub(all) suberror ParseError {
      UnexpectedEnd(Int, Int, Int, String)
      InvalidRange(Int, Int, Int, String)
      InvalidMagic(String, String)
      InvalidValue(Int, String, String)
      InvalidPageNumber(UInt64, UInt64)
      IntegerOverflow(String)
      Unsupported(String)
    } derive(Eq, 
    Debug    )

    Errors raised by byte-level and SQLite format parsers.

    ParseError::message

    source
    fn ParseError::message(self : ParseError) -> String

    BinaryReader

    source
    pub(all) struct BinaryReader {
      data : Bytes
      start : Int
      limit : Int
      position : Int
      context : String
    }

    A bounded cursor over immutable bytes.

    Every read checks the active range before indexing the input. A reader can be forked into a smaller range, which lets page and cell parsers enforce their own boundaries even when the underlying database buffer is larger.

    BinaryReader::absolute_position

    source
    fn BinaryReader::absolute_position(self : BinaryReader) -> Int

    BinaryReader::fork

    source
    fn BinaryReader::fork(self : BinaryReader, count : Int, context : String) -> BinaryReader raise ParseError

    BinaryReader::is_empty

    source
    fn BinaryReader::is_empty(self : BinaryReader) -> Bool

    BinaryReader::length

    source
    fn BinaryReader::length(self : BinaryReader) -> Int

    BinaryReader::named

    source
    fn BinaryReader::named(data : Bytes, context : String) -> BinaryReader

    BinaryReader::new

    source
    fn BinaryReader::new(data : Bytes) -> BinaryReader

    BinaryReader::peek_u8

    source
    fn BinaryReader::peek_u8(self : BinaryReader) -> Byte raise ParseError

    BinaryReader::peek_varint

    source
    fn BinaryReader::peek_varint(self : BinaryReader) -> Varint raise ParseError

    Decode a varint without changing the reader's position.

    BinaryReader::range

    source
    fn BinaryReader::range(data : Bytes, offset : Int, length : Int, context : String) -> BinaryReader raise ParseError

    BinaryReader::read_ascii

    source
    fn BinaryReader::read_ascii(self : BinaryReader, count : Int) -> String raise ParseError

    BinaryReader::read_bytes

    source
    fn BinaryReader::read_bytes(self : BinaryReader, count : Int) -> Bytes raise ParseError

    BinaryReader::read_f64_be

    source
    fn BinaryReader::read_f64_be(self : BinaryReader) -> Double raise ParseError

    BinaryReader::read_i16_be

    source
    fn BinaryReader::read_i16_be(self : BinaryReader) -> Int raise ParseError

    BinaryReader::read_i24_be

    source
    fn BinaryReader::read_i24_be(self : BinaryReader) -> Int raise ParseError

    BinaryReader::read_i32_be

    source
    fn BinaryReader::read_i32_be(self : BinaryReader) -> Int64 raise ParseError

    BinaryReader::read_i64_be

    source
    fn BinaryReader::read_i64_be(self : BinaryReader) -> Int64 raise ParseError

    BinaryReader::read_i8

    source
    fn BinaryReader::read_i8(self : BinaryReader) -> Int raise ParseError

    BinaryReader::read_int_be

    source
    fn BinaryReader::read_int_be(self : BinaryReader, width : Int) -> Int64 raise ParseError

    Read a two's-complement signed big-endian integer using 1..8 bytes.

    BinaryReader::read_u16_be

    source
    fn BinaryReader::read_u16_be(self : BinaryReader) -> Int raise ParseError

    BinaryReader::read_u24_be

    source
    fn BinaryReader::read_u24_be(self : BinaryReader) -> Int raise ParseError

    BinaryReader::read_u32_be

    source
    fn BinaryReader::read_u32_be(self : BinaryReader) -> UInt64 raise ParseError

    BinaryReader::read_u32_le

    source
    fn BinaryReader::read_u32_le(self : BinaryReader) -> UInt64 raise ParseError

    BinaryReader::read_u64_be

    source
    fn BinaryReader::read_u64_be(self : BinaryReader) -> UInt64 raise ParseError

    BinaryReader::read_u8

    source
    fn BinaryReader::read_u8(self : BinaryReader) -> Byte raise ParseError

    BinaryReader::read_uint_be

    source
    fn BinaryReader::read_uint_be(self : BinaryReader, width : Int) -> UInt64 raise ParseError

    Read an unsigned big-endian integer using exactly width bytes.

    BinaryReader::read_varint

    source
    fn BinaryReader::read_varint(self : BinaryReader) -> Varint raise ParseError

    Decode SQLite's one-to-nine-byte unsigned varint representation.

    BinaryReader::relative_position

    source
    fn BinaryReader::relative_position(self : BinaryReader) -> Int

    BinaryReader::remaining

    source
    fn BinaryReader::remaining(self : BinaryReader) -> Int

    BinaryReader::seek_absolute

    source
    fn BinaryReader::seek_absolute(self : BinaryReader, offset : Int) -> Unit raise ParseError

    BinaryReader::seek_relative

    source
    fn BinaryReader::seek_relative(self : BinaryReader, offset : Int) -> Unit raise ParseError

    BinaryReader::skip

    source
    fn BinaryReader::skip(self : BinaryReader, count : Int) -> Unit raise ParseError

    BtreeCell

    source
    pub(all) struct BtreeCell {
      page_number : UInt64
      index : Int
      offset : Int
      page_type : PageType
      left_child_page : UInt64?
      rowid : Int64?
      payload_size : Int
      local_payload : Bytes
      overflow_page : UInt64?
      encoded_size : Int
    } derive(Eq, 
    Debug    )

    A decoded cell from one of SQLite's four B-tree page types.

    BtreeCell::has_overflow

    source
    fn BtreeCell::has_overflow(self : BtreeCell) -> Bool

    BtreeCell::local_payload_size

    source
    fn BtreeCell::local_payload_size(self : BtreeCell) -> Int

    BtreePageHeader

    source
    pub(all) struct BtreePageHeader {
      page_number : UInt64
      page_offset : Int
      header_offset : Int
      page_type : PageType
      first_freeblock : Int
      cell_count : Int
      cell_content_area : Int
      fragmented_free_bytes : Int
      right_most_pointer : UInt64?
      cell_pointers : Array[Int]
    } derive(Eq, 
    Debug    )

    Parsed common header of a B-tree page.

    BtreePageHeader::cell_content_start

    source
    fn BtreePageHeader::cell_content_start(self : BtreePageHeader) -> Int

    BtreePageHeader::header_size

    source
    fn BtreePageHeader::header_size(self : BtreePageHeader) -> Int

    BtreePageHeader::pointer_array_end

    source
    fn BtreePageHeader::pointer_array_end(self : BtreePageHeader) -> Int

    BtreePageHeader::pointer_array_start

    source
    fn BtreePageHeader::pointer_array_start(self : BtreePageHeader) -> Int

    BtreePageHeader::unallocated_bytes

    source
    fn BtreePageHeader::unallocated_bytes(self : BtreePageHeader) -> Int

    BtreeStatistics

    source
    pub(all) struct BtreeStatistics {
      root_page : UInt64
      total_pages : Int
      interior_pages : Int
      leaf_pages : Int
      table_pages : Int
      index_pages : Int
      total_cells : Int
      maximum_depth : Int
      maximum_children : Int
    } derive(Eq, 
    Debug    )

    Aggregate shape of one traversed SQLite B-tree.

    BtreeStatistics::average_cells_per_page

    source
    fn BtreeStatistics::average_cells_per_page(self : BtreeStatistics) -> Double

    BtreeStatistics::is_single_page

    source
    fn BtreeStatistics::is_single_page(self : BtreeStatistics) -> Bool

    BtreeTraversal

    source
    pub(all) struct BtreeTraversal {
      root_page : UInt64
      visits : Array[BtreeVisit]
      diagnostics : Array[Diagnostic]
    } derive(Eq, 
    Debug    )

    BtreeVisit

    source
    pub(all) struct BtreeVisit {
      page_number : UInt64
      depth : Int
      page_type : PageType
      cell_count : Int
      child_pages : Array[UInt64]
    } derive(Eq, 
    Debug    )

    ChangedRange

    source
    pub(all) struct ChangedRange {
      offset : Int
      length : Int
    } derive(Eq, 
    Debug    )

    One contiguous byte range changed by a WAL frame.

    DatabaseHeader

    source
    pub(all) struct DatabaseHeader {
      page_size : Int
      write_version : Int
      read_version : Int
      reserved_bytes : Int
      max_embedded_payload_fraction : Int
      min_embedded_payload_fraction : Int
      leaf_payload_fraction : Int
      file_change_counter : UInt64
      database_size_pages : UInt64
      first_freelist_trunk_page : UInt64
      total_freelist_pages : UInt64
      schema_cookie : UInt64
      schema_format : UInt64
      default_page_cache_size : Int64
      largest_root_btree_page : UInt64
      text_encoding : TextEncoding
      user_version : UInt64
      incremental_vacuum : UInt64
      application_id : UInt64
      version_valid_for : UInt64
      sqlite_version_number : UInt64
    } derive(Eq, 
    Debug    )

    Parsed representation of SQLite's 100-byte database header.

    DatabaseHeader::effective_database_pages

    source
    fn DatabaseHeader::effective_database_pages(self : DatabaseHeader, file_length : Int) -> UInt64

    DatabaseHeader::is_wal_mode

    source
    fn DatabaseHeader::is_wal_mode(self : DatabaseHeader) -> Bool

    DatabaseHeader::usable_page_size

    source
    fn DatabaseHeader::usable_page_size(self : DatabaseHeader) -> Int

    DatabaseImage

    source
    pub(all) struct DatabaseImage {
      data : Bytes
      header : DatabaseHeader
      page_count : UInt64
    }

    Immutable database image backed by the caller-provided bytes.

    DatabaseImage::file_length

    source
    fn DatabaseImage::file_length(self : DatabaseImage) -> Int

    DatabaseImage::open

    source
    fn DatabaseImage::open(data : Bytes) -> DatabaseImage raise ParseError

    DatabaseImage::page_bytes

    source
    fn DatabaseImage::page_bytes(self : DatabaseImage, page_number : UInt64) -> Bytes raise ParseError

    DatabaseImage::page_offset

    source
    fn DatabaseImage::page_offset(self : DatabaseImage, page_number : UInt64) -> Int raise ParseError

    DatabaseImage::page_reader

    source
    fn DatabaseImage::page_reader(self : DatabaseImage, page_number : UInt64, context : String) -> BinaryReader raise ParseError

    DatabaseImage::validate_page_number

    source
    fn DatabaseImage::validate_page_number(self : DatabaseImage, page_number : UInt64) -> Unit raise ParseError

    DatabaseInspection

    source
    pub(all) struct DatabaseInspection {
      header : DatabaseHeader
      physical_page_count : UInt64
      file_length : Int
      page_one : BtreePageHeader
      page_one_layout : PageLayout
      schema_tree : BtreeTraversal
      freelist : FreelistReport
      diagnostics : Array[Diagnostic]
    }

    High-level database facts used by the CLI's text and JSON renderers.

    Diagnostic

    source
    pub(all) struct Diagnostic {
      severity : Severity
      code : String
      message : String
      offset : Int?
      page_number : UInt64?
    } derive(Eq, 
    Debug    )

    A non-fatal parser or validation observation.

    Diagnostic::error

    source
    fn Diagnostic::error(code : String, message : String, offset? : Int, page_number? : UInt64) -> Diagnostic

    Diagnostic::info

    source
    fn Diagnostic::info(code : String, message : String, offset? : Int, page_number? : UInt64) -> Diagnostic

    Diagnostic::warning

    source
    fn Diagnostic::warning(code : String, message : String, offset? : Int, page_number? : UInt64) -> Diagnostic

    Freeblock

    source
    pub(all) struct Freeblock {
      offset : Int
      next : Int
      size : Int
    } derive(Eq, 
    Debug    )

    FreelistReport

    source
    pub(all) struct FreelistReport {
      trunks : Array[FreelistTrunk]
      trunk_pages : Array[UInt64]
      leaf_pages : Array[UInt64]
      diagnostics : Array[Diagnostic]
      declared_page_count : UInt64
    } derive(
    Debug    )

    A complete walk of the freelist rooted in the database header.

    FreelistReport::observed_page_count

    source
    fn FreelistReport::observed_page_count(self : FreelistReport) -> Int

    FreelistTrunk

    source
    pub(all) struct FreelistTrunk {
      page_number : UInt64
      next_trunk_page : UInt64
      leaf_count : Int
      leaf_pages : Array[UInt64]
    } derive(Eq, 
    Debug    )

    One SQLite freelist trunk page and the leaf page numbers stored on it.

    IntegrityReport

    source
    pub(all) struct IntegrityReport {
      diagnostics : Array[Diagnostic]
      database_opened : Bool
      pages_examined : Int
      btree_pages : Int
      btree_cells : Int
      records_decoded : Int
      overflow_pages : Int
      freelist_pages : Int
      wal_frames : Int
    }

    Aggregate outcome of PageLens's structural consistency pass.

    IntegrityReport::count

    source
    fn IntegrityReport::count(self : IntegrityReport, severity : Severity) -> Int

    IntegrityReport::error_count

    source
    fn IntegrityReport::error_count(self : IntegrityReport) -> Int

    IntegrityReport::info_count

    source
    fn IntegrityReport::info_count(self : IntegrityReport) -> Int

    IntegrityReport::is_ok

    source
    fn IntegrityReport::is_ok(self : IntegrityReport) -> Bool

    IntegrityReport::warning_count

    source
    fn IntegrityReport::warning_count(self : IntegrityReport) -> Int

    OverflowChain

    source
    pub(all) struct OverflowChain {
      first_page : UInt64
      pages : Array[UInt64]
      payload : Bytes
      diagnostics : Array[Diagnostic]
    } derive(Eq, 
    Debug    )

    PageDifference

    source
    pub(all) struct PageDifference {
      page_number : UInt64
      frame_index : Int
      changed_bytes : Int
      first_changed_offset : Int?
      last_changed_offset : Int?
      ranges : Array[ChangedRange]
    } derive(Eq, 
    Debug    )

    PageLayout

    source
    pub(all) struct PageLayout {
      page_number : UInt64
      header_bytes : Int
      pointer_array_bytes : Int
      unallocated_bytes : Int
      cell_content_bytes : Int
      freeblock_bytes : Int
      fragmented_free_bytes : Int
      usable_bytes : Int
      freeblocks : Array[Freeblock]
    } derive(Eq, 
    Debug    )

    PageLayout::total_free_bytes

    source
    fn PageLayout::total_free_bytes(self : PageLayout) -> Int

    PageType

    source
    pub(all) enum PageType {
      IndexInterior
      TableInterior
      IndexLeaf
      TableLeaf
    } derive(Compare, Eq, 
    Debug    )

    The four B-tree page types defined by the SQLite file format.

    PageType::flag

    source
    fn PageType::flag(self : PageType) -> Int

    PageType::from_flag

    source
    fn PageType::from_flag(flag : Int, offset : Int) -> PageType raise ParseError

    PageType::header_size

    source
    fn PageType::header_size(self : PageType) -> Int

    PageType::is_interior

    source
    fn PageType::is_interior(self : PageType) -> Bool

    PageType::is_table

    source
    fn PageType::is_table(self : PageType) -> Bool

    PageType::label

    source
    fn PageType::label(self : PageType) -> String

    RecordColumn

    source
    pub(all) struct RecordColumn {
      index : Int
      serial_type : UInt64
      body_offset : Int
      byte_length : Int
      value : RecordValue
    } derive(Eq, 
    Debug    )

    RecordValue

    source
    pub(all) enum RecordValue {
      Null
      Integer(Int64)
      Real(Double)
      Text(String)
      Blob(Bytes)
    } derive(Eq, 
    Debug    )

    One decoded value in a SQLite record body.

    RecordValue::display

    source
    fn RecordValue::display(self : RecordValue) -> String

    RecordValue::kind

    source
    fn RecordValue::kind(self : RecordValue) -> String

    Severity

    source
    pub(all) enum Severity {
      Info
      Warning
      Error
    } derive(Compare, Eq, 
    Debug    )

    Stable severity levels used by validation and consistency reports.

    Severity::label

    source
    fn Severity::label(self : Severity) -> String

    SnapshotPage

    source
    pub(all) struct SnapshotPage {
      page_number : UInt64
      source : SnapshotPageSource
      bytes : Bytes
    } derive(Eq, 
    Debug    )

    SnapshotPageSource

    source
    pub(all) enum SnapshotPageSource {
      DatabaseFile
      WalFrame(Int)
    } derive(Eq, 
    Debug    )

    SnapshotStatistics

    source
    pub(all) struct SnapshotStatistics {
      commit_frame : Int
      logical_page_count : UInt64
      changed_pages : Int
      changed_bytes : Int
      changed_ranges : Int
      pages_added_by_wal : Int
      largest_page_change : Int
    } derive(Eq, 
    Debug    )

    SnapshotStatistics::average_changed_bytes_per_page

    source
    fn SnapshotStatistics::average_changed_bytes_per_page(self : SnapshotStatistics) -> Double

    SnapshotStatistics::is_unchanged

    source
    fn SnapshotStatistics::is_unchanged(self : SnapshotStatistics) -> Bool

    SnapshotView

    source
    pub(all) struct SnapshotView {
      database : DatabaseImage
      wal : WalFile
      max_frame : Int
      logical_page_count : UInt64
    }

    An immutable database view at one committed WAL boundary.

    SnapshotView::at_commit

    source
    fn SnapshotView::at_commit(database : DatabaseImage, wal : WalFile, frame_index : Int) -> SnapshotView raise ParseError

    SnapshotView::changed_pages

    source
    fn SnapshotView::changed_pages(self : SnapshotView) -> Array[UInt64]

    SnapshotView::difference_for_page

    source
    fn SnapshotView::difference_for_page(self : SnapshotView, page_number : UInt64) -> PageDifference? raise ParseError

    SnapshotView::differences

    source
    fn SnapshotView::differences(self : SnapshotView) -> Array[PageDifference] raise ParseError

    SnapshotView::page_size

    source
    fn SnapshotView::page_size(self : SnapshotView) -> Int

    SnapshotView::read_page

    source
    fn SnapshotView::read_page(self : SnapshotView, page_number : UInt64) -> SnapshotPage raise ParseError

    SnapshotView::uses_wal

    source
    fn SnapshotView::uses_wal(self : SnapshotView) -> Bool

    SqliteRecord

    source
    pub(all) struct SqliteRecord {
      header_size : Int
      body_offset : Int
      columns : Array[RecordColumn]
      trailing_bytes : Int
    } derive(Eq, 
    Debug    )

    SqliteRecord::column_count

    source
    fn SqliteRecord::column_count(self : SqliteRecord) -> Int

    SqliteRecord::value

    source
    fn SqliteRecord::value(self : SqliteRecord, index : Int) -> RecordValue?

    TextEncoding

    source
    pub(all) enum TextEncoding {
      Utf8
      Utf16Le
      Utf16Be
      Unspecified
    } derive(Eq, 
    Debug    )

    Text encodings allowed by the SQLite database header.

    TextEncoding::from_header

    source
    fn TextEncoding::from_header(value : UInt64) -> TextEncoding raise ParseError

    TextEncoding::label

    source
    fn TextEncoding::label(self : TextEncoding) -> String

    Varint

    source
    pub(all) struct Varint {
      value : UInt64
      length : Int
    } derive(Eq, 
    Debug    )

    Result of decoding one SQLite variable-length integer.

    WalChecksum

    source
    pub(all) struct WalChecksum {
      first : UInt64
      second : UInt64
    } derive(Eq, 
    Debug    )

    WalChecksumOrder

    source
    pub(all) enum WalChecksumOrder {
      BigEndian
      LittleEndian
    } derive(Eq, 
    Debug    )

    Magic 0x377f0683 checksums words as big-endian; 0x377f0682 uses little-endian words. All structural fields remain big-endian.

    WalFile

    source
    pub(all) struct WalFile {
      header : WalHeader
      frames : Array[WalFrame]
      transactions : Array[WalTransaction]
      diagnostics : Array[Diagnostic]
      trailing_bytes : Int
      last_commit_frame : Int?
    } derive(
    Debug    )

    WalFile::committed_transaction_count

    source
    fn WalFile::committed_transaction_count(self : WalFile) -> Int

    WalFile::latest_frame_for_page

    source
    fn WalFile::latest_frame_for_page(self : WalFile, page_number : UInt64, max_frame? : Int) -> WalFrame?

    Return the newest valid occurrence of a page not newer than max_frame. Frame indexes are one-based, matching the CLI and SQLite documentation.

    WalFile::page_histories

    source
    fn WalFile::page_histories(self : WalFile) -> Array[WalPageHistory]

    WalFile::uncommitted_frame_count

    source
    fn WalFile::uncommitted_frame_count(self : WalFile) -> Int

    WalFile::valid_frame_count

    source
    fn WalFile::valid_frame_count(self : WalFile) -> Int

    WalFrame

    source
    pub(all) struct WalFrame {
      index : Int
      offset : Int
      page_number : UInt64
      database_size_after_commit : UInt64
      salt_first : UInt64
      salt_second : UInt64
      checksum : WalChecksum
      computed_checksum : WalChecksum
      page_data : Bytes
      salt_valid : Bool
      checksum_valid : Bool
    } derive(Eq, 
    Debug    )

    WalFrame::is_commit

    source
    fn WalFrame::is_commit(self : WalFrame) -> Bool

    WalFrame::is_valid

    source
    fn WalFrame::is_valid(self : WalFrame) -> Bool

    WalHeader

    source
    pub(all) struct WalHeader {
      magic : UInt64
      format_version : UInt64
      page_size : Int
      checkpoint_sequence : UInt64
      salt_first : UInt64
      salt_second : UInt64
      checksum : WalChecksum
      computed_checksum : WalChecksum
      checksum_order : WalChecksumOrder
      checksum_valid : Bool
    } derive(Eq, 
    Debug    )

    WalPageHistory

    source
    pub(all) struct WalPageHistory {
      page_number : UInt64
      frame_indexes : Array[Int]
      valid_frame_indexes : Array[Int]
      committed_frame : Int?
      uncommitted_frame_indexes : Array[Int]
    } derive(Eq, 
    Debug    )

    Every occurrence of one database page in a WAL, including frames that do not become visible in the newest committed snapshot.

    WalPageHistory::has_uncommitted_change

    source
    fn WalPageHistory::has_uncommitted_change(self : WalPageHistory) -> Bool

    WalPageHistory::latest_valid_frame

    source
    fn WalPageHistory::latest_valid_frame(self : WalPageHistory) -> Int?

    WalPageHistory::occurrence_count

    source
    fn WalPageHistory::occurrence_count(self : WalPageHistory) -> Int

    WalPageHistory::valid_occurrence_count

    source
    fn WalPageHistory::valid_occurrence_count(self : WalPageHistory) -> Int

    WalTransaction

    source
    pub(all) struct WalTransaction {
      ordinal : Int
      first_frame : Int
      last_frame : Int
      frame_count : Int
      committed : Bool
      database_size_after_commit : UInt64?
    } derive(Eq, 
    Debug    )

    analyze_freelist

    source
    fn analyze_freelist(database : DatabaseImage) -> FreelistReport

    Walk every trunk and validate page references, loops, duplicates and the freelist count declared by the 100-byte database header.

    analyze_page_layout

    source
    fn analyze_page_layout(database : DatabaseImage, header : BtreePageHeader) -> PageLayout raise ParseError

    fn banner() -> String

    Return the project banner without performing file I/O.

    bytes_equal

    source
    fn bytes_equal(left : Bytes, right : Bytes) -> Bool

    bytes_hex

    source
    fn bytes_hex(data : Bytes) -> String

    check_database

    source
    fn check_database(data : Bytes, wal_data? : Bytes) -> IntegrityReport

    Run a read-only consistency pass. Parsing failures become ERROR diagnostics instead of escaping, which makes this function suitable for damaged files.

    description

    source
    let description : String

    Short description used by the CLI and package documentation.

    inspect_database

    source
    fn inspect_database(data : Bytes) -> DatabaseInspection raise ParseError

    join_payload

    source
    fn join_payload(local_bytes : Bytes, overflow : Bytes) -> Bytes

    local_payload_size

    source
    fn local_payload_size(page_type : PageType, payload_size : Int, usable_size : Int) -> Int raise ParseError

    Compute the local payload length using SQLite's spill formula.

    materialize_cell_payload

    source
    fn materialize_cell_payload(database : DatabaseImage, cell : BtreeCell) -> Bytes raise ParseError

    open_snapshot

    source
    fn open_snapshot(database : DatabaseImage, wal : WalFile) -> SnapshotView raise ParseError

    Construct the newest fully committed view. Invalid and uncommitted WAL frames never influence the resulting snapshot.

    parse_btree_cell

    source
    fn parse_btree_cell(database : DatabaseImage, header : BtreePageHeader, index : Int) -> BtreeCell raise ParseError

    parse_btree_page_cells

    source
    fn parse_btree_page_cells(database : DatabaseImage, header : BtreePageHeader) -> Array[BtreeCell] raise ParseError

    parse_btree_page_header

    source
    fn parse_btree_page_header(database : DatabaseImage, page_number : UInt64) -> BtreePageHeader raise ParseError

    parse_cell_record

    source
    fn parse_cell_record(database : DatabaseImage, cell : BtreeCell) -> SqliteRecord raise ParseError

    parse_database_header

    source
    fn parse_database_header(data : Bytes) -> DatabaseHeader raise ParseError

    Parse and strictly validate the SQLite database header.

    parse_freeblocks

    source
    fn parse_freeblocks(database : DatabaseImage, header : BtreePageHeader) -> Array[Freeblock] raise ParseError

    parse_freelist_trunk

    source
    fn parse_freelist_trunk(database : DatabaseImage, page_number : UInt64) -> FreelistTrunk raise ParseError

    Decode a single freelist trunk. Leaf pages are references only: their contents are intentionally not read because SQLite assigns them no format.

    parse_record

    source
    fn parse_record(payload : Bytes, encoding : TextEncoding) -> SqliteRecord raise ParseError

    Parse a complete SQLite record payload.

    parse_wal

    source
    fn parse_wal(data : Bytes) -> WalFile raise ParseError

    Parse a complete WAL, retaining invalid frames and attaching diagnostics so an analyst can distinguish structural damage from uncommitted tail data.

    parse_wal_header

    source
    fn parse_wal_header(data : Bytes) -> WalHeader raise ParseError

    read_overflow_chain

    source
    fn read_overflow_chain(database : DatabaseImage, first_page : UInt64, payload_bytes : Int) -> OverflowChain raise ParseError

    Follow an overflow chain and return exactly payload_bytes bytes.

    render_database_json

    source
    fn render_database_json(inspection : DatabaseInspection) -> String

    render_database_text

    source
    fn render_database_text(inspection : DatabaseInspection) -> String

    render_integrity_json

    source
    fn render_integrity_json(report : IntegrityReport) -> String

    render_integrity_text

    source
    fn render_integrity_text(report : IntegrityReport) -> String

    render_snapshot_json

    source
    fn render_snapshot_json(snapshot : SnapshotView) -> String raise ParseError

    render_snapshot_text

    source
    fn render_snapshot_text(snapshot : SnapshotView) -> String raise ParseError

    render_wal_json

    source
    fn render_wal_json(wal : WalFile) -> String

    render_wal_text

    source
    fn render_wal_text(wal : WalFile) -> String

    serial_type_length

    source
    fn serial_type_length(serial_type : UInt64) -> Int raise ParseError

    Return the number of body bytes represented by a serial type.

    summarize_btree

    source
    fn summarize_btree(traversal : BtreeTraversal) -> BtreeStatistics

    summarize_snapshot

    source
    fn summarize_snapshot(snapshot : SnapshotView) -> SnapshotStatistics raise ParseError

    traverse_btree

    source
    fn traverse_btree(database : DatabaseImage, root_page : UInt64, max_depth? : Int) -> BtreeTraversal raise ParseError

    validate_database_header

    source
    fn validate_database_header(header : DatabaseHeader, file_length : Int) -> Array[Diagnostic]

    Return non-fatal relationships that cannot be decided from one field alone.

    validate_page_layout

    source
    fn validate_page_layout(database : DatabaseImage, header : BtreePageHeader) -> Array[Diagnostic]

    Validate page-local layout facts without parsing cell payloads.

    validate_record

    source
    fn validate_record(record : SqliteRecord) -> Array[Diagnostic]

    version

    source
    let version : String

    Semantic version of the PageLens library.

    wal_checksum

    source
    fn wal_checksum(bytes : Bytes, order : WalChecksumOrder, initial_first? : UInt64, initial_second? : UInt64) -> WalChecksum raise ParseError

    Apply SQLite's rolling two-word WAL checksum. Initial values allow frame checksums to continue the state established by the header and prior frames.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io