{"id":28414166,"url":"https://github.com/litestar-org/sqlspec","last_synced_at":"2026-04-01T22:47:20.826Z","repository":{"id":272633096,"uuid":"773112251","full_name":"litestar-org/sqlspec","owner":"litestar-org","description":"A Query Mapper for Python","archived":false,"fork":false,"pushed_at":"2026-03-26T16:53:49.000Z","size":21097,"stargazers_count":67,"open_issues_count":9,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-03-26T18:44:02.587Z","etag":null,"topics":["adbc","aiosqlite","asyncmy","asyncpg","bigquery","duckdb","litestar","msgspec","mysql","oracle","oracledb","postgresql","psqlpy","psycopg","pydantic","sql","sqlite","sqlserver"],"latest_commit_sha":null,"homepage":"https://sqlspec.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/litestar-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["litestar-org"],"open_collective":"litestar","polar":"litestar-org"}},"created_at":"2024-03-16T19:28:14.000Z","updated_at":"2026-03-22T02:47:22.000Z","dependencies_parsed_at":"2026-01-16T19:00:33.111Z","dependency_job_id":null,"html_url":"https://github.com/litestar-org/sqlspec","commit_stats":null,"previous_names":["litestar-org/sqlspec"],"tags_count":66,"template":false,"template_full_name":null,"purl":"pkg:github/litestar-org/sqlspec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Fsqlspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Fsqlspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Fsqlspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Fsqlspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/litestar-org","download_url":"https://codeload.github.com/litestar-org/sqlspec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Fsqlspec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adbc","aiosqlite","asyncmy","asyncpg","bigquery","duckdb","litestar","msgspec","mysql","oracle","oracledb","postgresql","psqlpy","psycopg","pydantic","sql","sqlite","sqlserver"],"created_at":"2025-06-03T07:14:57.978Z","updated_at":"2026-04-01T22:47:20.819Z","avatar_url":"https://github.com/litestar-org.png","language":"Python","readme":"# SQLSpec\n\n[![PyPI](https://img.shields.io/pypi/v/sqlspec)](https://pypi.org/project/sqlspec/)\n[![Python](https://img.shields.io/pypi/pyversions/sqlspec)](https://pypi.org/project/sqlspec/)\n[![License](https://img.shields.io/pypi/l/sqlspec)](https://github.com/litestar-org/sqlspec/blob/main/LICENSE)\n[![Docs](https://img.shields.io/badge/docs-sqlspec.dev-blue)](https://sqlspec.dev/)\n\nSQLSpec 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.\n\nIt 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.\n\n## Quick Start\n\n```bash\npip install sqlspec\n```\n\n```python\nfrom pydantic import BaseModel\nfrom sqlspec import SQLSpec\nfrom sqlspec.adapters.sqlite import SqliteConfig\n\nclass Greeting(BaseModel):\n    message: str\n\nspec = SQLSpec()\ndb = spec.add_config(SqliteConfig(connection_config={\"database\": \":memory:\"}))\n\nwith spec.provide_session(db) as session:\n    greeting = session.select_one(\n        \"SELECT 'Hello, SQLSpec!' AS message\",\n        schema_type=Greeting,\n    )\n    print(greeting.message)  # Output: Hello, SQLSpec!\n```\n\nWrite SQL, define a schema, get typed objects back. Or use the query builder -- they're interchangeable:\n\n```python\nfrom sqlspec import sql\n\n# Builder API -- same driver, same result mapping\nusers = session.select(\n    sql.select(\"id\", \"name\", \"email\")\n       .from_(\"users\")\n       .where(\"active = :active\")\n       .order_by(\"name\")\n       .limit(10),\n    {\"active\": True},\n    schema_type=User,\n)\n```\n\n## Features\n\n- **Connection pooling** -- sync and async adapters with a unified API across all supported drivers\n- **Parameter binding and dialect translation** -- powered by sqlglot, with a fluent query builder and `.sql` file loader\n- **Result mapping** -- map rows to Pydantic, msgspec, attrs, or dataclass models, or export to Arrow tables for pandas and Polars\n- **Storage layer** -- read and write Arrow tables to local files, fsspec, or object stores\n- **Framework integrations** -- Litestar plugin with DI, Starlette/FastAPI middleware, Flask extension\n- **Observability** -- OpenTelemetry and Prometheus instrumentation, structured logging with correlation IDs\n- **Event channels** -- LISTEN/NOTIFY, Oracle AQ, and a portable polling fallback\n- **Migrations** -- schema versioning CLI built on Alembic\n\n## Documentation\n\n- [Getting Started](https://sqlspec.dev/getting_started/) -- installation, adapter selection, first steps\n- [Usage Guides](https://sqlspec.dev/usage/) -- adapters, configuration, SQL file loader, and more\n- [Examples Gallery](https://sqlspec.dev/examples/) -- working code for common patterns\n- [API Reference](https://sqlspec.dev/reference/) -- full API docs\n- [CLI Reference](https://sqlspec.dev/usage/cli.html) -- migration and management commands\n\n## Playground\n\nWant to try it without installing anything? The [interactive playground](https://sqlspec.dev/playground) runs SQLSpec in your browser with a sandboxed Python runtime.\n\n## Reference Applications\n\n- **[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.\n- **[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.\n\n## Contributing\n\nContributions 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.\n\n## License\n\nMIT\n","funding_links":["https://github.com/sponsors/litestar-org","https://opencollective.com/litestar","https://polar.sh/litestar-org"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flitestar-org%2Fsqlspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flitestar-org%2Fsqlspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flitestar-org%2Fsqlspec/lists"}