examples

Example

A minimal end-to-end run of sqlinsite profile.

1. Create a test database

sqlite3 fruit.db "CREATE TABLE Fruit(id INTEGER PRIMARY KEY, name TEXT);
                  INSERT INTO Fruit(name) VALUES ('apple'),('banana'),('cherry');"

2. Profile it

sqlinsite profile \
  --test-file fruit.db \
  --statements examples/statements.json \
  --out-file fruit-trace.csv \
  --timing relative

A summary is printed to stderr:

SQLinsite summary:
  session "WarmCacheReads": 3 rows (3 read, 0 write)
  session "ColdSelect": 2 rows (2 read, 0 write)
  session "Write": 4 rows (2 read, 2 write)
  total: 9 rows (7 read, 2 write) across 3 session(s)

3. Read the trace

fruit-trace.csv (abridged; timings vary per machine):

Session Name,Statement Index,Time Start,Time End,Page Number,Read or Write
WarmCacheReads,0,121000,122416,1,Read
WarmCacheReads,0,175333,176333,1,Read
WarmCacheReads,0,179375,180416,2,Read
Write,0,537958,539625,1,Write
Write,0,540083,541333,2,Write

• Each row is one page access at the VFS layer for the main database file.
• Statement Index is the 0-based position of the statement within its session; cross-reference it against examples/statements.json to see the SQL.
• Page Number is byte_offset / page_size + 1; page 1 is the database header. It matches SQLite's numbering and sqlinsite map's pageNumber.
• Time Start/Time End are nanoseconds. With --timing relative they are rebased to the start of the run; without it they are raw monotonic ticks. Use Time End - Time Start for the per-access cost.

Notes:

• Statements in the same session share a warm page cache. To profile a statement against a cold cache, put it in its own session.
• Writes run in place — the example's INSERT permanently adds a row to fruit.db.