sqlspec 0.5.0__tar.gz → 0.38.0__tar.gz

{sqlspec-0.5.0 → sqlspec-0.38.0}/.gitignore

@@ -18,7 +18,9 @@ target/
 .idea/
 .vscode/
 .cursor/
-
+.zed/
+.cache
+.coverage*
 # files
 **/*.so
 **/*.sqlite
@@ -29,5 +31,33 @@ target/
 .python-version
 .ruff_cache
 /docs/_build/
+docs/autoapi/
 coverage.*
 setup.py
+tmp/
+*.log
+.tmp
+.tmp_mypyc
+TODO*
+.env
+tools/*.json
+benchmarks/
+.benchmark
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+*.duckdb
+.crush
+CRUSH.md
+CLAUDE.md
+AGENTS.md
+docs-build
+.envs/
+.claude/*
+.gh-cache
+.gemini/
+specs/
+.playwright-mcp
+.geminiignore
+uv.toml

{sqlspec-0.5.0 → sqlspec-0.38.0}/.pre-commit-config.yaml

@@ -2,12 +2,12 @@ default_language_version:
   python: "3"
 repos:
   - repo: https://github.com/compilerla/conventional-pre-commit
-    rev: v4.0.0
+    rev: v4.3.0
     hooks:
       - id: conventional-pre-commit
         stages: [commit-msg]
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: check-ast
       - id: check-case-conflict
@@ -17,19 +17,19 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.9.1"
+    rev: "v0.14.13"
     hooks:
       - id: ruff
         args: ["--fix"]
       - id: ruff-format
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.3.0
+    rev: v2.4.1
     hooks:
       - id: codespell
         additional_dependencies:
           - tomli
   - repo: https://github.com/python-formate/flake8-dunder-all
-    rev: v0.4.1
+    rev: v0.5.0
     hooks:
       - id: ensure-dunder-all
         exclude: "test*|tools"
@@ -40,9 +40,10 @@ repos:
       - id: slotscheck
         exclude: "docs|.github"
   - repo: https://github.com/sphinx-contrib/sphinx-lint
-    rev: "v1.0.0"
+    rev: "v1.0.2"
     hooks:
       - id: sphinx-lint
+        args: ["--jobs", "1"]
   - repo: local
     hooks:
       - id: pypi-readme

{sqlspec-0.5.0 → sqlspec-0.38.0}/CONTRIBUTING.rst

@@ -18,7 +18,7 @@ Workflow
 2. Clone your fork locally with git
 3. `Set up the environment <#setting-up-the-environment>`_
 4. Make your changes
-5. Run ``male lint`` to run linters and formatters. This step is optional and will be executed
+5. Run ``make lint`` to run linters and formatters. This step is optional and will be executed
    automatically by git before you make a commit, but you may want to run it manually in order to apply fixes
 6. Commit your changes to git
 7. Push the changes to your fork
@@ -36,7 +36,14 @@ Guidelines for writing code
 - All code should be fully `typed <https://peps.python.org/pep-0484/>`_. This is enforced via
   `mypy <https://mypy.readthedocs.io/en/stable/>`_.
 - All code should be tested. This is enforced via `pytest <https://docs.pytest.org/en/stable/>`_.
-- All code should be properly formatted. This is enforced via `black <https://black.readthedocs.io/en/stable/>`_ and `Ruff <https://beta.ruff.rs/docs/>`_.
+- All code should be properly formatted. This is enforced via `black <https://black.readthedocs.io/en/stable/>`_ and `Ruff <https://docs.astral.sh/ruff/>`_.
+
+Logging
+++++++++
+
+- Logger names must follow the ``sqlspec.<module>`` hierarchy.
+- Always obtain loggers via ``sqlspec.utils.logging.get_logger`` to ensure filters are attached.
+- Use static event names in structured logs and include context fields instead of dynamic message strings.
 
 Writing and running tests
 +++++++++++++++++++++++++
@@ -48,8 +55,8 @@ Project documentation
 
 The documentation is located in the ``/docs`` directory and is `ReST <https://docutils.sourceforge.io/rst.html>`_ and
 `Sphinx <https://www.sphinx-doc.org/en/master/>`_. If you're unfamiliar with any of those,
-`ReStructuredText primer <https://www.sphinx-doc.org/en/master/lib/usage/restructuredtext/basics.html>`_ and
-`Sphinx quickstart <https://www.sphinx-doc.org/en/master/lib/usage/quickstart.html>`_ are recommended reads.
+`ReStructuredText primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ and
+`Sphinx quickstart <https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_ are recommended reads.
 
 Running the docs locally
 ++++++++++++++++++++++++
@@ -60,7 +67,7 @@ Creating a new release
 ----------------------
 
 1. Increment the version in `pyproject.toml <https://github.com/litestar-org/sqlspec/blob/main/pyproject.toml>`_.
-    .. note:: The version should follow `semantic versioning <https://semver.org/>`_ and `PEP 440 <https://www.python.org/dev/peps/pep-0440/>`_.
+    .. note:: The version should follow `semantic versioning <https://semver.org/>`_ and `PEP 440 <https://peps.python.org/pep-0440/>`_.
 2. `Draft a new release <https://github.com/litestar-org/sqlspec/releases/new>`_ on GitHub
 
    * Use ``vMAJOR.MINOR.PATCH`` (e.g. ``v1.2.3``) as both the tag and release title

sqlspec-0.38.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Litestar Organization
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{sqlspec-0.5.0 → sqlspec-0.38.0}/Makefile

@@ -43,11 +43,23 @@ install-uv:                                         ## Install latest version of
 .PHONY: install
 install: destroy clean                              ## Install the project, dependencies, and pre-commit
 	@echo "${INFO} Starting fresh installation..."
-	@uv python pin 3.12 >/dev/null 2>&1
+	@uv python pin 3.10 >/dev/null 2>&1
 	@uv venv >/dev/null 2>&1
 	@uv sync --all-extras --dev
 	@echo "${OK} Installation complete! 🎉"
 
+.PHONY: install-compiled
+install-compiled: destroy clean                  ## Install with mypyc compilation for performance
+	@echo "${INFO} Starting fresh installation with mypyc compilation..."
+	@uv python pin 3.10 >/dev/null 2>&1
+	@uv venv >/dev/null 2>&1
+	@echo "${INFO} Installing in editable mode with mypyc compilation..."
+	@HATCH_BUILD_HOOKS_ENABLE=1 uv pip install -e .
+	@uv sync --all-extras --dev
+	@echo "${OK} Performance installation complete! 🚀"
+	@echo "${INFO} Verifying compilation..."
+	@find sqlspec -name "*.so" | wc -l | xargs -I {} echo "${OK} Compiled {} modules"
+
 .PHONY: destroy
 destroy:                                            ## Destroy the virtual environment
 	@echo "${INFO} Destroying virtual environment... 🗑️"
@@ -83,16 +95,57 @@ build:                                             ## Build the package
 	@uv build >/dev/null 2>&1
 	@echo "${OK} Package build complete"
 
+.PHONY: build-performance
+build-performance:                                 ## Build package with mypyc compilation
+	@echo "${INFO} Building package with mypyc compilation... 📦"
+	@HATCH_BUILD_HOOKS_ENABLE=1 uv build >/dev/null 2>&1
+	@echo "${OK} Performance package build complete 🚀"
+
+.PHONY: test-mypyc
+test-mypyc:                                        ## Test mypyc compilation on individual modules
+	@echo "${INFO} Testing mypyc compilation... 🔧"
+	@uv run mypyc --check-untyped-defs sqlspec/utils/statement_hashing.py
+	@uv run mypyc --check-untyped-defs sqlspec/utils/text.py
+	@uv run mypyc --check-untyped-defs sqlspec/utils/sync_tools.py
+	@uv run mypyc --check-untyped-defs sqlspec/statement/cache.py
+	@echo "${OK} Mypyc compilation tests passed ✨"
+
+
 .PHONY: release
 release:                                           ## Bump version and create release tag
 	@echo "${INFO} Preparing for release... 📦"
 	@make docs
 	@make clean
 	@make build
-	@uv lock --upgrade-package litestar-vite >/dev/null 2>&1
 	@uv run bump-my-version bump $(bump)
+	@uv lock --upgrade-package sqlspec >/dev/null 2>&1
 	@echo "${OK} Release complete 🎉"
 
+.PHONY: pre-release
+pre-release:                                       ## Start a pre-release: make pre-release version=0.33.0-alpha.1
+	@if [ -z "$(version)" ]; then \
+		echo "${ERROR} Usage: make pre-release version=X.Y.Z-alpha.N"; \
+		echo ""; \
+		echo "Pre-release workflow:"; \
+		echo "  1. Start alpha:     make pre-release version=0.33.0-alpha.1"; \
+		echo "  2. Next alpha:      make pre-release version=0.33.0-alpha.2"; \
+		echo "  3. Move to beta:    make pre-release version=0.33.0-beta.1"; \
+		echo "  4. Move to rc:      make pre-release version=0.33.0-rc.1"; \
+		echo "  5. Final release:   make release bump=patch (from rc) OR bump=minor (from stable)"; \
+		exit 1; \
+	fi
+	@echo "${INFO} Preparing pre-release $(version)... 🧪"
+	@make clean
+	@make build
+	@uv run bump-my-version bump --new-version $(version) pre
+	@uv lock --upgrade-package sqlspec >/dev/null 2>&1
+	@echo "${OK} Pre-release $(version) complete 🧪"
+	@echo ""
+	@echo "${INFO} Next steps:"
+	@echo "  1. Push: git push origin HEAD"
+	@echo "  2. Create a GitHub pre-release: gh release create v$(version) --prerelease --generate-notes --title 'v$(version)'"
+	@echo "  3. This will publish to PyPI with pre-release tags"
+
 # =============================================================================
 # Cleaning and Maintenance
 # =============================================================================
@@ -101,13 +154,15 @@ release:                                           ## Bump version and create re
 clean:                                              ## Cleanup temporary build artifacts
 	@echo "${INFO} Cleaning working directory... 🧹"
 	@rm -rf .pytest_cache .ruff_cache .hypothesis build/ -rf dist/ .eggs/ .coverage coverage.xml coverage.json htmlcov/ .pytest_cache tests/.pytest_cache tests/**/.pytest_cache .mypy_cache .unasyncd_cache/ .auto_pytabs_cache >/dev/null 2>&1
