docs: 173 usage configuration

AGENTS.md

@@ -507,6 +507,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 +2042,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                                    |

docs/examples/usage/conftest.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+
+import pytest
+from pytest_databases.docker.postgres import PostgresService
+
+pytest_plugins = ["pytest_databases.docker.postgres"]
+
+
+@pytest.fixture(scope="session", autouse=True)
+def usage_postgres_env(postgres_service: PostgresService) -> Generator[None, None, None]:
+    """Expose Postgres connection settings via env vars for docs examples."""
+
+    patcher = pytest.MonkeyPatch()
+    dsn = (
+        f"postgresql://{postgres_service.user}:{postgres_service.password}"
+        f"@{postgres_service.host}:{postgres_service.port}/{postgres_service.database}"
+    )
+    patcher.setenv("SQLSPEC_USAGE_PG_DSN", dsn)
+    patcher.setenv("SQLSPEC_USAGE_PG_HOST", postgres_service.host)
+    patcher.setenv("SQLSPEC_USAGE_PG_PORT", str(postgres_service.port))
+    patcher.setenv("SQLSPEC_USAGE_PG_USER", postgres_service.user)
+    patcher.setenv("SQLSPEC_USAGE_PG_PASSWORD", postgres_service.password)
+    patcher.setenv("SQLSPEC_USAGE_PG_DATABASE", postgres_service.database)
+    yield
+    patcher.undo()

docs/examples/usage/usage_configuration_1.py

@@ -0,0 +1,14 @@
+def test_sqlite_memory_db() -> None:
+    from sqlspec import SQLSpec
+    from sqlspec.adapters.sqlite import SqliteConfig
+
+    # Create SQLSpec instance
+    db_manager = SQLSpec()
+
+    # Add database configuration
+    db = db_manager.add_config(SqliteConfig(pool_config={"database": ":memory:"}))
+
+    # Use the database
+    with db_manager.provide_session(db) as session:
+        result = session.execute("SELECT 1")
+        assert result[0] == {"1": 1}

docs/examples/usage/usage_configuration_10.py

@@ -0,0 +1,12 @@
+POOL_INSTANCE = 20
+
+
+def test_manual_pool() -> None:
+    import os
+
+    from sqlspec.adapters.asyncpg import AsyncpgConfig
+
+    dsn = os.getenv("SQLSPEC_USAGE_PG_DSN", "postgresql://localhost/db")
+    pool = {"dsn": dsn, "min_size": 10, "max_size": POOL_INSTANCE}
+    db = AsyncpgConfig(pool_instance=pool)
+    assert db.pool_instance["max_size"] == POOL_INSTANCE

docs/examples/usage/usage_configuration_11.py

@@ -0,0 +1,5 @@
+def test_thread_local_connections() -> None:
+    from sqlspec.adapters.sqlite import SqliteConfig
+
+    config = SqliteConfig(pool_config={"database": "test.db"})
+    assert config.pool_config["database"] == "test.db"

docs/examples/usage/usage_configuration_12.py

@@ -0,0 +1,19 @@
+def test_basic_statement_config() -> None:
+    import os
+
+    from sqlspec import StatementConfig
+    from sqlspec.adapters.asyncpg import AsyncpgConfig
+
+    statement_config = StatementConfig(
+        dialect="postgres",  # SQLGlot dialect
+        enable_parsing=True,  # Parse SQL into AST
+        enable_validation=True,  # Run security/performance validators
+        enable_transformations=True,  # Apply AST transformations
+        enable_caching=True,  # Enable multi-tier caching
+    )
+
+    # Apply to adapter
+    dsn = os.getenv("SQLSPEC_USAGE_PG_DSN", "postgresql://localhost/db")
+    config = AsyncpgConfig(pool_config={"dsn": dsn}, statement_config=statement_config)
+    assert config.statement_config.dialect == "postgres"
+    assert config.statement_config.enable_parsing is True

docs/examples/usage/usage_configuration_13.py

@@ -0,0 +1,15 @@
+def test_parameter_style_config() -> None:
+    from sqlspec import ParameterStyle, ParameterStyleConfig, StatementConfig
+
+    param_config = ParameterStyleConfig(
+        default_parameter_style=ParameterStyle.NUMERIC,  # $1, $2, ...
+        supported_parameter_styles={
+            ParameterStyle.NUMERIC,
+            ParameterStyle.NAMED_COLON,  # :name
+        },
+        has_native_list_expansion=False,
+        needs_static_script_compilation=False,
+    )
+
+    statement_config = StatementConfig(dialect="postgres", parameter_config=param_config)
+    assert statement_config.parameter_config.default_parameter_style == ParameterStyle.NUMERIC

docs/examples/usage/usage_configuration_14.py

