sqlspec 0.29.0__tar.gz → 0.30.0__tar.gz

{sqlspec-0.29.0 → sqlspec-0.30.0}/.gitignore

@@ -19,6 +19,7 @@ target/
 .vscode/
 .cursor/
 .zed/
+.cache
 .coverage*
 # files
 **/*.so

{sqlspec-0.29.0 → sqlspec-0.30.0}/.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.14.3"
+    rev: "v0.14.5"
     hooks:
       - id: ruff
         args: ["--fix"]
@@ -43,6 +43,7 @@ repos:
     rev: "v1.0.1"
     hooks:
       - id: sphinx-lint
+        args: ["--jobs", "1"]
   - repo: local
     hooks:
       - id: pypi-readme

{sqlspec-0.29.0 → sqlspec-0.30.0}/AGENTS.md

@@ -185,6 +185,25 @@ SQLSpec is a type-safe SQL query mapper designed for minimal abstraction between
 - **Single-Pass Processing**: Parse once → transform once → validate once - SQL object is single source of truth
 - **Abstract Methods with Concrete Implementations**: Protocol defines abstract methods, base classes provide concrete sync/async implementations
 
+### Query Stack Implementation Guidelines
+
+- **Builder Discipline**
+    - `StatementStack` and `StackOperation` are immutable (`__slots__`, tuple storage). Every push helper returns a new stack; never mutate `_operations` in place.
+    - Validate inputs at push time (non-empty SQL, execute_many payloads, reject nested stacks) so drivers can assume well-formed operations.
+- **Adapter Responsibilities**
+    - Add a single capability gate per adapter (e.g., Oracle pipeline version check, `psycopg.capabilities.has_pipeline()`), return `super().execute_stack()` immediately when unsupported.
+    - Preserve `StackResult.result` by building SQL/Arrow results via `create_sql_result()` / `create_arrow_result()` instead of copying row data.
+    - Honor manual toggles via `driver_features={"stack_native_disabled": True}` and document the behavior in the adapter guide.
+- **Telemetry + Tracing**
+    - Always wrap adapter overrides with `StackExecutionObserver(self, stack, continue_on_error, native_pipeline=bool)`.
+    - Do **not** emit duplicate metrics; the observer already increments `stack.execute.*`, logs `stack.execute.start/complete/failed`, and publishes the `sqlspec.stack.execute` span.
+- **Error Handling**
+    - Wrap driver exceptions in `StackExecutionError` with `operation_index`, summarized SQL (`describe_stack_statement()`), adapter name, and execution mode.
+    - Continue-on-error stacks append `StackResult.from_error()` and keep executing. Fail-fast stacks roll back (if they started the transaction) before re-raising the wrapped error.
+- **Testing Expectations**
+    - Add integration tests under `tests/integration/test_adapters/<adapter>/test_driver.py::test_*statement_stack*` that cover native path, sequential fallback, and continue-on-error.
+    - Guard base behavior (empty stacks, large stacks, transaction boundaries) via `tests/integration/test_stack_edge_cases.py`.
+
 ### Driver Parameter Profile Registry
 
 - All adapter parameter defaults live in `DriverParameterProfile` entries inside `sqlspec/core/parameters.py`.
@@ -507,6 +526,23 @@ When processing user input that may be incomplete or malformed, use a two-tier a
 
 **Implementation Pattern:**
 
+## Recent edit: Configuration examples (2025-11-04)
+
+- Updated docs/examples/usage examples: consolidated example filenames to
+  docs/examples/usage/test_configuration_*.py and ensured the documentation
+  references match the renamed examples.
+- Added an explicit :lines: range and a :dedent: directive to the
+  literalinclude for test_configuration_23.py so Sphinx renders the snippet
+  with correct indentation.
+- Built the Sphinx documentation (make docs) and verified HTML output was
+  generated successfully. Two minor warnings were reported (dedent and a
+  missing stylesheet copy) but they did not prevent the build.
+- Updated project TODOs to reflect completed steps.
+
+This summary documents the small documentation and example maintenance
+performed on the configuration usage guide and can be expanded into a
+longer changelog entry if desired.
+
 ```python
 def parse_user_input(content: str, source: str) -> "dict[str, Result]":
     """Parse user input with two-tier error handling.
@@ -2025,6 +2061,14 @@ class GoodDriverFeatures(TypedDict):
 
 ### Compliance Table
 
+### Change log: configuration examples
+
+- Renamed documentation example references to use docs/examples/usage/test_configuration_*.py
+- Added explicit :lines: ranges and :dedent: directive for the literalinclude at the top of docs/usage/configuration.rst
+- Rebuilt documentation to verify the changes (make docs). Build completed with 2 warnings about dedent and a missing stylesheet; output HTML written to docs/_build/html
+
+### Compliance Table
+
 Current state of all adapters (as of type-cleanup branch):
 
 | Adapter    | TypedDict | Auto-Detect | enable_ Prefix | Defaults | Grade      | Notes                                    |

sqlspec-0.30.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: sqlspec
+Version: 0.30.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
+Requires-Dist: sqlglot>=19.9.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; extra == 'adk'
+Provides-Extra: aioodbc
+Requires-Dist: aioodbc; extra == 'aioodbc'
+Provides-Extra: aiosql
+Requires-Dist: aiosql; extra == 'aiosql'
+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: cli
+Requires-Dist: rich-click; extra == 'cli'
+Provides-Extra: cloud-sql
+Requires-Dist: cloud-sql-python-connector; extra == 'cloud-sql'
+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: 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), 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 (aiosql-style)
+- 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
+- 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 = sql.add_config(SqliteConfig(pool_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.30.0/README.md

@@ -0,0 +1,108 @@
+# 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), 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 (aiosql-style)
+- 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
+- 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 = sql.add_config(SqliteConfig(pool_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.29.0 → sqlspec-0.30.0}/pyproject.toml

@@ -7,7 +7,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.10, <4.0"
-version = "0.29.0"
+version = "0.30.0"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -179,13 +179,21 @@ include = [
   "sqlspec/utils/fixtures.py",            # File fixture loading
   "sqlspec/utils/data_transformation.py", # Data transformation utilities
 
+  # === OBSERVABILITY ===
+  "sqlspec/observability/_config.py",
+  "sqlspec/observability/_diagnostics.py",
+  "sqlspec/observability/_dispatcher.py",
+  "sqlspec/observability/_observer.py",
+  "sqlspec/observability/_runtime.py",
+  "sqlspec/observability/_spans.py",
+
   # === STORAGE LAYER ===
-  "sqlspec/storage/_utils.py",
-  "sqlspec/storage/registry.py",
-  "sqlspec/storage/backends/base.py",
-  "sqlspec/storage/backends/obstore.py",
-  "sqlspec/storage/backends/fsspec.py",
-  "sqlspec/storage/backends/local.py",
+  # "sqlspec/storage/_utils.py",
+  # "sqlspec/storage/registry.py",
+  # "sqlspec/storage/backends/base.py",
+  # "sqlspec/storage/backends/obstore.py",
+  # "sqlspec/storage/backends/fsspec.py",
+  # "sqlspec/storage/backends/local.py",
 ]
 mypy-args = [
   "--ignore-missing-imports",
@@ -209,7 +217,7 @@ opt_level = "3"   # Maximum optimization (0-3)
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.29.0"
+current_version = "0.30.0"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"
@@ -322,7 +330,8 @@ markers = [
   "pymysql: marks tests using pymysql",
   "psqlpy: marks tests using psqlpy",
 ]
-testpaths = ["tests"]
+python_files = ["test_*.py", "quickstart_*.py", "usage_*.py"]
+testpaths = ["tests", "docs/examples/quickstart", "docs/examples/usage"]
 
 [tool.mypy]
 exclude = ["tmp/", ".tmp/", ".bugs/"]
@@ -490,10 +499,11 @@ known-first-party = ["sqlspec", "tests"]
 split-on-trailing-comma = false
 
 [tool.ruff.lint.per-file-ignores]
-"docs/**/*.*" = ["S", "B", "DTZ", "A", "TC", "ERA", "D", "RET", "PLW0127"]
+"docs/**/*.*" = ["S", "B", "DTZ", "A", "TC", "ERA", "D", "RET", "PLW0127", "PLR2004"]
 "docs/examples/**" = ["T201"]
 "sqlspec/builder/mixins/**/*.*" = ["SLF001"]
 "sqlspec/extensions/adk/converters.py" = ["S403"]