-	@find . -name '*.egg-info' -exec rm -rf {} + >/dev/null 2>&1
-	@find . -type f -name '*.egg' -exec rm -f {} + >/dev/null 2>&1
-	@find . -name '*.pyc' -exec rm -f {} + >/dev/null 2>&1
-	@find . -name '*.pyo' -exec rm -f {} + >/dev/null 2>&1
-	@find . -name '*~' -exec rm -f {} + >/dev/null 2>&1
-	@find . -name '__pycache__' -exec rm -rf {} + >/dev/null 2>&1
-	@find . -name '.ipynb_checkpoints' -exec rm -rf {} + >/dev/null 2>&1
+	@find . \( -path ./.venv -o -path ./.git \) -prune -o -name '*.egg-info' -exec rm -rf {} + >/dev/null 2>&1
+	@find . \( -path ./.venv -o -path ./.git \) -prune -o -type f -name '*.egg' -exec rm -f {} + >/dev/null 2>&1
+	@find . \( -path ./.venv -o -path ./.git \) -prune -o -name '*.pyc' -exec rm -f {} + >/dev/null 2>&1
+	@find . \( -path ./.venv -o -path ./.git \) -prune -o -name '*.pyo' -exec rm -f {} + >/dev/null 2>&1
+	@find . \( -path ./.venv -o -path ./.git \) -prune -o -name '*~' -exec rm -f {} + >/dev/null 2>&1
+	@find . \( -path ./.venv -o -path ./.git \) -prune -o -type d -name '__pycache__' -exec rm -rf {} + >/dev/null 2>&1
+	@find . \( -path ./.venv -o -path ./.git \) -prune -o -name '.ipynb_checkpoints' -exec rm -rf {} + >/dev/null 2>&1
+	@find . \( -path ./.venv -o -path ./.git \) -prune -o -name '*.so' -exec rm -f {} + >/dev/null 2>&1
+	@find . \( -path ./.venv -o -path ./.git \) -prune -o -name '*.c' -exec rm -f {} + >/dev/null 2>&1
 	@echo "${OK} Working directory cleaned"
 	$(MAKE) docs-clean
 
