fix(query builder): correct edge cases and typing of query builder

.github/workflows/ci.yml

@@ -106,7 +106,10 @@ jobs:
         run: uv sync --all-extras --dev
 
       - name: Test
-        run: uv run pytest -n 2 --dist=loadgroup
+        env:
+          PYTHONFAULTHANDLER: "1"
+          PYTEST_ADDOPTS: "--max-worker-restart=0 -s"
+        run: timeout 900s uv run pytest -n 2 --dist=loadgroup
 
   # test-windows:
   #   runs-on: windows-latest

.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.5"
+    rev: "v0.14.6"
     hooks:
       - id: ruff
         args: ["--fix"]
@@ -40,7 +40,7 @@ repos:
       - id: slotscheck
         exclude: "docs|.github"
   - repo: https://github.com/sphinx-contrib/sphinx-lint
-    rev: "v1.0.1"
+    rev: "v1.0.2"
     hooks:
       - id: sphinx-lint
         args: ["--jobs", "1"]

docs/examples/quickstart/quickstart_5.py

@@ -2,6 +2,8 @@
 
 import pytest
 
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_quickstart_5",)
 
 

docs/examples/usage/usage_configuration_1.py

@@ -2,6 +2,7 @@
 
 
 def test_sqlite_memory_db() -> None:
+    from rich import print
 
     # start-example
     from sqlspec import SQLSpec
@@ -15,6 +16,7 @@ def test_sqlite_memory_db() -> None:
 
     # Use the database
     with db_manager.provide_session(db) as session:
-        result = session.execute("SELECT 1")
+        value = session.select_value("SELECT 1")
+        print(value)
         # end-example
-        assert result[0] == {"1": 1}
+        assert value == 1

docs/examples/usage/usage_configuration_10.py

@@ -1,3 +1,7 @@
+import pytest
+
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_manual_pool",)
 
 

docs/examples/usage/usage_configuration_12.py

@@ -1,3 +1,7 @@
+import pytest
+
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_basic_statement_config",)
 
 

docs/examples/usage/usage_configuration_19.py

@@ -1,5 +1,9 @@
 """Test configuration example: Binding multiple database configurations."""
 
+import pytest
+
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_binding_multiple_configs",)
 
 

docs/examples/usage/usage_configuration_20.py

@@ -1,5 +1,9 @@
 """Test configuration example: Named database bindings."""
 
+import pytest
+
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_named_bindings",)
 
 

docs/examples/usage/usage_configuration_21.py

@@ -1,5 +1,9 @@
 """Test configuration example: Basic migration configuration."""
 
+import pytest
+
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_basic_migration_config",)
 
 

docs/examples/usage/usage_configuration_22.py

@@ -1,3 +1,7 @@
+import pytest
+
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_basic_migration_config",)
 
 

docs/examples/usage/usage_configuration_23.py

@@ -1,5 +1,9 @@
 """Test configuration example: Environment-based configuration."""
 
+import pytest
+
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_extension_config",)
 
 

docs/examples/usage/usage_configuration_25.py

@@ -1,5 +1,9 @@
 """Test configuration example: Best practice - Use connection pooling."""
 
+import pytest
+
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_connection_pooling_best_practice",)
 
 

docs/examples/usage/usage_configuration_4.py

@@ -1,3 +1,7 @@
+import pytest
+
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_asyncpg_config_setup",)
 
 

docs/examples/usage/usage_configuration_5.py

@@ -1,3 +1,7 @@
+import pytest
+
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_psycopg_config_setup",)
 
 

docs/examples/usage/usage_configuration_8.py

@@ -1,3 +1,7 @@
+import pytest
+
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_asyncpg_pool_setup",)
 
 

docs/examples/usage/usage_configuration_9.py

@@ -1,3 +1,7 @@
+import pytest
+
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_pool_lifecycle",)
 
 

docs/examples/usage/usage_data_flow_11.py

@@ -5,6 +5,8 @@
 
 def test_sql_result_object() -> None:
     """Test accessing SQLResult object properties."""
+    from rich import print
+
     from sqlspec import SQLSpec
     from sqlspec.adapters.sqlite import SqliteConfig
 
@@ -13,15 +15,13 @@ def test_sql_result_object() -> None:
 
     # start-example
     with db_manager.provide_session(db) as session:
-        result = session.execute("SELECT 'test' as col1, 'value' as col2")
+        result = session.select("SELECT 'test' as col1, 'value' as col2")
+        print(len(result))  # length of result set
 
-        # Access result data
-        result.data  # List of dictionaries
-        result.rows_affected  # Number of rows modified (INSERT/UPDATE/DELETE)
-        result.column_names  # Column names for SELECT
-        result.operation_type  # "SELECT", "INSERT", "UPDATE", "DELETE", "SCRIPT"
+        # Access result data (SQLResult is iterable over rows)
+        print(result)
     # end-example
 
     # Verify result properties
-    assert result.data is not None
-    assert result.column_names is not None
+    assert result is not None
+    assert len(result) == 1

docs/examples/usage/usage_data_flow_13.py

@@ -5,9 +5,9 @@
 
 def test_schema_mapping() -> None:
     """Test mapping results to typed objects."""