@@ -0,0 +1,19 @@
+def test_parameter_styles() -> None:
+    from sqlspec import ParameterStyle
+
+    # Question mark (SQLite, DuckDB)
+    qmark = ParameterStyle.QMARK  # WHERE id = ?
+
+    # Numeric (PostgreSQL, asyncpg)
+    numeric = ParameterStyle.NUMERIC  # WHERE id = $1
+
+    # Named colon (Oracle, SQLite)
+    named_colon = ParameterStyle.NAMED_COLON  # WHERE id = :id
+
+    # Named at (BigQuery)
+
+    # Format/pyformat (psycopg, MySQL)
+
+    assert qmark == ParameterStyle.QMARK
+    assert numeric == ParameterStyle.NUMERIC
+    assert named_colon == ParameterStyle.NAMED_COLON

docs/examples/usage/usage_configuration_15.py

@@ -0,0 +1,23 @@
+"""Test configuration example: Global cache configuration."""
+
+SQL_CACHE_SIZE = 1000
+
+
+def test_global_cache_config() -> None:
+    """Test global cache configuration."""
+    from sqlspec.core.cache import CacheConfig, update_cache_config
+
+    cache_config = CacheConfig(
+        compiled_cache_enabled=True,  # Cache compiled SQL
+        sql_cache_enabled=True,  # Cache SQL strings
+        fragment_cache_enabled=True,  # Cache SQL fragments
+        optimized_cache_enabled=True,  # Cache optimized AST
+        sql_cache_size=SQL_CACHE_SIZE,  # Maximum cached SQL items
+    )
+
+    # Update global cache configuration
+    update_cache_config(cache_config)
+
+    # Verify config applied
+    assert cache_config.sql_cache_enabled is True
+    assert cache_config.sql_cache_size == SQL_CACHE_SIZE

docs/examples/usage/usage_configuration_16.py

@@ -0,0 +1,23 @@
+"""Test configuration example: Per-instance cache configuration."""
+
+
+def test_per_instance_cache_config() -> None:
+    """Test per-instance cache configuration."""
+    import tempfile
+
+    from sqlspec import SQLSpec
+    from sqlspec.adapters.sqlite import SqliteConfig
+    from sqlspec.core.cache import CacheConfig
+
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=True) as tmp:
+        # Configure cache for specific SQLSpec instance
+        db_manager = SQLSpec()
+        db_manager.update_cache_config(CacheConfig(sql_cache_enabled=True, sql_cache_size=500))
+
+        # Add database config
+        db = db_manager.add_config(SqliteConfig(pool_config={"database": tmp.name}))
+
+        # Use the configured spec
+        with db_manager.provide_session(db) as session:
+            result = session.execute("SELECT 1")
+            assert result is not None

docs/examples/usage/usage_configuration_17.py

@@ -0,0 +1,27 @@
+"""Test configuration example: Cache statistics tracking."""
+
+
+def test_cache_statistics() -> None:
+    """Test cache statistics tracking."""
+    import tempfile
+
+    from sqlspec import SQLSpec
+    from sqlspec.adapters.sqlite import SqliteConfig
+    from sqlspec.core.cache import get_cache_statistics, log_cache_stats
+
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=True) as tmp:
+        db_manager = SQLSpec()
+        db = db_manager.add_config(SqliteConfig(pool_config={"database": tmp.name}))
+
+        # Execute some queries to generate cache activity
+        with db_manager.provide_session(db) as session:
+            session.execute("SELECT 1")
+            session.execute("SELECT 1")  # Should hit cache
+
+        # Get statistics
+        stats = get_cache_statistics()
+        assert isinstance(stats, dict)
+        assert "multi_level" in stats
+
+        # Log statistics (logs to configured logger)
+        log_cache_stats()

docs/examples/usage/usage_configuration_18.py

@@ -0,0 +1,18 @@
+"""Test configuration example: Cache clearing operations."""
+
+
+def test_clear_cache() -> None:
+    """Test cache clearing operations."""
+    from sqlspec.core.cache import clear_all_caches, get_cache_statistics
+
+    # Get initial statistics
+    stats_before = get_cache_statistics()
+    assert isinstance(stats_before, dict)
+
+    # Clear all caches and reset statistics
+    clear_all_caches()
+
+    # Verify caches were cleared
+    stats_after = get_cache_statistics()
+    assert isinstance(stats_after, dict)
+    assert "multi_level" in stats_after

docs/examples/usage/usage_configuration_19.py