@@ -118,7 +173,7 @@ clean:                                              ## Cleanup temporary build a
 .PHONY: test
 test:                                               ## Run the tests
 	@echo "${INFO} Running test cases... 🧪"
-	@uv run pytest tests
+	@uv run pytest -n 2 --dist=loadgroup tests
 	@echo "${OK} Tests complete ✨"
 
 .PHONY: test-all
@@ -128,7 +183,7 @@ test-all: tests				                        ## Run all tests
 .PHONY: coverage
 coverage:                                           ## Run tests with coverage report
 	@echo "${INFO} Running tests with coverage... 📊"
-	@uv run pytest --cov -n auto --quiet
+	@uv run pytest --cov -n 2 --dist=loadgroup --quiet
 	@uv run coverage html >/dev/null 2>&1
 	@uv run coverage xml >/dev/null 2>&1
 	@echo "${OK} Coverage report generated ✨"
@@ -189,18 +244,18 @@ check-all: lint test-all coverage                  ## Run all checks (lint, test
 .PHONY: docs-clean
 docs-clean:                                        ## Clean documentation build
 	@echo "${INFO} Cleaning documentation build assets... 🧹"
-	@rm -rf docs/_build >/dev/null 2>&1
+	@rm -rf docs/_build
 	@echo "${OK} Documentation assets cleaned"
 
 .PHONY: docs-serve
 docs-serve: docs-clean                             ## Serve documentation locally
 	@echo "${INFO} Starting documentation server... 📚"