-
     # start-example
     from pydantic import BaseModel
+    from rich import print
 
     from sqlspec import SQLSpec
     from sqlspec.adapters.sqlite import SqliteConfig
@@ -27,17 +27,17 @@ class User(BaseModel):
         session.execute("INSERT INTO users VALUES (1, 'Alice', '[email protected]', 1)")
 
         # Execute query
-        result = session.execute("SELECT id, name, email, is_active FROM users")
-
-        # Map results to typed User instances
-        users: list[User] = result.all(schema_type=User)
+        result = session.select("SELECT id, name, email, is_active FROM users", schema_type=User)
+        print(len(result))
 
         # Or get single typed user
-        single_result = session.execute("SELECT id, name, email, is_active FROM users WHERE id = ?", 1)
-        user: User = single_result.one(schema_type=User)  # Type-safe!
+        single_result = session.select_one(
+            "SELECT id, name, email, is_active FROM users WHERE id = ?", 1, schema_type=User
+        )
+        print(single_result)
     # end-example
 
     # Verify typed results
-    assert len(users) == 1
-    assert isinstance(user, User)
-    assert user.id == 1
+    assert len(result) == 1
+    assert isinstance(single_result, User)
+    assert single_result.id == 1

docs/examples/usage/usage_data_flow_8.py

@@ -16,6 +16,8 @@ def test_statement_execution() -> None:
 
     with db_manager.provide_session(db) as session:
         result = session.execute(sql_statement)
+        print(result.rows_affected)
+        print(result.parameters)
         message = result.scalar()
     # end-example
 

docs/examples/usage/usage_data_flow_9.py

@@ -5,6 +5,8 @@
 
 def test_driver_execution() -> None:
     """Test driver execution pattern."""
+    from rich import print
+
     from sqlspec import SQLSpec
     from sqlspec.adapters.sqlite import SqliteConfig
 
@@ -13,7 +15,8 @@ def test_driver_execution() -> None:
     db_manager = SQLSpec()
     db = db_manager.add_config(SqliteConfig(pool_config={"database": ":memory:"}))
     with db_manager.provide_session(db) as session:
-        result = session.execute("SELECT 'test' as message")
+        message = session.select_value("SELECT 'test' as message")
+        print(message)
     # end-example
 
-    assert result is not None
+    assert message == "test"

docs/examples/usage/usage_drivers_and_querying_1.py

@@ -3,8 +3,11 @@
 
 import os
 
+import pytest
 from pytest_databases.docker.postgres import PostgresService
 
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_importable_1",)
 
 

docs/examples/usage/usage_drivers_and_querying_11.py

@@ -1,8 +1,11 @@
 # Test module converted from docs example - code-block 11
 """Minimal smoke test for drivers_and_querying example 11."""
 
+import pytest
 from pytest_databases.docker.oracle import OracleService
 
+pytestmark = pytest.mark.xdist_group("oracle")
+
 __all__ = ("test_example_11_oracledb_config",)
 
 

docs/examples/usage/usage_drivers_and_querying_12.py

@@ -5,6 +5,8 @@
 
 from sqlspec.adapters.bigquery.driver import BigQueryDriver
 
+pytestmark = pytest.mark.xdist_group("bigquery")
+
 __all__ = ("test_example_12_bigquery_config",)
 
 

docs/examples/usage/usage_drivers_and_querying_2.py

@@ -3,8 +3,11 @@
 
 import os
 
+import pytest
 from pytest_databases.docker.postgres import PostgresService
 
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_example_2_importable",)
 
 

docs/examples/usage/usage_drivers_and_querying_21.py

@@ -2,8 +2,12 @@
 
 import os
 
+import pytest
+
 from sqlspec.adapters.asyncpg import AsyncpgConfig
 
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_example_21_pool_config",)
 
 

docs/examples/usage/usage_drivers_and_querying_3.py

@@ -3,8 +3,11 @@
 
 import os
 
+import pytest
 from pytest_databases.docker.postgres import PostgresService
 
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_example_3_sync",)
 
 

docs/examples/usage/usage_drivers_and_querying_4.py

@@ -3,8 +3,11 @@
 
 import os
 
+import pytest
 from pytest_databases.docker.postgres import PostgresService
 
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_example_4_async",)
 
 

docs/examples/usage/usage_drivers_and_querying_5.py

@@ -3,11 +3,14 @@
 
 import os
 
+import pytest
 from pytest_databases.docker.postgres import PostgresService
 
 from sqlspec import SQLSpec
 from sqlspec.adapters.psqlpy import PsqlpyConfig
 
+pytestmark = pytest.mark.xdist_group("postgres")
+
 __all__ = ("test_example_5_construct_config",)
 
 

docs/examples/usage/usage_drivers_and_querying_9.py

@@ -1,8 +1,11 @@
 # Test module converted from docs example - code-block 9
 """Minimal smoke test for drivers_and_querying example 9."""
 
+import pytest
 from pytest_databases.docker.mysql import MySQLService
 
+pytestmark = pytest.mark.xdist_group("mysql")
+
 __all__ = ("test_example_9_asyncmy_config",)