Hello, I'm Maneshwar. I'm working on git-lrc: a Git hook for Checking AI generated code.
AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.
git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.
Yesterday we dissected the physical structure of pages and cells. We now climb one level higher in abstraction.
We’ve understood:
- What a page looks like
- How cells are laid out
- How payload spills into overflow
- How B+-trees grow and shrink
Today we shift focus from data layout to control structures.
This is where the tree module becomes a living system inside SQLite.
The Tree Module Functionalities
The tree module is the layer that stands between the VM and the pager. It organizes every SQL table and every SQL index into B+-trees and B-trees.
At this level:
- Each table is one B+-tree
- Each index is one B-tree
- Each tree spans one or more database pages
The VM does not manipulate pages directly. It asks the tree module to store variable-length records, retrieve records, delete records and traverse records
The tree module guarantees:
- Self-balancing on insert and delete
- Automatic reuse of freed space
- Logarithmic lookup, insert, and delete — O(log m)
- Amortized O(1) bidirectional traversal
All of that behavior rests on a set of control data structures.
Btree Structure
When the VM calls sqlite3BtreeOpen, a Btree object is created.
This object is the VM’s handle to a database file.
Everything the VM needs to know about the database connection at the tree layer is summarized inside this structure.
Conceptually:
Btree= the VM’s connection-level view of the database file.
Important member variables include:
-
db→ pointer to the SQLite library connection -
ppBtree→ pointer to aBtSharedobject -
inTrans→ indicates current transaction state - Additional control variables
The inTrans field determines the state of the Btree:
-
TRANS_NONE→ no transaction -
TRANS_READ→ read transaction active -
TRANS_WRITE→ write transaction active
This maps directly to pager locking states we studied earlier.
The key insight here is separation of responsibility:
-
Btree→ per-connection state -
BtShared→ per-database-file state
BtShared Structure
While Btree represents a connection, BtShared represents the shared state of the database file itself at the tree layer.
Multiple Btree objects may point to a single BtShared when shared cache mode is enabled.
Key members:
-
pPager→ pointer to Pager object -
pCursor→ list of open cursors -
pageSize→ page size in bytes -
nTransaction→ number of open transactions -
inTransaction→ transaction state -
pSchema→ schema cache -
pPage1→ in-memory copy of Page 1 -
mutex→ synchronization primitive
This structure binds together:
Tree layer ↔ Pager layer ↔ Schema layer
Notice how deeply layered SQLite is:
- Pager handles disk and journaling
- BtShared coordinates tree access
- Btree exposes safe operations to VM
When shared caching is disabled, each Btree has its own BtShared.
When enabled, multiple connections share the same BtShared.
That design allows memory savings and cross-connection page reuse.
MemPage Structure
Now we zoom even further down into the per-page control structure.
Earlier, when we studied the page cache, we saw that the pager allocates extra space below each cached page image.
That space is not for the pager. It is for the tree module.
When a page is brought into the cache:
- The pager initializes that extra space to zeros
- The tree module overlays it with a
MemPageobject
Here is how that fits together:
MemPage is the in-memory decoded representation of a raw database page.
Instead of re-parsing the byte layout every time, SQLite decodes page metadata once and stores it inside this structure.
Important fields include:
-
aData→ pointer to raw page bytes -
pParent→ pointer to parent MemPage - Cell counts
- Free space offsets
- Flags indicating page type
The pParent pointer is particularly powerful.
It allows upward traversal in the tree. This is how:
- Insert splits propagate upward
- Delete merges walk toward the root
- Search-next climbs parents
Without pParent, upward traversal would require re-searching from the root.
MemPage is where structural logic meets raw bytes.
The Architectural Flow
Let’s zoom out and connect all pieces:
VM
→ calls Btree interface
→ Btree uses BtShared
→ BtShared uses Pager
→ Pager returns cached page
→ Tree module decodes into MemPage
→ MemPage manages cells and structure
Every SQL operation flows through this chain.
The elegance lies in strict separation:
- Pager knows nothing about keys
- Tree module knows nothing about journaling
- VM knows nothing about page layout
Each layer does one thing well.
Tomorrow, we examine the final critical component:
BtCursor structure
This is the object that actually walks the tree.
It’s what makes SELECT, INSERT, DELETE, and ordered scans possible at runtime.
👉 Check out: git-lrc
Any feedback or contributors are welcome! It’s online, source-available, and ready for anyone to use.
⭐ Star it on GitHub:
HexmosTech
/
git-lrc
Free, Unlimited AI Code Reviews That Run on Commit
git-lrc
Free, Unlimited AI Code Reviews That Run on Commit
AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.
git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.
See It In Action
See git-lrc catch serious security issues such as leaked credentials, expensive cloud operations, and sensitive material in log statements
git-lrc-intro-60s.mp4
Why
- 🤖 AI agents silently break things. Code removed. Logic changed. Edge cases gone. You won't notice until production.
- 🔍 Catch it before it ships. AI-powered inline comments show you exactly what changed and what looks wrong.
- 🔁 Build a habit, ship better code. Regular review → fewer bugs → more robust code → better results in your team.
- 🔗 Why git? Git is universal. Every editor, every IDE, every AI…
Top comments (0)