-	@uv run sphinx-autobuild docs docs/_build/ -j auto --watch sqlspec --watch docs --watch tests --watch CONTRIBUTING.rst --port 8002
+	@uv run sphinx-autobuild docs docs/_build/ -j 1 --watch sqlspec --watch docs --watch tests --watch CONTRIBUTING.rst --port 8002
 
 .PHONY: docs
 docs: docs-clean                                   ## Build documentation
 	@echo "${INFO} Building documentation... 📝"
-	@uv run sphinx-build -M html docs docs/_build/ -E -a -j auto -W --keep-going >/dev/null 2>&1
+	@PYTHONWARNINGS="ignore::FutureWarning" uv run sphinx-build -M html docs docs/_build/ -E -a -j 1 -W --keep-going
 	@echo "${OK} Documentation built successfully"
 
 .PHONY: docs-linkcheck
@@ -215,6 +270,49 @@ docs-linkcheck-full:                               ## Run full documentation lin
 	@uv run sphinx-build -b linkcheck ./docs ./docs/_build -D linkcheck_anchors=0
 	@echo "${OK} Full link check complete"
 
+# =============================================================================
+# Development Infrastructure
+# =============================================================================
+
+.PHONY: infra-up
+infra-up:                                              ## Start development infrastructure (databases, storage)
+	@echo "${INFO} Starting development infrastructure..."
+	@./tools/local-infra.sh up
+	@echo "${OK} Development infrastructure ready ✨"
+
+.PHONY: infra-down
+infra-down:                                            ## Stop development infrastructure
+	@echo "${INFO} Stopping development infrastructure..."
+	@./tools/local-infra.sh down --quiet
+	@echo "${OK} Development infrastructure stopped"
+
+.PHONY: infra-status
+infra-status:                                          ## Show development infrastructure status
+	@./tools/local-infra.sh status
+
+.PHONY: infra-cleanup
+infra-cleanup:                                         ## Clean up development infrastructure
+	@echo "${WARN} This will remove all development containers and volumes"
+	@./tools/local-infra.sh cleanup
+
+.PHONY: infra-postgres
+infra-postgres:                                        ## Start only PostgreSQL
+	@echo "${INFO} Starting PostgreSQL..."
+	@./tools/local-infra.sh up postgres --quiet
+	@echo "${OK} PostgreSQL ready on port 5433"
+
+.PHONY: infra-oracle
+infra-oracle:                                          ## Start only Oracle
+	@echo "${INFO} Starting Oracle..."
+	@./tools/local-infra.sh up oracle --quiet
+	@echo "${OK} Oracle ready on port 1522"
+
+.PHONY: infra-mysql
+infra-mysql:                                           ## Start only MySQL
+	@echo "${INFO} Starting MySQL..."
+	@./tools/local-infra.sh up mysql --quiet
+	@echo "${OK} MySQL ready on port 3307"
+
 # =============================================================================
 # End of Makefile
 # =============================================================================

