SQLite WAL Proof of Concept

Standalone Java proof-of-concept that reads a SQLite WAL file, parses frame headers, validates checksums, and decodes b-tree leaf pages to extract row-level data.

Built as part of the GSoC 2026 proposal for a Debezium SQLite Source Connector.

What it demonstrates

1. WAL Header Parsing — Validates magic number (0x377f0682), format version, page size, and salt values
2. Frame Reading — Sequential frame parsing with salt validation and cumulative checksum verification
3. Commit Boundary Detection — Buffers frames until commit_size > 0, processes complete transactions atomically
4. B-Tree Page Decoding — Decodes leaf table pages (0x0D): cell pointer arrays, varint fields, serial type codes, record payloads

Build and run

# Build
mvn package

# Run against a WAL file
java -cp target/classes io.debezium.sqlite.poc.Main /path/to/database.db-wal

# Run tests (requires sqlite3 on PATH)
mvn test

Docker

docker build -t sqlite-wal-poc .
docker run -v /path/to/db:/data sqlite-wal-poc /data/database.db-wal

Project structure

src/main/java/io/debezium/sqlite/poc/
  WalReader.java        - WAL file parser (header + frames)
  WalHeader.java        - 32-byte WAL header
  WalFrame.java         - 24-byte frame header + page image
  BTreePageDecoder.java - B-tree leaf page decoder
  RowData.java          - Decoded row data container
  VarInt.java           - SQLite varint encoding utilities
  Main.java             - CLI entry point