feat: add StatementStack tests and enhance pipeline execution across adapters

- Implement tests for StatementStack sequential execution and continue-on-error behavior in BigQuery, DuckDB, Oracle, Psqlpy, Psycopg, and SQLite adapters.
- Introduce edge case tests for StatementStack execution in SQLite, ensuring proper handling of empty stacks and mixed operations.
- Enhance OracleAsyncDriver with pipeline support tests, verifying native pipeline execution and error handling.
- Add metrics tracking for stack execution to monitor performance and error rates.
- Create a utility script to run pre-commit hooks without requiring PTY support.

Author: cofin

.gitignore

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

.pre-commit-config.yaml

@@ -43,6 +43,7 @@ repos:
     rev: "v1.0.1"
     hooks:
       - id: sphinx-lint
+        args: ["--jobs", "1"]
   - repo: local
     hooks:
       - id: pypi-readme

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.raw_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`.

docs/changelog.rst

@@ -10,6 +10,14 @@ SQLSpec Changelog
 Recent Updates
 ==============
 
+Query Stack Documentation Suite
+--------------------------------
+
+- Expanded the :doc:`/reference/query-stack` API reference (``StatementStack``, ``StackResult``, driver hooks, and ``StackExecutionError``) with the high-level workflow, execution modes, telemetry, and troubleshooting tips.
+- Added :doc:`/examples/query_stack_example` that runs the same stack against SQLite and AioSQLite.
+- Captured the detailed architecture and performance guidance inside the internal specs workspace for future agent runs.
+- Updated every adapter reference with a **Query Stack Support** section so behavior is documented per database.
+
 Migration Convenience Methods on Config Classes
 ------------------------------------------------
 

docs/examples/index.rst

@@ -91,6 +91,8 @@ Patterns
      - Routing requests to dedicated SQLite configs per tenant slug.
    * - ``patterns/configs/multi_adapter_registry.py``
      - Register multiple adapters on a single SQLSpec registry.
+   * - ``query_stack_example.py``
+     - Immutable StatementStack workflow executed against SQLite and AioSQLite drivers.
 
 Loaders
 -------
@@ -142,4 +144,5 @@ Shared Utilities
    frameworks/starlette/aiosqlite_app
    frameworks/flask/sqlite_app
    patterns/configs/multi_adapter_registry
+   query_stack_example
    README

docs/examples/query_stack_example.py

@@ -0,0 +1,98 @@
+import asyncio
+
+from sqlspec import SQLSpec
+from sqlspec.adapters.aiosqlite import AiosqliteConfig
+from sqlspec.adapters.sqlite import SqliteConfig
+from sqlspec.core import StatementStack
+
+
+def build_stack(user_id: int, action: str) -> "StatementStack":
+    stack = (
+        StatementStack()
+        .push_execute(
+            "INSERT INTO audit_log (user_id, action) VALUES (:user_id, :action)", {"user_id": user_id, "action": action}
+        )
+        .push_execute(
+            "UPDATE users SET last_action = :action WHERE id = :user_id", {"action": action, "user_id": user_id}
+        )
+        .push_execute("SELECT role FROM user_roles WHERE user_id = :user_id ORDER BY role", {"user_id": user_id})
+    )
+    return stack
+
+
+def run_sync_example() -> None:
+    sql = SQLSpec()
+    config = SqliteConfig(pool_config={"database": ":memory:"})
+    registry = sql.add_config(config)
+
+    with sql.provide_session(registry) as session:
+        session.execute_script(
+            """
+            CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, last_action TEXT);
+            CREATE TABLE IF NOT EXISTS audit_log (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                user_id INTEGER NOT NULL,
+                action TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS user_roles (
+                user_id INTEGER NOT NULL,
+                role TEXT NOT NULL
+            );
+            INSERT INTO users (id, last_action) VALUES (1, 'start');
+            INSERT INTO user_roles (user_id, role) VALUES (1, 'admin'), (1, 'editor');
+            """
+        )
+
+        stack = build_stack(user_id=1, action="sync-login")
+        results = session.execute_stack(stack)
+
+        audit_insert, user_update, role_select = results
+        print("[sync] rows inserted:", audit_insert.rowcount)
+        print("[sync] rows updated:", user_update.rowcount)
+        if role_select.raw_result is not None:
+            print("[sync] roles:", [row["role"] for row in role_select.raw_result.data])
+
+
+def run_async_example() -> None:
+    async def _inner() -> None:
+        sql = SQLSpec()
+        config = AiosqliteConfig(pool_config={"database": ":memory:"})
+        registry = sql.add_config(config)
+
+        async with sql.provide_session(registry) as session:
+            await session.execute_script(
+                """
+                CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, last_action TEXT);
+                CREATE TABLE IF NOT EXISTS audit_log (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    user_id INTEGER NOT NULL,
+                    action TEXT NOT NULL
+                );
+                CREATE TABLE IF NOT EXISTS user_roles (
+                    user_id INTEGER NOT NULL,
+                    role TEXT NOT NULL
+                );
+                INSERT INTO users (id, last_action) VALUES (2, 'start');
+                INSERT INTO user_roles (user_id, role) VALUES (2, 'viewer');
+                """
+            )
+
+            stack = build_stack(user_id=2, action="async-login")
+            results = await session.execute_stack(stack, continue_on_error=False)
+
+            audit_insert, user_update, role_select = results
+            print("[async] rows inserted:", audit_insert.rowcount)
+            print("[async] rows updated:", user_update.rowcount)
+            if role_select.raw_result is not None:
+                print("[async] roles:", [row["role"] for row in role_select.raw_result.data])
+
+    asyncio.run(_inner())
+
+
+def main() -> None:
+    run_sync_example()
+    run_async_example()
+
+
+if __name__ == "__main__":
+    main()

docs/examples/query_stack_example.rst

@@ -0,0 +1,22 @@
+====================
+Query Stack Example
+====================
+
+This example builds an immutable ``StatementStack`` and executes it against both the synchronous SQLite adapter and the asynchronous AioSQLite adapter. Each stack:
+
+1. Inserts an audit log row
+2. Updates the user's last action
+3. Fetches the user's roles
+
+.. literalinclude:: query_stack_example.py
+   :language: python
+   :caption: ``docs/examples/query_stack_example.py``
+   :linenos:
+
+Run the script:
+
+.. code-block:: console
+
+   uv run python docs/examples/query_stack_example.py
+
+Expected output shows inserted/updated row counts plus the projected role list for each adapter.

docs/guides/README.md

@@ -36,6 +36,11 @@ Optimization guides for SQLSpec:
 
 - [**SQLglot Guide**](performance/sqlglot.md) - SQL parsing, transformation, and optimization with SQLglot
 - [**MyPyC Guide**](performance/mypyc.md) - Compilation strategies for high-performance Python code
+- [**Batch Execution**](performance/batch-execution.md) - Guidance for Query Stack vs. ``execute_many`` across adapters
+
+## Features
+
+- [**Query Stack Guide**](features/query-stack.md) - Multi-statement execution, execution modes, telemetry, and troubleshooting
 
 ## Migrations
 
@@ -55,6 +60,7 @@ Core architecture and design patterns:
 
 - [**Architecture Guide**](architecture/architecture.md) - SQLSpec architecture overview
 - [**Data Flow Guide**](architecture/data-flow.md) - How data flows through SQLSpec
+- [**Architecture Patterns**](architecture/patterns.md) - Immutable stack builder, native vs. sequential branching, and telemetry requirements
 
 ## Extensions
 

docs/guides/adapters/adbc.md

@@ -17,6 +17,12 @@ This guide provides specific instructions for the `adbc` adapter.
 - **JSON Strategy:** `helper` (shared serializers wrap dict/list/tuple values)
 - **Extras:** `type_coercion_overrides` ensure Arrow arrays map to Python lists; PostgreSQL dialects attach a NULL-handling AST transformer
 
+## Query Stack Support
+
+- Each ADBC backend falls back to SQLSpec's sequential stack executor. There is no driver-agnostic pipeline API today, so stacks simply reuse the same cursor management that individual `execute()` calls use, wrapped in a transaction when the backend supports it (e.g., PostgreSQL) and as independent statements when it does not (e.g., SQLite, DuckDB).
+- Continue-on-error mode is supported on every backend. Successful statements commit as they finish, while failures populate `StackResult.error` for downstream inspection.
+- Telemetry spans (`sqlspec.stack.execute`) and `StackExecutionMetrics` counters emit for all stacks, enabling observability parity with adapters that do have native optimizations.
+
 ## Best Practices
 
 - **Arrow-Native:** The primary benefit of ADBC is its direct integration with Apache Arrow. Use it when you need to move large amounts of data efficiently between the database and data science tools like Pandas or Polars.

docs/guides/adapters/aiosqlite.md

@@ -17,6 +17,11 @@ This guide provides specific instructions for the `aiosqlite` adapter.
 - **JSON Strategy:** `helper` (shared serializer handles dict/list/tuple inputs)
 - **Extras:** None (profile applies bool→int and ISO datetime coercions automatically)
 
+## Query Stack Support
+
+- `StatementStack` executions always use the sequential fallback – SQLite has no notion of pipelined requests – so each operation runs one after another on the same connection. When `continue_on_error=False`, SQLSpec opens a transaction (if one is not already in progress) so the entire stack commits or rolls back together. With `continue_on_error=True`, statements are committed individually after each success.
+- Because pooled in-memory connections share state, prefer per-test temporary database files when running stacks under pytest-xdist (see `tests/integration/test_adapters/test_aiosqlite/test_driver.py::test_aiosqlite_statement_stack_*` for the reference pattern).
+
 ## Best Practices
 
 - **Async Only:** This is an asynchronous driver for SQLite. Use it in `asyncio` applications.