sqlspec-0.38.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: sqlspec
+Version: 0.38.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
+Requires-Python: <4.0,>=3.10
+Requires-Dist: mypy-extensions
+Requires-Dist: rich-click>=1.9.0
+Requires-Dist: sqlglot>=19.9.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
+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'
+Requires-Dist: sqlglot[rs]; 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
+
+**Type-safe SQL execution layer for Python.**
+
+SQLSpec handles database connectivity and result mapping so you can focus on SQL. Write raw queries when you need precision, use the builder API when you need composability, or load SQL from files when you need organization. Every statement passes through a [sqlglot](https://github.com/tobymao/sqlglot)-powered AST pipeline for validation, dialect conversion, and optimization before execution. Export results as Python objects, Arrow tables, Polars or pandas DataFrames.
+
+It's not an ORM. It's the connectivity and processing layer between your application and your database that provides the right abstraction for each situation without dictating how you write SQL.
+
+## Status
+
+SQLSpec is currently in active development. The public API may change. Follow the [docs](https://sqlspec.dev/) and changelog for updates.
+
+## What You Get
+
+**Connection Management**
+
+- Connection pooling with configurable size, timeout, and lifecycle hooks
+- Sync and async support with a unified API surface
+- Adapters for PostgreSQL (psycopg, asyncpg, psqlpy), SQLite (sqlite3, aiosqlite), DuckDB, MySQL (asyncmy, mysql-connector, pymysql), Oracle, BigQuery, and ADBC-compatible databases
+
+**Query Execution**
+
+- Raw SQL strings with automatic parameter binding and dialect translation
+- SQL AST parsing via sqlglot for validation, optimization, and dialect conversion
+- Builder API for programmatic query construction without string concatenation
+- SQL file loading to keep queries organized alongside your code (named SQL queries)
+- Statement stacks for batching multiple operations with transaction control
+
+**Result Handling**
+
+- Type-safe result mapping to Pydantic, msgspec, attrs, or dataclasses
+- Apache Arrow export for zero-copy integration with pandas, Polars, and analytical tools
+- Result iteration, single-row fetch, or bulk retrieval based on your use case
+
+**Framework Integration**
+
+- Litestar plugin with dependency injection for connections, sessions, and pools
+- Starlette/FastAPI middleware for automatic transaction management
+- Flask extension with sync/async portal support
+
+**Production Features**
+
+- SQL validation and caching via sqlglot AST parsing
+- OpenTelemetry and Prometheus instrumentation hooks
+- Database event channels with native LISTEN/NOTIFY, Oracle AQ, and a portable queue fallback
+- Structured logging with correlation ID support
+- Migration CLI for schema versioning
+
+## Quick Start
+
+### Install
+
+```bash
+pip install "sqlspec"
+```
+
+### Run your first query
+
+```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!
+```
+
+That's it. Write SQL, define a schema, get typed objects back. Connection pooling, parameter binding, and result mapping are handled automatically.
+
+See the [Getting Started guide](https://sqlspec.dev/getting_started/) for installation variants, adapter selection, and advanced result mapping options.
+
+## Documentation
+
+- [Getting Started](https://sqlspec.dev/getting_started/)
+- [Usage Guides](https://sqlspec.dev/usage/)
+- [Examples Gallery](https://sqlspec.dev/examples/)
+- [API Reference](https://sqlspec.dev/reference/)
+- [CLI Reference](https://sqlspec.dev/usage/cli.html)
+
+## 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 (CLOB) handling, and real-time performance metrics.
+
+See the [usage docs](https://sqlspec.dev/usage/) for detailed guides on adapters, configuration patterns, and features like the [SQL file loader](https://sqlspec.dev/usage/loader.html).
+
+## Built With
+
+- **[sqlglot](https://github.com/tobymao/sqlglot)** - SQL parser, transpiler, and optimizer powering SQLSpec's AST pipeline
+
+## Contributing
+
+Contributions, issue reports, and adapter ideas are welcome. Review the
+[contributor guide](https://sqlspec.dev/contributing/) and follow the project
+coding standards before opening a pull request.
+
+## License
+
+SQLSpec is distributed under the MIT License.

sqlspec-0.38.0/README.md

@@ -0,0 +1,109 @@
+# SQLSpec
+
+**Type-safe SQL execution layer for Python.**
+
+SQLSpec handles database connectivity and result mapping so you can focus on SQL. Write raw queries when you need precision, use the builder API when you need composability, or load SQL from files when you need organization. Every statement passes through a [sqlglot](https://github.com/tobymao/sqlglot)-powered AST pipeline for validation, dialect conversion, and optimization before execution. Export results as Python objects, Arrow tables, Polars or pandas DataFrames.
+
+It's not an ORM. It's the connectivity and processing layer between your application and your database that provides the right abstraction for each situation without dictating how you write SQL.
+
+## Status
+
+SQLSpec is currently in active development. The public API may change. Follow the [docs](https://sqlspec.dev/) and changelog for updates.
+
+## What You Get
+
+**Connection Management**
+
+- Connection pooling with configurable size, timeout, and lifecycle hooks
+- Sync and async support with a unified API surface
+- Adapters for PostgreSQL (psycopg, asyncpg, psqlpy), SQLite (sqlite3, aiosqlite), DuckDB, MySQL (asyncmy, mysql-connector, pymysql), Oracle, BigQuery, and ADBC-compatible databases
+
+**Query Execution**
+
+- Raw SQL strings with automatic parameter binding and dialect translation
+- SQL AST parsing via sqlglot for validation, optimization, and dialect conversion
+- Builder API for programmatic query construction without string concatenation
+- SQL file loading to keep queries organized alongside your code (named SQL queries)
+- Statement stacks for batching multiple operations with transaction control
+
+**Result Handling**
+
+- Type-safe result mapping to Pydantic, msgspec, attrs, or dataclasses
+- Apache Arrow export for zero-copy integration with pandas, Polars, and analytical tools
+- Result iteration, single-row fetch, or bulk retrieval based on your use case
+
+**Framework Integration**
+
+- Litestar plugin with dependency injection for connections, sessions, and pools
+- Starlette/FastAPI middleware for automatic transaction management
+- Flask extension with sync/async portal support
+
+**Production Features**
+
+- SQL validation and caching via sqlglot AST parsing
+- OpenTelemetry and Prometheus instrumentation hooks
+- Database event channels with native LISTEN/NOTIFY, Oracle AQ, and a portable queue fallback
+- Structured logging with correlation ID support
+- Migration CLI for schema versioning
+
+## Quick Start
+
+### Install
+
+```bash
+pip install "sqlspec"
+```
+
+### Run your first query
+
+```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!
+```
+
+That's it. Write SQL, define a schema, get typed objects back. Connection pooling, parameter binding, and result mapping are handled automatically.
+
+See the [Getting Started guide](https://sqlspec.dev/getting_started/) for installation variants, adapter selection, and advanced result mapping options.
+
+## Documentation
+
+- [Getting Started](https://sqlspec.dev/getting_started/)
+- [Usage Guides](https://sqlspec.dev/usage/)
+- [Examples Gallery](https://sqlspec.dev/examples/)
+- [API Reference](https://sqlspec.dev/reference/)
+- [CLI Reference](https://sqlspec.dev/usage/cli.html)
+
+## 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 (CLOB) handling, and real-time performance metrics.
+
+See the [usage docs](https://sqlspec.dev/usage/) for detailed guides on adapters, configuration patterns, and features like the [SQL file loader](https://sqlspec.dev/usage/loader.html).
+
+## Built With
+
+- **[sqlglot](https://github.com/tobymao/sqlglot)** - SQL parser, transpiler, and optimizer powering SQLSpec's AST pipeline
+
+## Contributing
+
+Contributions, issue reports, and adapter ideas are welcome. Review the
+[contributor guide](https://sqlspec.dev/contributing/) and follow the project
+coding standards before opening a pull request.
+
+## License
+
+SQLSpec is distributed under the MIT License.