SQLSpec Example Library¶

The example catalog now mirrors the way teams explore SQLSpec. Each snippet focuses on a single idea, keeps inline commentary to a minimum, and favors lightweight backends (SQLite, AioSQLite, DuckDB) so the code can run anywhere.

Quick Start¶

Run a smoke sweep that exercises the SQLite/AioSQLite/DuckDB demos:

make examples-smoke

Each file exposes a main() helper so you can execute it directly:

uv run python docs/examples/frameworks/litestar/aiosqlite_app.py

Folder Guide¶

Frameworks¶

FastAPI / Starlette / Flask demos¶
File	Description
`frameworks/fastapi/aiosqlite_app.py`	FastAPI app using the AioSQLite adapter with dependency-injected sessions.
`frameworks/fastapi/sqlite_app.py`	Synchronous FastAPI handlers powered by the SQLite adapter.
`frameworks/starlette/aiosqlite_app.py`	Starlette routes that read from an AioSQLite-backed dataset.
`frameworks/flask/sqlite_app.py`	Flask blueprint that serves data via the synchronous SQLite adapter.

Adapters¶

Connection-focused snippets¶
File	Adapter	Highlights
`adapters/adbc_postgres_ingest.py`	ADBC (Postgres)	Rich Click CLI that exports SELECT queries to Parquet/Arrow and loads them via the storage bridge.
`adapters/asyncpg/connect_pool.py`	AsyncPG	Minimal pool configuration plus a version probe.
`adapters/psycopg/connect_sync.py`	Psycopg (sync)	Blocking workflow familiar to scripts and management commands.
`adapters/oracledb/connect_async.py`	oracledb (async)	Async driver setup with timestamp sampling.

Patterns¶

Common tasks¶
File	Scenario
`patterns/builder/select_and_insert.py`	Fluent SQL builder usage with a tiny articles dataset.
`patterns/migrations/runner_basic.py`	Sync migration commands pointed at bundled demo migrations.
`patterns/migrations/files/0001_create_articles.py`	Python migration file consumed by the runner example.
`patterns/multi_tenant/router.py`	Routing requests to dedicated SQLite configs per tenant slug.
`patterns/configs/multi_adapter_registry.py`	Register multiple adapters on a single SQLSpec registry.
`patterns/stacks/query_stack_example.py`	Immutable StatementStack workflow executed against SQLite and AioSQLite drivers.

Arrow¶

Arrow-powered exports¶
File	Scenario
`arrow/arrow_basic_usage.py`	`select_to_arrow()` walkthrough covering native Arrow, pandas, polars, and Parquet exports.

Loaders¶

SQL file loading¶
File	Description
`loaders/sql_files.py`	Shows how `SQLFileLoader` binds named queries in `queries/users.sql` and executes them with SQLite.

Extensions¶

Adapter Development Kit¶
File	Description
`extensions/adk/basic_aiosqlite.py`	Create an ADK session, append events, and fetch the transcript using SQLSpec’s AioSQLite store.
`extensions/adk/litestar_aiosqlite.py`	Wire `SQLSpecSessionService` into Litestar and expose a simple `/sessions` endpoint.

Shared Utilities¶

shared/configs.py and shared/data.py provide registry builders and seed data so the individual examples can stay short and consistent.