feat: builder api

.gitignore

@@ -17,7 +17,9 @@ site/
 target/
 .idea/
 .vscode/
+.claude/
 .cursor/
+.zed/
 
 # files
 **/*.so
@@ -31,3 +33,13 @@ target/
 /docs/_build/
 coverage.*
 setup.py
+tmp/
+*.log
+.bugs
+.tmp
+.todos
+todo/
+CLAUDE.md
+CLAUDE.*.md
+TODO*
+.claudedocs

.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.11.9"
+    rev: "v0.12.0"
     hooks:
       - id: ruff
         args: ["--fix"]
@@ -29,7 +29,7 @@ repos:
         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"

docs/conf.py

@@ -46,9 +46,7 @@
 
 nitpicky = True
 nitpick_ignore: list[str] = []
-nitpick_ignore_regex = [
-    (PY_RE, r"sqlspec.*\.T"),
-]
+nitpick_ignore_regex = [(PY_RE, r"sqlspec.*\.T")]
 
 napoleon_google_docstring = True
 napoleon_include_special_with_doc = True
@@ -79,11 +77,7 @@
 html_title = "SQLSpec"
 # html_favicon = "_static/logo.png"
 # html_logo = "_static/logo.png"
-html_context = {
-    "source_type": "github",
-    "source_user": "cofin",
-    "source_repo": project.replace("_", "-"),
-}
+html_context = {"source_type": "github", "source_user": "cofin", "source_repo": project.replace("_", "-")}
 
 brand_colors = {
     "--brand-primary": {"rgb": "245, 0, 87", "hex": "#f50057"},

docs/examples/litestar_asyncpg.py

@@ -13,34 +13,28 @@
 # ]
 # ///
 
-from typing import Annotated, Optional
+from typing import Annotated, Any
 
 from litestar import Litestar, get
 from litestar.params import Dependency
 
-from sqlspec.adapters.asyncpg import AsyncpgConfig, AsyncpgDriver, AsyncpgPoolConfig
+from sqlspec.adapters.asyncpg import AsyncpgConfig, AsyncpgDriver
 from sqlspec.extensions.litestar import DatabaseConfig, SQLSpec, providers
-from sqlspec.filters import FilterTypes
+from sqlspec.statement import SQLResult
+from sqlspec.statement.filters import FilterTypes
 
 
-@get(
-    "/",
-    dependencies=providers.create_filter_dependencies({"search": "greeting", "search_ignore_case": True}),
-)
+@get("/", dependencies=providers.create_filter_dependencies({"search": "greeting", "search_ignore_case": True}))
 async def simple_asyncpg(
     db_session: AsyncpgDriver, filters: Annotated[list[FilterTypes], Dependency(skip_validation=True)]
-) -> Optional[dict[str, str]]:
-    return await db_session.select_one_or_none(
-        "SELECT greeting FROM (select 'Hello, world!' as greeting) as t", *filters
-    )
+) -> SQLResult[dict[str, Any]]:
+    return await db_session.execute("SELECT greeting FROM (select 'Hello, world!' as greeting) as t", *filters)
 
 
 sqlspec = SQLSpec(
     config=[
         DatabaseConfig(
-            config=AsyncpgConfig(
-                pool_config=AsyncpgPoolConfig(dsn="postgres://app:app@localhost:15432/app", min_size=1, max_size=3),
-            ),
+            config=AsyncpgConfig(dsn="postgres://app:app@localhost:15432/app", min_size=1, max_size=3),
             commit_mode="autocommit",
         )
     ]

docs/examples/litestar_duckllm.py

@@ -44,7 +44,7 @@ def duckllm_chat(db_session: DuckDBDriver, data: ChatMessage) -> ChatMessage:
                 },
             }
         ],
-    ),
+    )
 )
 app = Litestar(route_handlers=[duckllm_chat], plugins=[sqlspec], debug=True)
 

docs/examples/litestar_multi_db.py

@@ -22,8 +22,9 @@
 
 @get("/test", sync_to_thread=True)
 def simple_select(etl_session: DuckDBDriver) -> dict[str, str]:
-    result = etl_session.select_one("SELECT 'Hello, ETL world!' AS greeting")
-    return {"greeting": result["greeting"]}
+    result = etl_session.execute("SELECT 'Hello, ETL world!' AS greeting")
+    greeting = result.get_first()
+    return {"greeting": greeting["greeting"] if greeting is not None else "hi"}
 
 
 @get("/")
@@ -42,7 +43,7 @@ async def simple_sqlite(db_session: AiosqliteDriver) -> dict[str, str]:
             connection_key="etl_connection",
             session_key="etl_session",
         ),
-    ],
+    ]
 )
 app = Litestar(route_handlers=[simple_sqlite, simple_select], plugins=[sqlspec])
 

docs/examples/litestar_psycopg.py

@@ -15,26 +15,23 @@
 
 from litestar import Litestar, get
 
-from sqlspec.adapters.psycopg import PsycopgAsyncConfig, PsycopgAsyncDriver, PsycopgAsyncPoolConfig
+from sqlspec.adapters.psycopg import PsycopgAsyncConfig, PsycopgAsyncDriver
 from sqlspec.extensions.litestar import DatabaseConfig, SQLSpec
 
 
 @get("/")
 async def simple_psycopg(db_session: PsycopgAsyncDriver) -> dict[str, str]:
-    return await db_session.select_one("SELECT 'Hello, world!' AS greeting")
+    result = await db_session.execute("SELECT 'Hello, world!' AS greeting")
+    return result.get_first() or {"greeting": "No result found"}
 
 
 sqlspec = SQLSpec(
     config=[
         DatabaseConfig(
-            config=PsycopgAsyncConfig(
-                pool_config=PsycopgAsyncPoolConfig(
-                    conninfo="postgres://app:app@localhost:15432/app", min_size=1, max_size=3
-                ),
-            ),
+            config=PsycopgAsyncConfig(conninfo="postgres://app:app@localhost:15432/app", min_size=1, max_size=3),
             commit_mode="autocommit",
         )
-    ],
+    ]
 )
 app = Litestar(route_handlers=[simple_psycopg], plugins=[sqlspec])
 

docs/examples/litestar_single_db.py

@@ -5,13 +5,6 @@
 This examples hows how to get the raw connection object from the SQLSpec plugin.
 """
 
-# /// script
-# dependencies = [
-#   "sqlspec[aiosqlite]",
-#   "litestar[standard]",
-# ]
-# ///
-
 from aiosqlite import Connection
 from litestar import Litestar, get
 
@@ -27,8 +20,8 @@ async def simple_sqlite(db_connection: Connection) -> dict[str, str]:
         dict[str, str]: The greeting.
     """
     result = await db_connection.execute_fetchall("SELECT 'Hello, world!' AS greeting")
-    return {"greeting": result[0][0]}  # type: ignore
+    return {"greeting": next(iter(result))[0]}
 
 
-sqlspec = SQLSpec(config=AiosqliteConfig())
+sqlspec = SQLSpec(config=AiosqliteConfig(database=":memory:"))
 app = Litestar(route_handlers=[simple_sqlite], plugins=[sqlspec])

docs/examples/logging_setup_example.py

@@ -0,0 +1,107 @@
+"""Example of how to configure logging for SQLSpec.
+
+Since SQLSpec no longer provides a configure_logging function,
+users can set up their own logging configuration as needed.
+"""
+
+import logging
+import sys
+
+from sqlspec.utils.correlation import correlation_context
+from sqlspec.utils.logging import StructuredFormatter, get_logger
+
+__all__ = ("demo_correlation_ids", "setup_advanced_logging", "setup_simple_logging", "setup_structured_logging")
+
+
+# Example 1: Basic logging setup with structured JSON output
+def setup_structured_logging() -> None:
+    """Set up structured JSON logging for SQLSpec."""
+    # Get the SQLSpec logger
+    sqlspec_logger = logging.getLogger("sqlspec")
+
+    # Set the logging level
+    sqlspec_logger.setLevel(logging.INFO)
+
+    # Create a console handler with structured formatter
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setFormatter(StructuredFormatter())
+
+    # Add the handler to the logger
+    sqlspec_logger.addHandler(console_handler)
+
+    # Don't propagate to the root logger
+    sqlspec_logger.propagate = False
+
+    print("Structured logging configured for SQLSpec")
+
+
+# Example 2: Simple text logging
+def setup_simple_logging() -> None:
+    """Set up simple text logging for SQLSpec."""
+    # Configure basic logging for the entire application
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        handlers=[logging.StreamHandler(sys.stdout)],
+    )
+
+    print("Simple logging configured")
+
+
+# Example 3: Advanced setup with file output and custom formatting
+def setup_advanced_logging() -> None:
+    """Set up advanced logging with multiple handlers."""
+    sqlspec_logger = logging.getLogger("sqlspec")
+    sqlspec_logger.setLevel(logging.DEBUG)
+
+    # Console handler with simple format
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    console_handler.setFormatter(console_formatter)
+    console_handler.setLevel(logging.INFO)  # Only INFO and above to console
+
+    # File handler with structured format
+    file_handler = logging.FileHandler("sqlspec.log")
+    file_handler.setFormatter(StructuredFormatter())
+    file_handler.setLevel(logging.DEBUG)  # All messages to file
+
+    # Add both handlers
+    sqlspec_logger.addHandler(console_handler)
+    sqlspec_logger.addHandler(file_handler)
+
+    # Don't propagate to avoid duplicate logs
+    sqlspec_logger.propagate = False
+
+    print("Advanced logging configured with console and file output")
+
+
+# Example 4: Using correlation IDs
+def demo_correlation_ids() -> None:
+    """Demonstrate using correlation IDs with logging."""
+
+    logger = get_logger("example")
+
+    # Without correlation ID
+    logger.info("This log has no correlation ID")
+
+    # With correlation ID
+    with correlation_context() as correlation_id:
+        logger.info("Starting operation with correlation ID: %s", correlation_id)
+        logger.info("This log will include the correlation ID automatically")
+
+        # Simulate some work
+        logger.debug("Processing data...")
+        logger.info("Operation completed")
+
+
+if __name__ == "__main__":
+    # Choose your logging setup
+    print("=== Structured Logging Example ===")
+    setup_structured_logging()
+    demo_correlation_ids()
+
+    print("\n=== Simple Logging Example ===")
+    setup_simple_logging()
+
+    print("\n=== Advanced Logging Example ===")
+    setup_advanced_logging()

docs/examples/queries/users.sql

@@ -0,0 +1,74 @@
+-- User Management SQL Queries
+-- This file contains all user-related queries using aiosql-style named queries
+
+-- name: get_user_by_id
+-- Get a single user by their ID
+SELECT
+    id,
+    username,
+    email,
+    created_at,
+    updated_at
+FROM users
+WHERE id = :user_id;
+
+-- name: get_user_by_email
+-- Find a user by their email address
+SELECT
+    id,
+    username,
+    email,
+    created_at
+FROM users
+WHERE LOWER(email) = LOWER(:email);
+
+-- name: list_active_users
+-- List all active users with pagination
+SELECT
+    id,
+    username,
+    email,
+    last_login_at
+FROM users
+WHERE is_active = true
+ORDER BY username
+LIMIT :limit OFFSET :offset;
+
+-- name: create_user
+-- Create a new user and return the created record
+INSERT INTO users (
+    username,
+    email,
+    password_hash,
+    is_active
+) VALUES (
+    :username,
+    :email,
+    :password_hash,
+    :is_active
+)
+RETURNING id, username, email, created_at;
+
+-- name: update_user_last_login
+-- Update the last login timestamp for a user
+UPDATE users
+SET
+    last_login_at = CURRENT_TIMESTAMP,
+    updated_at = CURRENT_TIMESTAMP
+WHERE id = :user_id;
+
+-- name: deactivate_user
+-- Soft delete a user by setting is_active to false
+UPDATE users
+SET
+    is_active = false,
+    updated_at = CURRENT_TIMESTAMP
+WHERE id = :user_id;
+
+-- name: count_users_by_status
+-- Count users grouped by their active status
+SELECT
+    is_active,
+    COUNT(*) as count
+FROM users
+GROUP BY is_active;