feat: initial release

11-config × 10M sweep + ORM-vs-raw benchmark harness for SQLite write
throughput. Includes long-form ARTICLE.md with industry comparison
across 20+ references (Expensify, Litestream, DHH, Forward Email, etc.)
and our actual benchmark data (10M + 50M rows) under results/sample/.

Findings: ORM ceiling ~3,800 r/s across all 11 configs. Raw executemany
hits 87,893 r/s at 10M (23.8x speedup) and 65,742 r/s at 50M (17.9x).
PRAGMA tuning irrelevant for ORM workloads. Chunk size scales p99 66x
linearly with no throughput improvement. Zero errors with QueuePool.

Author: Tanay10x

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  smoke:
+    name: Smoke test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Import check
+        run: |
+          python -c "from sqlite_bench import scale_benchmark, before_after, paths, engine, schema, configs, data_generator, monitor, results, report"
+
+      - name: Smoke test before_after (10K rows)
+        run: |
+          python -m sqlite_bench.before_after --scales 10K --mode both --output-dir /tmp/smoke
+
+      - name: Smoke test scale_benchmark (3 presets × 5K)
+        run: |
+          python -m sqlite_bench.scale_benchmark --scales 5K --configs presets --output-dir /tmp/smoke_scale
+
+      - name: Verify results JSON
+        run: |
+          python -c "import json; d=json.load(open('/tmp/smoke/results.json')); assert len(d['results'])>=2"
+          python -c "import json; d=json.load(open('/tmp/smoke_scale/results.json')); assert len(d['results'])>=3"

.gitignore

