Metadata-Version: 2.5
Name: sqlspec
Version: 0.70.0
Summary: SQL Experiments in Python
Project-URL: Discord, https://discord.gg/litestar
Project-URL: Documentation, https://sqlspec.dev
Project-URL: Issue, https://github.com/litestar-org/sqlspec/issues/
Project-URL: Source, https://github.com/litestar-org/sqlspec
Author-email: Cody Fincher <cody@litestar.dev>
Maintainer-email: Litestar Developers <hello@litestar.dev>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.11
Requires-Dist: mypy-extensions
Requires-Dist: rich-click>=1.9.0
Requires-Dist: sqlglot>=30.13.0
Requires-Dist: typing-extensions
Provides-Extra: adbc
Requires-Dist: adbc-driver-manager; extra == 'adbc'
Requires-Dist: pyarrow; extra == 'adbc'
Provides-Extra: adk
Requires-Dist: google-adk>=2.10.0; extra == 'adk'
Provides-Extra: aiomysql
Requires-Dist: aiomysql; extra == 'aiomysql'
Provides-Extra: aiosqlite
Requires-Dist: aiosqlite; extra == 'aiosqlite'
Provides-Extra: alloydb
Requires-Dist: google-cloud-alloydb-connector; extra == 'alloydb'
Provides-Extra: arrow-odbc
Requires-Dist: arrow-odbc>=10.4; extra == 'arrow-odbc'
Requires-Dist: pyarrow; extra == 'arrow-odbc'
Provides-Extra: asyncmy
Requires-Dist: asyncmy>=0.2.13; extra == 'asyncmy'
Provides-Extra: asyncpg
Requires-Dist: asyncpg; extra == 'asyncpg'
Provides-Extra: attrs
Requires-Dist: attrs; extra == 'attrs'
Requires-Dist: cattrs; extra == 'attrs'
Provides-Extra: bigquery
Requires-Dist: google-cloud-bigquery; extra == 'bigquery'
Requires-Dist: google-cloud-bigquery-storage; extra == 'bigquery'
Requires-Dist: google-cloud-storage; extra == 'bigquery'
Provides-Extra: cloud-sql
Requires-Dist: cloud-sql-python-connector; extra == 'cloud-sql'
Provides-Extra: cockroachdb
Requires-Dist: asyncpg; extra == 'cockroachdb'
Requires-Dist: psycopg[binary,pool]; extra == 'cockroachdb'
Provides-Extra: db2
Requires-Dist: ibm-db>=3.3.0; extra == 'db2'
Provides-Extra: duckdb
Requires-Dist: duckdb; extra == 'duckdb'
Requires-Dist: pyarrow; extra == 'duckdb'
Requires-Dist: pytz; extra == 'duckdb'
Provides-Extra: fastapi
Requires-Dist: fastapi; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask; extra == 'flask'
Provides-Extra: fsspec
Requires-Dist: fsspec; extra == 'fsspec'
Provides-Extra: litestar
Requires-Dist: litestar>=2.23.0; extra == 'litestar'
Provides-Extra: msgspec
Requires-Dist: msgspec; extra == 'msgspec'
Provides-Extra: mssql-python
Requires-Dist: mssql-python>=1.13; extra == 'mssql-python'
Provides-Extra: mypyc
Requires-Dist: sqlglot[c]>=30.13.0; extra == 'mypyc'
Provides-Extra: mysql-connector
Requires-Dist: mysql-connector-python; (python_version < '3.12') and extra == 'mysql-connector'
Requires-Dist: mysql-connector-python<9.7.0; (python_version >= '3.12') and extra == 'mysql-connector'
Provides-Extra: nanoid
Requires-Dist: fastnanoid>=0.4.1; extra == 'nanoid'
Provides-Extra: obstore
Requires-Dist: obstore; extra == 'obstore'
Provides-Extra: opentelemetry
Requires-Dist: opentelemetry-instrumentation; extra == 'opentelemetry'
Provides-Extra: oracledb
Requires-Dist: oracledb>=3.4; extra == 'oracledb'
Provides-Extra: orjson
Requires-Dist: orjson; extra == 'orjson'
Provides-Extra: pandas
Requires-Dist: pandas; extra == 'pandas'
Requires-Dist: pyarrow; extra == 'pandas'
Provides-Extra: performance
Requires-Dist: librt>=0.10.0; extra == 'performance'
Requires-Dist: msgspec; extra == 'performance'
Provides-Extra: polars
Requires-Dist: polars; extra == 'polars'
Requires-Dist: pyarrow; extra == 'polars'
Provides-Extra: prometheus
Requires-Dist: prometheus-client; extra == 'prometheus'
Provides-Extra: psqlpy
Requires-Dist: psqlpy>=0.12.1; extra == 'psqlpy'
Provides-Extra: psycopg
Requires-Dist: psycopg[binary,pool]; extra == 'psycopg'
Provides-Extra: pydantic
Requires-Dist: pydantic; extra == 'pydantic'
Requires-Dist: pydantic-extra-types; extra == 'pydantic'
Provides-Extra: pymssql
Requires-Dist: pymssql; extra == 'pymssql'
Provides-Extra: pymysql
Requires-Dist: pymysql; extra == 'pymysql'
Provides-Extra: sanic
Requires-Dist: sanic; extra == 'sanic'
Provides-Extra: spanner
Requires-Dist: google-cloud-spanner>=3.64.0; extra == 'spanner'
Provides-Extra: sqlanywhere
Requires-Dist: sqlanydb>=1.0.14; extra == 'sqlanywhere'
Provides-Extra: starlette
Requires-Dist: starlette; extra == 'starlette'
Provides-Extra: sybase
Requires-Dist: pymssql; extra == 'sybase'
Provides-Extra: uuid
Requires-Dist: uuid-utils>=0.17.0; extra == 'uuid'
Description-Content-Type: text/markdown

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-inline-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="docs/assets/banner-inline-light.svg">
  <img alt="SQLSpec" src="docs/assets/banner-inline-light.svg" width="520">
