Metadata-Version: 2.4
Name: sqlspec
Version: 0.41.0
Summary: SQL Experiments in Python
Project-URL: Discord, https://discord.gg/litestar
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.10
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: Typing :: Typed
Requires-Python: <4.0,>=3.10
Requires-Dist: mypy-extensions
Requires-Dist: rich-click>=1.9.0
Requires-Dist: sqlglot>=30.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
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; extra == 'adk'
Provides-Extra: aioodbc
Requires-Dist: aioodbc; extra == 'aioodbc'
Provides-Extra: aiosqlite
Requires-Dist: aiosqlite; extra == 'aiosqlite'
Provides-Extra: alloydb
Requires-Dist: google-cloud-alloydb-connector; extra == 'alloydb'
Provides-Extra: asyncmy
Requires-Dist: asyncmy; 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-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: duckdb
Requires-Dist: duckdb; 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; extra == 'litestar'
Provides-Extra: msgspec
Requires-Dist: msgspec; extra == 'msgspec'
Provides-Extra: mypyc
Requires-Dist: sqlglot[c]>=30.0.0; extra == 'mypyc'
Provides-Extra: mysql-connector
Requires-Dist: mysql-connector-python; 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; 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: 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; 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: spanner
Requires-Dist: google-cloud-spanner; extra == 'spanner'
Provides-Extra: uuid
Requires-Dist: uuid-utils; extra == 'uuid'
Description-Content-Type: text/markdown

# SQLSpec

[![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-blue)](https://sqlspec.dev/)

SQLSpec is a SQL execution layer for Python. You write the SQL -- as strings, through a builder API, or loaded from files -- and SQLSpec handles connections, parameter binding, SQL injection prevention, dialect translation, and mapping results back to typed Python objects. It uses [sqlglot](https://github.com/tobymao/sqlglot) under the hood to parse, validate, and optimize your queries before they hit the database.

It works with PostgreSQL (asyncpg, psycopg, psqlpy), SQLite (sqlite3, aiosqlite), DuckDB, MySQL (asyncmy, mysql-connector, pymysql), Oracle (oracledb), CockroachDB, BigQuery, Spanner, and anything ADBC-compatible. Sync or async, same API. It also includes a built-in storage layer, native and bridged Arrow support for all drivers, and integrations for Litestar, FastAPI, Flask, and Starlette.

## Quick Start

```bash
pip install sqlspec
```

```python
from pydantic import BaseModel
from sqlspec import SQLSpec
from sqlspec.adapters.sqlite import SqliteConfig

class Greeting(BaseModel):
    message: str

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

with spec.provide_session(db) as session:
    greeting = session.select_one(
        "SELECT 'Hello, SQLSpec!' AS message",
        schema_type=Greeting,
    )
    print(greeting.message)  # Output: Hello, SQLSpec!
```

Write SQL, define a schema, get typed objects back. Or use the query builder -- they're interchangeable:

```python
from sqlspec import sql

# Builder API -- same driver, same result mapping
users = session.select(
    sql.select("id", "name", "email")
       .from_("users")
       .where("active = :active")
       .order_by("name")
       .limit(10),
    {"active": True},
    schema_type=User,
)
```

## Features

- **Connection pooling** -- sync and async adapters with a unified API across all supported drivers
- **Parameter binding and dialect translation** -- powered by sqlglot, with a fluent query builder and `.sql` file loader
- **Result mapping** -- map rows to Pydantic, msgspec, attrs, or dataclass models, or export to Arrow tables for pandas and Polars
- **Storage layer** -- read and write Arrow tables to local files, fsspec, or object stores
- **Framework integrations** -- Litestar plugin with DI, Starlette/FastAPI middleware, Flask extension
- **Observability** -- OpenTelemetry and Prometheus instrumentation, structured logging with correlation IDs
- **Event channels** -- LISTEN/NOTIFY, Oracle AQ, and a portable polling fallback
- **Migrations** -- schema versioning CLI built on Alembic

## Documentation

- [Getting Started](https://sqlspec.dev/getting_started/) -- installation, adapter selection, first steps
- [Usage Guides](https://sqlspec.dev/usage/) -- adapters, configuration, SQL file loader, and more
- [Examples Gallery](https://sqlspec.dev/examples/) -- working code for common patterns
- [API Reference](https://sqlspec.dev/reference/) -- full API docs
- [CLI Reference](https://sqlspec.dev/usage/cli.html) -- migration and management commands

## Playground

Want to try it without installing anything? The [interactive playground](https://sqlspec.dev/playground) runs SQLSpec in your browser with a sandboxed Python runtime.

## Reference Applications

- **[PostgreSQL + Vertex AI Demo](https://github.com/cofin/postgres-vertexai-demo)** -- Vector search with pgvector and real-time chat using Litestar and Google ADK. Shows connection pooling, migrations, type-safe result mapping, vector embeddings, and response caching.
- **[Oracle + Vertex AI Demo](https://github.com/cofin/oracledb-vertexai-demo)** -- Oracle 23ai vector search with semantic similarity using HNSW indexes. Demonstrates NumPy array conversion, large object handling, and real-time performance metrics.

## Contributing

Contributions are welcome -- whether that's bug reports, new adapter ideas, or pull requests. Take a look at the [contributor guide](https://sqlspec.dev/contributing/) to get started.

## License

MIT