@@ -0,0 +1,37 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+.env
+.env.local
+
+# Benchmark artifacts
+*.db
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite-shm
+*.sqlite-wal
+results/scale/
+results/before_after/
+results/*.log
+!results/sample/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Build
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

ARTICLE.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Issues and PRs welcome.
+
+## Particularly interested in
+
+- **Results on other hardware tiers** — cloud VMs, ARM (M1, Graviton), spinning disk, eMMC. Open an issue with your `results.json` + system info per [docs/reproducing.md](docs/reproducing.md).
+- **Other ORMs** — Peewee, Tortoise, SQLModel. Same benchmark harness, different `paths.py` implementation. PR welcome.
+- **Other databases** — DuckDB, Postgres (libpq vs psycopg vs SQLAlchemy). Natural extension.
+- **Bug fixes** — particularly around result aggregation, percentile math, and the edge case where checkpoints fall inside a single chunk.
+
+## Setup
+
+```bash
+git clone https://github.com/TanayK07/sqlite-orm-bench.git
+cd sqlite-orm-bench
+pip install -e ".[dev]"
+```
+
+## Code style
+
+- Black with line-length 100
+- Ruff for linting
+- Python 3.11+ syntax (`str | None`, not `Optional[str]`)
+- PEP 604 unions everywhere
+
+```bash
+black sqlite_bench/
+ruff check sqlite_bench/
+```
+
+## Running tests
+
+```bash
+# Fast smoke test
+python -m sqlite_bench.before_after --scales 10K --mode both
+
+# Full validation (≈ 5 hours, don't do this on CI)
+python -m sqlite_bench.scale_benchmark --scales 3M,5M,10M --configs all
+```
+
+## PR checklist
+
+- [ ] Smoke test passes locally
+- [ ] No new wall-finishing or project-specific references
+- [ ] Type hints use PEP 604 syntax
+- [ ] No `print()` outside of CLI entry points (use the existing checkpoint printing helpers)
+- [ ] If adding a new config: include rationale in PR description

CONTRIBUTING.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tanay Kedia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LICENSE

@@ -0,0 +1,186 @@
+# sqlite-orm-bench
+
+> **SQLite handles 88K writes/sec. Your ORM caps at 3,800. PRAGMA tuning won't save you.**
+
+A benchmark harness that quantifies the **ORM tax** on SQLite write performance at 10M–50M row scale. Run an 11-configuration sweep, or compare SQLAlchemy ORM vs raw `executemany` head-to-head. Reproduce our results on your hardware.
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Read the article](https://img.shields.io/badge/article-ARTICLE.md-green.svg)](ARTICLE.md)
+
+---
+
+## Headline Results
+
+| Path | 10M rows | 50M rows | p99 |
+|------|----------|----------|-----|
+| SQLAlchemy ORM | **3,696 r/s** (45 min) | **3,682 r/s** (3.8 hrs) | 1,492 ms |
+| Raw `executemany` | **87,893 r/s** (1.9 min) | **65,742 r/s** (12.7 min) | 478 ms |
+| **Speedup** | **23.8×** | **17.9×** | **3.1×** |
+
+Across **11 PRAGMA configurations** (sync modes, cache sizes, pool sizes, mmap, chunk sizes), ORM throughput varied only **26%** (3,045–3,821 r/s). The database isn't your bottleneck — your ORM is.
+
+Zero errors across 110 million rows. Every config. Every scale.
+
+→ Full writeup: [**ARTICLE.md**](ARTICLE.md)
+
+---
+
+## What This Benchmarks
+
+Two complementary harnesses:
+
+1. **`scale_benchmark`** — Sweeps 11 SQLite configurations against a fixed scale (default 10M rows). Tests whether PRAGMA tuning matters.
+2. **`before_after`** — Compares SQLAlchemy ORM vs raw `sqlite3.executemany` at multiple scales (default 10M and 50M). Measures the ORM overhead directly.
+
+Both:
+- Stream rows via a generator (constant memory regardless of scale)
+- Capture checkpoint metrics (throughput, p50/p95/p99, RSS, DB size, errors)
+- Save results as JSON with `--resume` support (50M ORM runs take 3+ hours; crashes happen)
+- Generate HTML reports with Chart.js
+
+---
+
+## Quickstart
+
+```bash
+# Clone + install
+git clone https://github.com/TanayK07/sqlite-orm-bench.git
+cd sqlite-orm-bench
+pip install -e .
+
+# Smoke test (≈ 5 seconds)
+python -m sqlite_bench.before_after --scales 10K --mode both
+
+# ORM vs Raw at 10M (≈ 50 minutes)
+python -m sqlite_bench.before_after --scales 10M --mode both
+
+# Full 11-config sweep × 10M (≈ 5.5 hours)
+python -m sqlite_bench.scale_benchmark --scales 3M,5M,10M --configs all
+
+# Generate HTML report
+python -m sqlite_bench.report results/scale/results.json
+```
+
+---
+
+## Repo Layout
+
+```
+sqlite-orm-bench/
+├── README.md                        # This file (hook + quickstart)
+├── ARTICLE.md                       # Long-form writeup with industry comparison
+├── LICENSE                          # MIT
+├── pyproject.toml                   # Package metadata
+├── sqlite_bench/                    # Python package
+│   ├── schema.py                    # Generic benchmark table
+│   ├── configs.py                   # PRAGMA presets + parametric sweeps
+│   ├── engine.py                    # SQLAlchemy engine factories
+│   ├── data_generator.py            # Streaming row generator
+│   ├── paths.py                     # ORM + raw write paths
+│   ├── monitor.py                   # RSS / CPU / DB-size sampler
+│   ├── results.py                   # Percentiles + CSV/summary writers
+│   ├── scale_benchmark.py           # CLI: config sweep
+│   ├── before_after.py              # CLI: ORM vs raw comparison
+│   └── report.py                    # HTML report generator
+├── docs/
+│   ├── methodology.md               # Test design + decisions
+│   ├── findings.md                  # Detailed analysis
+│   └── reproducing.md               # Hardware-by-hardware notes
+├── examples/
+│   └── hybrid_repository.py         # Production pattern: ORM for CRUD, raw for bulk
+└── results/sample/                  # Our actual run data (10M + 50M)
+    ├── scale_results.json
+    ├── scale_report.html
+    ├── before_after_results.json
+    └── before_after_report.html
+```
+
+---
+
+## Configurations Tested
+
+11 configs cover the obvious axes any production engineer might tune:
+
+| Group | Configs | What changes |
+|-------|---------|--------------|
+| **Presets** | `baseline`, `optimized`, `aggressive` | Realistic deployment profiles |
+| **Chunk size sweep** | `chunk_1000` → `chunk_50000` | Transaction batching impact |
+| **Pool size sweep** | `pool_3`, `pool_5`, `pool_8` | Connection-pool contention |
+
+Each config defines: `chunk_size`, `synchronous`, `cache_size`, `pool_size`, `max_overflow`, `mmap_size`, `busy_timeout`, `journal_mode`, `temp_store`.
+
+See [`sqlite_bench/configs.py`](sqlite_bench/configs.py) for defaults and how to add your own.
+
+---
+
+## Five Findings
+
+1. **The ORM is the bottleneck, not SQLite.** 11 configs × 10M rows. Throughput varies only 26%. Raw `executemany` on the same hardware hits 87K r/s — 23× faster.
+2. **PRAGMA tuning is irrelevant for ORM workloads.** `sync=OFF` doesn't help. 256MB mmap doesn't help. 8-connection pool doesn't help. The ORM consumes the CPU budget before I/O matters.
+3. **Chunk size controls latency, not throughput.** p99 scales **66×** across chunk sizes (313 ms → 20,508 ms). Throughput drops only 20%. Use 1K–5K chunks for predictable latency.
+4. **Baseline config wins.** `sync=NORMAL`, default cache, `pool=5`, `chunk=5000`. No exotic PRAGMAs needed. Matches production consensus across 7 referenced sources.
+5. **QueuePool eliminates concurrency errors.** Zero `database is locked` errors across 110M rows. QueuePool serializes writes at the application level, matching the single-writer architecture every production SQLite deployment converges on.
+
+→ Detailed analysis with industry comparison: [**ARTICLE.md**](ARTICLE.md)
+
+---
+
+## When to Bypass Your ORM
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Single-row CRUD | Use the ORM |
+| < 1K rows per transaction | Use the ORM |
+| 10K–1M bulk load | Consider raw SQL (5–10× faster) |
+| > 1M bulk load | Use raw SQL (18–24× faster) |
+| Sustained > 1K writes/sec | Use raw SQL (ORM caps at 3.8K) |
+
+The hybrid pattern (ORM for normal CRUD, raw `executemany` for bulk paths) is in [`examples/hybrid_repository.py`](examples/hybrid_repository.py).
+
+---
+
+## Reproducing Our Numbers
+
+Hardware we measured on:
+
+| Component | Spec |
+|-----------|------|
+| CPU | 8-core / 16-thread |
+| RAM | 23.2 GB DDR |
+| Storage | Samsung 990 EVO Plus 1TB NVMe |
+| OS | Linux 6.8.0 |
+| Python | 3.11 |
+| SQLAlchemy | 2.0 |
+
+Your absolute numbers will differ on EBS, spinning disk, or eMMC — but the **relative findings** (ORM-to-raw ratio, config irrelevance, chunk-size effect on latency) should hold.
+
+See [`docs/reproducing.md`](docs/reproducing.md) for storage-specific guidance.
+
+---
+
+## Acknowledgements
+
+This benchmark draws on prior work from:
+
+- [Expensify](https://use.expensify.com/blog/scaling-sqlite-to-4m-qps-on-a-single-server) — SQLite at 4M QPS
+- [Ben Johnson / Litestream](https://fly.io/blog/all-in-on-sqlite-litestream/) — WAL semantics in production
+- [Stephen Margheim / Fractaled Mind](https://fractaledmind.com/2024/04/15/sqlite-on-rails-the-how-and-why-of-optimal-performance/) — Rails 8 IMMEDIATE transactions
+- [Evan Schwartz](https://emschwartz.me/psa-your-sqlite-connection-pool-might-be-ruining-your-write-performance/) — Connection-pool write contention
+- [Shivek Khurana](https://shivekkhurana.com/blog/sqlite-in-production/) — WAL vs DELETE benchmarks
+- [Forward Email](https://forwardemail.net/en/blog/docs/sqlite-performance-optimization-pragma-chacha20-production-guide) — PRAGMA deep dive
+
+Full references in [ARTICLE.md](ARTICLE.md).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contributing
+
+Issues and PRs welcome. Particularly interested in:
+- Results on other hardware tiers (cloud, ARM, spinning disk)
+- Other ORMs (Peewee, Tortoise, SQLModel) — same benchmark harness, different paths
+- Other databases (DuckDB, Postgres) — would be a natural extension

README.md

@@ -0,0 +1,34 @@
+# Detailed Findings
+
+See [ARTICLE.md](../ARTICLE.md) for the full long-form writeup with industry comparison.
+
+## Quick Reference
+
+### Five Key Conclusions
+
+1. **The ORM Is the Bottleneck, Not SQLite** — 11 configs × 10M rows, never exceeded 3,821 r/s. Raw `executemany` hits 87,893 r/s.
+2. **PRAGMA Tuning Is Irrelevant for ORM Workloads** — `sync=OFF`, 64MB cache, 256MB mmap, 8-conn pool: all within 26%.
+3. **Chunk Size Controls Latency, Not Throughput** — p99 scales 66× (313ms → 20,508ms). Throughput drops only 20%.
+4. **Baseline Config Wins** — `sync=NORMAL`, default cache, `pool=5`, `chunk=5000`. No exotic PRAGMAs needed.
+5. **Raw SQL Degrades Gracefully at Scale** — 87,893 r/s @ 10M → 65,742 r/s @ 50M (25% drop). I/O scaling curve.
+6. **QueuePool Eliminates Concurrency Errors** — Zero errors across 110M rows.
+
+### When to Bypass Your ORM
+
+| Scenario | ORM | Raw SQL |
+|----------|-----|---------|
+| < 1K rows | Good enough | Premature optimization |
+| 10K–1M rows | 2–5 min/M | 7 sec/M |
+| 1M–100M rows | 45 min/10M | 1.9 min/10M |
+| Sustained > 1K r/s | Ceiling at 3.8K | Headroom to 88K |
+| Upsert-heavy | Slow | 18× faster |
+
+### Surprising Findings From the Literature
+
+- **`temp_store=MEMORY` can be slower than disk** (Forward Email)
+- **SQLite's default exponential backoff is bad** — uniform 1ms is better (Margheim)
+- **WAL is slower than DELETE at low concurrency** — 43% slower at 1 worker (Khurana)
+- **50-connection pool is 23× slower than single writer** (Schwartz)
+- **Node.js version matters more than SQLite config** — v24 57% slower than v20 (Forward Email)
+
+See [ARTICLE.md](../ARTICLE.md) sections "Surprising Findings From the Literature" and "How Our Numbers Compare to the Industry".