@@ -0,0 +1,29 @@
+"""Test configuration example: Binding multiple database configurations."""
+
+
+def test_binding_multiple_configs() -> None:
+    """Test binding multiple database configurations."""
+    import os
+    import tempfile
+
+    from sqlspec import SQLSpec
+    from sqlspec.adapters.asyncpg import AsyncpgConfig
+    from sqlspec.adapters.sqlite import SqliteConfig
+
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=True) as tmp:
+        db_manager = SQLSpec()
+
+        # Add multiple configurations
+        sqlite_key = db_manager.add_config(SqliteConfig(pool_config={"database": tmp.name}))
+        dsn = os.getenv("SQLSPEC_USAGE_PG_DSN", "postgresql://localhost/db")
+        asyncpg_key = db_manager.add_config(AsyncpgConfig(pool_config={"dsn": dsn}))
+
+        # Use specific configuration
+        with db_manager.provide_session(sqlite_key) as session:
+            session.execute("SELECT 1")
+
+        sqlite_config = db_manager.get_config(sqlite_key)
+        pg_config = db_manager.get_config(asyncpg_key)
+
+        assert sqlite_config.pool_config["database"] == tmp.name
+        assert pg_config.pool_config["dsn"] == os.getenv("SQLSPEC_USAGE_PG_DSN", "postgresql://localhost/db")

docs/examples/usage/usage_configuration_2.py

@@ -0,0 +1,13 @@
+def test_sqlite_config_setup() -> None:
+    from sqlspec.adapters.sqlite import SqliteConfig
+
+    config = SqliteConfig(
+        pool_config={
+            "database": "myapp.db",  # Database file path
+            "timeout": 5.0,  # Lock timeout in seconds
+            "check_same_thread": False,  # Allow multi-thread access
+            "cached_statements": 100,  # Statement cache size
+            "uri": False,  # Enable URI mode
+        }
+    )
+    assert config.pool_config["database"] == "myapp.db"

docs/examples/usage/usage_configuration_20.py

@@ -0,0 +1,31 @@
+"""Test configuration example: Named database bindings."""
+
+
+def test_named_bindings() -> None:
+    """Test named database bindings."""
+    import os
+    import tempfile
+
+    from sqlspec import SQLSpec
+    from sqlspec.adapters.asyncpg import AsyncpgConfig
+    from sqlspec.adapters.sqlite import SqliteConfig
+
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=True) as tmp:
+        db_manager = SQLSpec()
+
+        # Add with bind keys
+        cache_key = db_manager.add_config(
+            SqliteConfig(pool_config={"database": tmp.name}, bind_key="cache_db")
+        )
+        dsn = os.getenv("SQLSPEC_USAGE_PG_DSN", "postgresql://localhost/db")
+        main_key = db_manager.add_config(AsyncpgConfig(pool_config={"dsn": dsn}, bind_key="main_db"))
+
+        # Access by bind key
+        with db_manager.provide_session(cache_key) as session:
+            session.execute("SELECT 1")
+
+        cache_config = db_manager.get_config(cache_key)
+        main_config = db_manager.get_config(main_key)
+
+        assert cache_config.bind_key == "cache_db"
+        assert main_config.bind_key == "main_db"

docs/examples/usage/usage_configuration_21.py

@@ -0,0 +1,29 @@
+"""Test configuration example: Basic migration configuration."""
+
+import pytest
+
+
+@pytest.mark.skipif(
+    not pytest.importorskip("asyncpg", reason="AsyncPG not installed"), reason="AsyncPG integration tests disabled"
+)
+def test_basic_migration_config() -> None:
+    """Test basic migration configuration."""
+    import os
+
+    from sqlspec.adapters.asyncpg import AsyncpgConfig
+
+    dsn = os.getenv("SQLSPEC_USAGE_PG_DSN", "postgresql://localhost/db")
+    config = AsyncpgConfig(
+        pool_config={"dsn": dsn},
+        extension_config={
+            "litestar": {"session_table": "custom_sessions"}  # Extension settings
+        },
+        migration_config={
+            "script_location": "migrations",  # Migration directory
+            "version_table": "alembic_version",  # Version tracking table
+            "include_extensions": ["litestar"],  # Simple string list only
+        },
+    )
+
+    assert config.migration_config["script_location"] == "migrations"
+    assert "litestar" in config.migration_config["include_extensions"]

docs/examples/usage/usage_configuration_22.py

@@ -0,0 +1,19 @@
+def test_basic_migration_config() -> None:
+    import os
+
+    from sqlspec.adapters.asyncpg import AsyncpgConfig
+
+    dsn = os.getenv("SQLSPEC_USAGE_PG_DSN", "postgresql://localhost/db")
+    config = AsyncpgConfig(
+        pool_config={"dsn": dsn},
+        extension_config={
+            "litestar": {"session_table": "custom_sessions"}  # Extension settings
+        },
+        migration_config={
+            "script_location": "migrations",  # Migration directory
+            "version_table": "alembic_version",  # Version tracking table
+            "include_extensions": ["litestar"],  # Simple string list only
+        },
+    )
+    assert config.migration_config["script_location"] == "migrations"
+    assert "litestar" in config.migration_config["include_extensions"]