Installation¶

Installing SQLSpec¶

SQLSpec can be installed using pip or uv. The base package includes support for SQLite and the core query processing infrastructure.

Using pip¶

pip install sqlspec

Using uv (recommended)¶

uv is a fast Python package installer and resolver written in Rust. It’s significantly faster than pip and provides better dependency resolution.

uv pip install sqlspec

Database-Specific Dependencies¶

SQLSpec uses optional dependencies to keep the base installation lightweight. Install only the drivers you need for your databases.

PostgreSQL¶

SQLSpec supports multiple PostgreSQL drivers. Choose the one that best fits your needs:

asyncpg (recommended for async)

Fast, async-native PostgreSQL driver with connection pooling.

pip install sqlspec[asyncpg]
# or
uv pip install sqlspec[asyncpg]

psycopg (sync and async)

Modern PostgreSQL adapter with both sync and async support.

pip install sqlspec[psycopg]
# or
uv pip install sqlspec[psycopg]

psqlpy (high-performance async)

High-performance async PostgreSQL driver built with Rust.

pip install sqlspec[psqlpy]
# or
uv pip install sqlspec[psqlpy]

SQLite¶

SQLite is included in Python’s standard library. For async support:

pip install sqlspec[aiosqlite]
# or
uv pip install sqlspec[aiosqlite]

DuckDB¶

DuckDB is an embedded analytical database perfect for OLAP workloads:

pip install sqlspec[duckdb]
# or
uv pip install sqlspec[duckdb]

MySQL¶

For async MySQL support:

pip install sqlspec[asyncmy]
# or
uv pip install sqlspec[asyncmy]

Oracle¶

For Oracle Database support (both sync and async):

pip install sqlspec[oracledb]
# or
uv pip install sqlspec[oracledb]

BigQuery¶

For Google BigQuery support:

pip install sqlspec[bigquery]
# or
uv pip install sqlspec[bigquery]

ADBC (Arrow Database Connectivity)¶

ADBC provides Arrow-native database access for multiple databases:

pip install sqlspec[adbc]
# or
uv pip install sqlspec[adbc]

Type-Safe Result Mapping¶

SQLSpec supports automatic mapping to typed models. Install the library you prefer:

Pydantic¶

pip install sqlspec[pydantic]
# or
uv pip install sqlspec[pydantic]

msgspec (recommended for performance)¶

pip install sqlspec[msgspec]
# or
uv pip install sqlspec[msgspec]

attrs¶

pip install sqlspec[attrs]
# or
uv pip install sqlspec[attrs]

Framework Integrations¶

Litestar¶

For Litestar web framework integration:

pip install sqlspec[litestar]
# or
uv pip install sqlspec[litestar]

FastAPI¶

For FastAPI integration:

pip install sqlspec[fastapi]
# or
uv pip install sqlspec[fastapi]

Flask¶

For Flask integration:

pip install sqlspec[flask]
# or
uv pip install sqlspec[flask]

Additional Features¶

SQL File Loading¶

For loading SQL queries from files (aiosql-style):

pip install sqlspec[aiosql]
# or
uv pip install sqlspec[aiosql]

Observability¶

For OpenTelemetry instrumentation:

pip install sqlspec[opentelemetry]
# or
uv pip install sqlspec[opentelemetry]

For Prometheus metrics:

pip install sqlspec[prometheus]
# or
uv pip install sqlspec[prometheus]

Data Export¶

For Pandas and Polars support:

pip install sqlspec[pandas]
# or
uv pip install sqlspec[polars]

For storage operations with fsspec or obstore:

pip install sqlspec[fsspec]
# or
uv pip install sqlspec[obstore]

Performance Optimizations¶

For maximum performance with Rust-based SQL parsing and msgspec:

pip install sqlspec[performance]
# or
uv pip install sqlspec[performance]

Installing Multiple Extras¶

You can install multiple optional dependencies at once:

pip install sqlspec[asyncpg,pydantic,litestar]
# or
uv pip install sqlspec[asyncpg,pydantic,litestar]

Development Installation¶

If you want to contribute to SQLSpec or run the examples:

git clone https://github.com/litestar-org/sqlspec.git
cd sqlspec
make install
# or
uv sync --all-extras --dev

Next Steps¶

Now that SQLSpec is installed, head over to the Quickstart to run your first query!