perf: SQLite3 comparison benchmark and report

[poyrazK]

This PR adds a dedicated benchmarking suite to compare cloudSQL against SQLite3.

Key Additions:

• ****: Head-to-head tests for point inserts and sequential scans.
• ****: Detailed report of results on Apple M3 Pro.
• CMake Integration: Automated SQLite3 dependency management via FetchContent.

Results (Release Mode):

• Point Inserts: cloudSQL is 7.1x behind SQLite (due to SQL parsing and object allocations).
• Sequential Scans: cloudSQL is 6.5x behind SQLite (small gap, validating binary format efficiency).

This establishes a clear industry-standard baseline for our future optimization efforts.

Summary by CodeRabbit

Release Notes

• New Features

  • Added performance benchmarking suite to compare insert and scan operations against SQLite3.

• Documentation

  • Added performance comparison guide with benchmark results and optimization roadmap.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This change introduces a SQLite3 benchmarking framework to compare cloudSQL's performance against SQLite. It includes CMake integration for fetching and building SQLite3, a new benchmark file with four comparison tests (point inserts and sequential scans), and documentation detailing the performance comparison results and identified optimization opportunities.

Changes

Cohort / File(s)	Summary
Build System Integration CMakeLists.txt	Added FetchContent logic to download and build SQLite3 as a static library with performance-oriented compile definitions (SQLITE_THREADSAFE=0, SQLITE_OMIT_LOAD_EXTENSION). Created new benchmark executable sqlite_comparison_bench linking against cloudSQL engine, Google Benchmark, and SQLite3.
Benchmark Implementation benchmarks/sqlite_comparison_bench.cpp	Implemented four microbenchmarks comparing cloudSQL and SQLite3 across insert and scan operations. Created context helpers (CloudSQLContext, SQLiteContext) to initialize respective systems with matching table schemas and measure performance metrics.
Performance Documentation docs/performance/SQLITE_COMPARISON.md	Added benchmark results showing comparative performance metrics for point inserts and sequential scans, including architectural analysis of performance gaps and planned optimizations (prepared statement caching, memory arena allocation, vectorized execution).

Sequence Diagram(s)

sequenceDiagram
    participant Benchmark as Google Benchmark
    participant CloudCtx as CloudSQLContext
    participant CloudEng as CloudSQL Engine
    participant SQLiteCtx as SQLiteContext
    participant SQLite as SQLite3

    Note over Benchmark: Insert Benchmark
    Benchmark->>CloudCtx: Initialize (create table)
    CloudCtx->>CloudEng: Create storage, catalog, managers
    CloudEng-->>CloudCtx: Ready
    
    loop Each iteration
        Benchmark->>CloudEng: Parse & execute INSERT
        CloudEng-->>Benchmark: Row inserted
    end

    Benchmark->>SQLiteCtx: Initialize (create table)
    SQLiteCtx->>SQLite: Open DB, apply PRAGMAs
    SQLite-->>SQLiteCtx: Ready

    loop Each iteration
        Benchmark->>SQLite: Step prepared INSERT
        SQLite-->>Benchmark: Row inserted
    end

Loading

sequenceDiagram
    participant Benchmark as Google Benchmark
    participant CloudCtx as CloudSQLContext
    participant CloudEng as CloudSQL Engine
    participant QueryExec as QueryExecutor
    participant SQLiteCtx as SQLiteContext
    participant SQLite as SQLite3

    Note over Benchmark: Scan Benchmark
    Benchmark->>CloudCtx: Initialize & populate
    CloudCtx->>CloudEng: Insert num_rows via executor
    CloudEng-->>CloudCtx: Population complete

    loop Each iteration
        Benchmark->>QueryExec: Execute prepared SELECT \\*
        QueryExec->>CloudEng: Scan table
        CloudEng-->>QueryExec: Return rows
        QueryExec-->>Benchmark: All rows processed
    end

    Benchmark->>SQLiteCtx: Initialize & populate
    SQLiteCtx->>SQLite: Bulk INSERT in transaction
    SQLite-->>SQLiteCtx: Population complete

    loop Each iteration
        Benchmark->>SQLite: Step through SELECT \\* results
        SQLite-->>Benchmark: Each row
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• perf: add benchmarking infrastructure and performance baseline report #16: Introduces foundational benchmarking infrastructure and build system updates that this PR extends with SQLite comparison benchmarks and new benchmark executable.

Poem

🐰 A hare built a benchmark so fine,
SQLite and cloudSQL align,
With inserts and scans put to test,
We'll see which system performs best!
Performance gaps now crystal-line! 🚀

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 55.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'perf: SQLite3 comparison benchmark and report' directly and clearly summarizes the main changes: adding benchmarks and a performance report comparing cloudSQL against SQLite3.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/sqlite-comparison

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}