// Run performance benchmarks for TurboAPI. Use when testing performance, checking for regressions, or comparing against FastAPI.
| name | turbo-benchmark |
| description | Run performance benchmarks for TurboAPI. Use when testing performance, checking for regressions, or comparing against FastAPI. |
| disable-model-invocation | true |
| argument-hint | ["http|db|full|all"] |
$ARGUMENTS[0] — http (default), db, full, or alluv run --python 3.14t python zig/build_turbonet.py --install --releaseuv run --python 3.14t python benchmarks/turboapi_vs_fastapi.py --duration 10 --threads 4 --connections 100
docker run -d --name bench-pg -p 5432:5432 \
-e POSTGRES_USER=turbo -e POSTGRES_PASSWORD=turbo -e POSTGRES_DB=turbotest \
postgres:18-alpine
sleep 3
# Seed, then:
uv run --python 3.14t python benchmarks/db_bench_ci.py
docker stop bench-pg && docker rm bench-pg
# Needs Postgres running on :5432
uv run --python 3.14t python benchmarks/full_comparison.py
Tests: baseline, SELECT by PK, paginated list, full-text search, GROUP BY, and more.
wrk -t2 -c50 -d5s -s benchmarks/varying_ids.lua http://127.0.0.1:8000
| Endpoint | TurboAPI | FastAPI+SQLAlchemy | Speedup |
|---|---|---|---|
| Baseline (no DB) | ~133k req/s | ~9.8k req/s | 14x |
| SELECT by PK (cached) | ~133k req/s | ~2.6k req/s | 48x |
| Full-text search | ~110k req/s | ~2.5k req/s | 44x |
| GROUP BY sum/avg | ~129k req/s | ~1.4k req/s | 96x |
| Auth + Depends | ~116k req/s | — | — |
| Varying IDs (100 keys) | ~126k req/s | — | — |
CI fails if cached PK drops below 10k req/s. See .github/workflows/db-benchmark.yml.
Build the TurboAPI Zig native backend. Use when the turbonet extension needs to be recompiled, after changing Zig source files, or when seeing "Native core not available".
Scaffold Zig-native database routes using pg.zig + TurboPG. Use when adding database-backed CRUD endpoints, custom SQL queries (pgvector, JSONB, full-text search, JOINs, CTEs), or standalone TurboPG usage.
Use TurboPG for standalone Postgres queries. Use when writing database code outside of TurboAPI routes, running migrations, seeding data, or building scripts that talk to Postgres.
Scaffold a new TurboAPI route with handler, model, and tests. Use when adding a new API endpoint, creating a new route, or scaffolding CRUD for a resource.
Run TurboAPI tests. Use when running tests, checking for regressions, or verifying changes.