+"sqlspec/migrations/utils.py" = ["S404"]
 "tests/**/*.*" = [
   "A",
   "ARG",

sqlspec-0.30.0/specs/guides/docs_examples_alignment.md

@@ -0,0 +1,33 @@
+# Docs & Example Alignment
+
+## Why
+
+- Keep literalincluded snippets in `docs/` authoritative and executable.
+- Reduce drift between prose and runnable code by treating documentation examples as pytest cases.
+
+## Workflow
+
+1. Update the Python example under `docs/examples/...` first and keep it function-based (`def test_*`).
+2. Refresh the corresponding ``literalinclude`` in the `.rst` file:
+   - Adjust `:lines:` and `:dedent:` ranges so the rendered snippet only shows the relevant part of the test.
+   - Mention any helper imports or context (e.g., `contextlib.suppress`) in nearby prose.
+3. Re-run the targeted example tests locally and record failures that require external services (Postgres, etc.) so reviewers know what still needs coverage. Use helpers like `SQLSPEC_QUICKSTART_PG_*` to keep DSNs out of docs snippets.
+4. When SQLite pooling is involved, use `tempfile.NamedTemporaryFile` (or `tmp_path`) to guarantee isolation. Delete any prior tables at the top of the example to keep re-runs deterministic.
+5. Reference this checklist in PR descriptions whenever docs/examples are touched.
+
+## Testing Command Examples
+
+```bash
+uv run pytest docs/examples/quickstart docs/examples/usage -q
+```
+
+- `docs/examples/quickstart/conftest.py` sets `SQLSPEC_QUICKSTART_PG_*` from `pytest-databases` so `quickstart_5.py` stays copy/paste friendly in the docs.
+- Usage samples are function-based (`usage_*.py`) and collected automatically because `python_files` now includes that pattern.
+- Prefer smaller batches (per topic/section) to keep feedback loops fast.
+
+## Review Checklist
+
+- [ ] Example is function-based and runnable via pytest.
+- [ ] Docs include/excerpt ranges match the function body.
+- [ ] Tests were re-run or limitations were documented.
+- [ ] Temporary SQLite files are used for pooled configs to avoid leakage between examples.

sqlspec-0.30.0/specs/guides/query-stack.md

@@ -0,0 +1,67 @@
+# Query Stack Guide
+
+Query Stack executes multiple SQL statements in a single driver call while preserving raw SQL semantics. Each stack is immutable, MyPy-friendly, and can be shared across asyncio tasks or worker threads without synchronization.
+
+## When to Use Query Stack
+
+- Multi-step workflows (audit insert + update + permission read) that would otherwise require multiple round-trips.
+- Adapter-specific native pipelines (Oracle 23ai+, psycopg pipeline mode, asyncpg batch execution) where batching reduces latency.
+- Sequential fallback adapters (SQLite, DuckDB, BigQuery, ADBC, AsyncMy) when you still want the ergonomic benefits of a single API call.
+- Continue-on-error workflows that need to run every statement but report failures alongside successful operations.
+
+## Building StatementStack Instances
+
+1. Start with an empty stack: `stack = StatementStack()`.
+2. Add operations via the push helpers (each returns a new instance):
+   - `.push_execute(sql, parameters, *, statement_config=None, **kwargs)`
+   - `.push_execute_many(sql, parameter_sets, *filters, statement_config=None, **kwargs)`
+   - `.push_execute_script(sql, *filters, statement_config=None, **kwargs)`
+   - `.push_execute_arrow(sql, *filters, statement_config=None, **kwargs)`
+3. Use `.extend()` or `StatementStack.from_operations()` to combine stacks.
+4. Store stacks at module scope or factory functions—the tuple-based storage makes them hashable and thread-safe.
+
+## Execution Modes
+
+`Session.execute_stack(stack, continue_on_error=False)` mirrors the driver’s transaction rules:
+
+- **Fail-fast (default):** The driver creates a transaction if one is not already active. Any failure raises `StackExecutionError` and rolls back the transaction.
+- **Continue-on-error:** Each operation commits immediately. Failures still raise `StackExecutionError`, but execution continues and the error is preserved on the corresponding `StackResult`.
+
+When using adapters with native pipelines (Oracle, psycopg, asyncpg), continue-on-error downgrades to sequential mode if the native API cannot honor the semantics (e.g., psycopg pipeline requires fail-fast).
+
+## Transaction Boundaries
+
+- Existing transactions are respected—`execute_stack()` never commits or rolls back a transaction it did not create.
+- For fail-fast stacks, drivers call `begin()`/`commit()` (or `rollback()` on error) only when no transaction is active.
+- Continue-on-error uses commit/rollback hooks after each operation to keep the connection clean.
+
+## Arrow Operations
+
+`push_execute_arrow()` delegates to `select_to_arrow()` when the adapter implements Arrow support (DuckDB, BigQuery, ADBC, etc.). The returned `StackResult.result` is an `ArrowResult`, so downstream helpers like `to_pandas()` or `to_polars()` continue to work.
+
+## Telemetry and Tracing
+
+Every stack execution routes through `StackExecutionObserver`, which provides:
+
+- `StackExecutionMetrics`: increments `stack.execute.*` counters (invocations, statements, partial errors, duration) for any observability runtime (built-in logger, OTLP exporter, Prometheus bridge, etc.).
+- `sqlspec.stack.execute` tracing spans containing adapter, statement count, native pipeline flag, continue-on-error, and hashed SQL identifiers.
+- Structured DEBUG/ERROR logs (`stack.execute.start`, `stack.execute.complete`, `stack.execute.failed`).
+
+Adapters only need to report whether they used a native pipeline; the observer handles the rest.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `ValueError: Cannot execute an empty StatementStack` | Stack has zero operations | Ensure you push at least one statement before calling `execute_stack()` |
+| `StackExecutionError(operation_index=1, ...)` | Driver error on a specific statement | Inspect `StackResult.error` to see the wrapped exception; use `StackResult.result` to inspect partial data |
+| `push_execute_many` raising `TypeError` | Parameter payload not a sequence | Pass an actual list/tuple of parameter sets |
+| Continue-on-error seems to run sequentially on psycopg | Psycopg pipeline mode does not support partial failures | Expected—SQLSpec downgrades to sequential mode automatically |
+
+## Related Resources
+
+- [Query Stack API Reference](/reference/query-stack)
+- :doc:`/examples/patterns/stacks/query_stack_example`
+- [Adapter Guides](/guides/adapters/) for native vs. fallback behavior per database
+
+Use the new :doc:`/reference/query-stack` page for low-level API details and :doc:`/examples/patterns/stacks/query_stack_example` to see the end-to-end workflow.

{sqlspec-0.29.0 → sqlspec-0.30.0}/sqlspec/__init__.py

@@ -29,11 +29,15 @@ from sqlspec.core import (
     ParameterStyle,
     ParameterStyleConfig,
     SQLResult,
+    StackOperation,
+    StackResult,
     Statement,
     StatementConfig,
+    StatementStack,
 )
 from sqlspec.core import filters as filters
 from sqlspec.driver import AsyncDriverAdapterBase, ExecutionResult, SyncDriverAdapterBase
+from sqlspec.exceptions import StackExecutionError
 from sqlspec.loader import SQLFile, SQLFileLoader
 from sqlspec.typing import ConnectionT, PoolT, SchemaT, StatementParameters, SupportedSchemaModel
 from sqlspec.utils.logging import suppress_erroneous_sqlglot_log_messages
@@ -70,9 +74,13 @@ __all__ = (
     "SQLSpec",
     "SchemaT",
     "Select",
+    "StackExecutionError",
+    "StackOperation",
+    "StackResult",
     "Statement",
     "StatementConfig",
     "StatementParameters",
+    "StatementStack",
     "SupportedSchemaModel",
     "SyncDatabaseConfig",
     "SyncDriverAdapterBase",

{sqlspec-0.29.0 → sqlspec-0.30.0}/sqlspec/_typing.py

@@ -568,6 +568,9 @@ except ImportError:
         ) -> Tracer:
             return Tracer()  # type: ignore[abstract] # pragma: no cover
 
+        def get_tracer_provider(self) -> Any:  # pragma: no cover
+            return None
+
         TracerProvider = type(None)  # Shim for TracerProvider if needed elsewhere
         StatusCode = type(None)  # Shim for StatusCode
         Status = type(None)  # Shim for Status
@@ -600,6 +603,8 @@ except ImportError:
             unit: str = "",
             registry: Any = None,
             ejemplar_fn: Any = None,
+            buckets: Any = None,
+            **_: Any,
         ) -> None:
             return None