Refactor example configurations and tests

- Deleted outdated test configuration examples for asyncpg and psycopg.
- Added new example configurations for SQLite, asyncpg, psycopg, asyncmy, and DuckDB.
- Introduced environment-based configuration examples for better flexibility.
- Updated documentation references to point to the new example files.
- Enhanced test cases to cover various best practices, including connection pooling, caching, and resource cleanup.
- Improved clarity and organization of configuration examples for better usability.

Author: cofin

AGENTS.md

@@ -524,7 +524,6 @@ 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.

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/test_configuration_19.py

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

docs/examples/usage/test_configuration_20.py

@@ -2,8 +2,11 @@
 
 
 def test_manual_pool() -> None:
+    import os
+
     from sqlspec.adapters.asyncpg import AsyncpgConfig
 
-    pool = {"dsn": "postgresql://localhost/db", "min_size": 10, "max_size": POOL_INSTANCE}
+    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