The file is a strip of pages — 4 KB page reads and OS block alignment

The DB file is a strip of identical fixed-size pages — every read/write is one whole page because the disk and OS work in pages.

Previously

We need an ordered structure. Before we can build it, we have to know what the storage substrate looks like — and it's not a sea of bytes.

Scene 02

The file is a strip of pages

Watch
Try it
Predict
Capture

What to watch for

The file isn't a soup of bytes — it's a strip of identical pages. Watch the read-head sweep across them; each landing is one disk I/O. Then an INSERT picks exactly ONE page as rowid 42's home.

Implementation

Highlighted lines are the ones running in the diagram right now.

Pager.read_one_row

fetch the WHOLE page; slice the row out in RAM

1def read_one_row(file, page_size, page_no, row_offset):
2    # disk addresses are page numbers, not byte offsets
3    offset = (page_no - 1) * page_size
4    page_buf = read(file, offset, page_size)  # one I/O = one page
5 
6    # row extraction happens entirely in RAM
7    row = extract_row_from_page_buffer(page_buf, row_offset)
8    return row

Kernel.effective_io

bytes the kernel actually moves for one page read

1def effective_io(row_size, page_size, os_block=4096):
2    if page_size < os_block:
3        # sub-block page: kernel still drags a whole 4 KB block,
4        # SQLite throws the rest away
5        sub = os_block // page_size
6        return os_block  # waste = (sub - 1) * page_size per read
7 
8    if page_size == os_block:
9        # aligned: one page = one block = one disk transfer
10        return os_block
11 
12    # supra-block page: one logical read spans many blocks
13    blocks = page_size // os_block
14    return blocks * os_block  # bandwidth = blocks * 4 KB per row

Sources

Where this sits in Build a B-tree storage engine (SQLite-style)

Scene 02 of 11, in the Anatomy act — Pages, the tree of pages, and how a search descends.. The DB file is a strip of identical fixed-size pages — every read/write is one whole page because the disk and OS work in pages.

Up next. We have a strip of fixed-size pages, but no order yet. The next scene links pages into a tree so we can find any row in a few page reads instead of N.

All 11 scenes in Build a B-tree storage engine (SQLite-style) · Every curriculum

Built with Arqly

Every scene in Build a B-tree storage engine (SQLite-style) builds on the one before it.All 11 Build a B-tree storage engine (SQLite-style) scenes