</picture>

<p><strong>SQL-first database execution for Python across synchronous and asynchronous database adapters.</strong></p>

[![PyPI](https://img.shields.io/pypi/v/sqlspec)](https://pypi.org/project/sqlspec/)
[![Python](https://img.shields.io/pypi/pyversions/sqlspec)](https://pypi.org/project/sqlspec/)
[![License](https://img.shields.io/pypi/l/sqlspec)](https://github.com/litestar-org/sqlspec/blob/main/LICENSE)
[![Docs](https://img.shields.io/badge/docs-sqlspec.dev-1d4ed8)](https://sqlspec.dev/)

[Documentation](https://sqlspec.dev/) · [Quickstart](https://sqlspec.dev/learn/quickstart/) · [Databases](https://sqlspec.dev/databases/) · [Integrations](https://sqlspec.dev/integrations/) · [Playground](https://sqlspec.dev/playground/) · [API Reference](https://sqlspec.dev/reference/)

</div>

SQLSpec provides unified synchronous and asynchronous session APIs, SQLGlot-backed parameter compilation, statement caching, schema migrations, Apache Arrow streaming, and typed row mapping without an ORM. Write plain SQL strings, load named statements from `.sql` files, or compose dialect-portable queries programmatically while keeping full control over your SQL and underlying driver.

## Install

```bash
uv add sqlspec
```

Install optional driver, schema validation, or framework extras as needed:

```bash
uv add "sqlspec[asyncpg,msgspec,litestar]"
```

## Quickstart

```python
import msgspec

from sqlspec import SQLSpec
from sqlspec.adapters.sqlite import SqliteConfig


class User(msgspec.Struct, frozen=True, gc=False):
    id: int
    name: str


spec = SQLSpec()
config = spec.add_config(
    SqliteConfig(connection_config={"database": ":memory:"})
)

with spec.provide_session(config) as session:
    session.execute(
        """
        CREATE TABLE users (
            id INTEGER PRIMARY KEY,
            name TEXT
        )
        """
    )
    session.execute(
        """
        INSERT INTO users (name)
        VALUES (:name)
        """,
        name="Ada",
    )
    user = session.select_one(
        """
        SELECT id, name
        FROM users
        WHERE name = :name
        """,
        name="Ada",
        schema_type=User,
    )
```

## Capabilities

| Area | Overview |
| --- | --- |
| **Unified Execution** | Consistent `execute`, `select`, `select_one`, `select_one_or_none`, `select_value`, `execute_many`, `select_stream`, and transaction APIs across sync and `asyncio` drivers. |
| **Database Adapters** | PostgreSQL (`asyncpg`, `psycopg`, `psqlpy`), CockroachDB (`asyncpg`, `psycopg`), SQLite (`sqlite3`, `aiosqlite`), MySQL & MariaDB (`asyncmy`, `aiomysql`, `pymysql`, `mysql-connector-python`), Oracle (`oracledb`), SQL Server (`mssql-python`, `pymssql`), Sybase ASE (`pymssql`), SAP SQL Anywhere (`sqlanydb`), IBM Db2 (`ibm_db`), DuckDB (`duckdb`), BigQuery (`google-cloud-bigquery`), Cloud Spanner (`google-cloud-spanner`), ADBC (`adbc-driver-manager`), and Arrow ODBC (`arrow-odbc`). |
| **SQL Files & Builder** | Load named queries from `.sql` files via `SQLFileLoader` or build statements with `sql.select`, `sql.insert`, `sql.update`, `sql.delete`, and `sql.merge` with cached AST compilation. |
| **Typed Rows & Arrow** | Project rows into `msgspec.Struct`, `Pydantic`, `dataclass`, `TypedDict`, or `attrs` models, or stream `pyarrow`, `polars`, and `pandas` datasets across local, `fsspec`, and `obstore` backends. |
| **Integrations & Ops** | First-party plugins and stores for Litestar, Google ADK, FastAPI, Starlette, Flask, Sanic, Dishka, and Events, plus OpenTelemetry spans, Prometheus metrics, and CLI migrations. |

## Documentation

- **[Learn & Quickstart](https://sqlspec.dev/learn/quickstart/)** — progressive tutorials, query patterns, migrations, and production recipes.
- **[Database Adapters](https://sqlspec.dev/databases/)** — capability matrix, driver installation extras, pool configuration, and dialect notes.
- **[Framework & AI Integrations](https://sqlspec.dev/integrations/)** — Litestar, Google ADK, Events, FastAPI, Starlette, Flask, Sanic, and Dishka guides.
- **[Interactive Playground](https://sqlspec.dev/playground/)** — zero-install browser SQLite environment powered by Pyodide WebAssembly.
- **[API Reference](https://sqlspec.dev/reference/)** — class, configuration, driver, builder, and CLI reference documentation.

## Reference Applications

- **[postgres-vertexai-demo](https://github.com/cofin/postgres-vertexai-demo)** — PostgreSQL `pgvector` semantic search and real-time chat with Litestar and Google ADK.
- **[oracledb-vertexai-demo](https://github.com/cofin/oracledb-vertexai-demo)** — Oracle vector search with HNSW indexes, Litestar, and Google ADK.

## Contributing & License

Contributions are welcome; see the [Contributing Guide](https://sqlspec.dev/contributing/) for local setup and adapter guidelines. Released under the [MIT License](LICENSE).
