fix: named parameter handling, thread local pooling & typing config (#52)

fix: bind parametr handling
fix: typing updates for litestar
feat: `sqlite` Thread local pool cleanup
feat: corrected `aiosqlite` pooler
feat: corrected thread safe `duckdb` pooler

Author: cofin

docs/examples/adbc_example.py

@@ -0,0 +1,114 @@
+"""Example demonstrating ADBC driver usage with query mixins.
+
+This example shows how to use the ADBC (Arrow Database Connectivity) driver
+with the development PostgreSQL container started by `make infra-up`.
+"""
+
+from sqlspec import SQLSpec
+from sqlspec.adapters.adbc import AdbcConfig
+from sqlspec.builder import Select
+
+__all__ = ("adbc_example", "main")
+
+
+def adbc_example() -> None:
+    """Demonstrate ADBC database driver usage with query mixins."""
+    # Create SQLSpec instance with ADBC (connects to dev PostgreSQL container)
+    spec = SQLSpec()
+    config = AdbcConfig(connection_config={"uri": "postgresql://postgres:postgres@localhost:5433/postgres"})
+    spec.add_config(config)
+
+    # Get a driver directly (drivers now have built-in query methods)
+    with spec.provide_session(config) as driver:
+        # Create a table
+        driver.execute("""
+            CREATE TABLE IF NOT EXISTS analytics_data (
+                id SERIAL PRIMARY KEY,
+                metric_name TEXT NOT NULL,
+                metric_value DOUBLE PRECISION NOT NULL,
+                dimensions JSONB,
+                recorded_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+
+        # Clean up any existing data
+        driver.execute("TRUNCATE TABLE analytics_data RESTART IDENTITY")
+
+        # Insert data
+        driver.execute(
+            "INSERT INTO analytics_data (metric_name, metric_value, dimensions) VALUES ($1, $2, $3::jsonb)",
+            "page_views",
+            1250.0,
+            '{"source": "organic", "device": "desktop"}',
+        )
+
+        # Insert multiple rows
+        driver.execute_many(
+            "INSERT INTO analytics_data (metric_name, metric_value, dimensions) VALUES ($1, $2, $3::jsonb)",
+            [
+                ("conversion_rate", 0.045, '{"funnel": "signup", "campaign": "summer"}'),
+                ("revenue", 15420.50, '{"product": "pro", "region": "us"}'),
+                ("bounce_rate", 0.32, '{"page": "landing", "source": "paid"}'),
+                ("session_duration", 180.5, '{"device": "mobile", "browser": "chrome"}'),
+            ],
+        )
+
+        # Select all metrics using query mixin
+        metrics = driver.select("SELECT * FROM analytics_data ORDER BY recorded_at")
+        print(f"All metrics: {metrics}")
+
+        # Select one metric using query mixin
+        revenue = driver.select_one("SELECT * FROM analytics_data WHERE metric_name = $1", "revenue")
+        print(f"Revenue metric: {revenue}")
+
+        # Select one or none (no match) using query mixin
+        nothing = driver.select_one_or_none("SELECT * FROM analytics_data WHERE metric_name = $1", "nothing")
+        print(f"Nothing: {nothing}")
+
+        # Select scalar value using query mixin
+        avg_value = driver.select_value("SELECT AVG(metric_value) FROM analytics_data WHERE metric_value > $1", 1.0)
+        print(f"Average metric value: {avg_value:.2f}")
+
+        # Update
+        result = driver.execute(
+            "UPDATE analytics_data SET dimensions = $1::jsonb WHERE metric_name = $2",
+            '{"updated": true}',
+            "bounce_rate",
+        )
+        print(f"Updated {result.rows_affected} bounce rate records")
+
+        # Delete
+        result = driver.execute("DELETE FROM analytics_data WHERE metric_value < $1", 1.0)
+        print(f"Removed {result.rows_affected} low-value metrics")
+
+        # Use query builder with driver - this demonstrates the QueryBuilder parameter fix
+        query = Select("*").from_("analytics_data").where("metric_name = $1")
+        page_view_metrics = driver.select(query, "page_views")
+        print(f"Page view metrics: {page_view_metrics}")
+
+        # JSON operations (PostgreSQL-specific) - using raw SQL due to SQLGlot JSON operator conversion
+        mobile_metrics = driver.select(
+            "SELECT metric_name, metric_value, dimensions->>'device' as device FROM analytics_data WHERE dimensions->>'device' = $1",
+            "mobile",
+        )
+        print(f"Mobile metrics: {mobile_metrics}")
+
+        # Demonstrate pagination
+        page_metrics = driver.select("SELECT * FROM analytics_data ORDER BY metric_value DESC LIMIT $1 OFFSET $2", 2, 0)
+        total_count = driver.select_value("SELECT COUNT(*) FROM analytics_data")
+        print(f"Page 1: {page_metrics}, Total: {total_count}")
+
+
+def main() -> None:
+    """Run ADBC example."""
+    print("=== ADBC (Arrow Database Connectivity) Driver Example ===")
+    try:
+        adbc_example()
+        print("✅ ADBC example completed successfully!")
+    except Exception as e:
+        print(f"❌ ADBC example failed: {e}")
+        print("Make sure PostgreSQL is running with: make infra-up")
+
+
+if __name__ == "__main__":
+    main()

docs/examples/aiosqlite_example.py

@@ -0,0 +1,84 @@
+# type: ignore
+"""Example demonstrating AIOSQLite driver usage with query mixins.
+
+This example shows how to use the AIOSQLite driver directly with its built-in query
+mixin functionality for common database operations.
+"""
+
+import asyncio
+
+from sqlspec import SQLSpec
+from sqlspec.adapters.aiosqlite import AiosqliteConfig
+from sqlspec.builder import Select
+
+__all__ = ("aiosqlite_example", "main")
+
+
+async def aiosqlite_example() -> None:
+    """Demonstrate asynchronous database driver usage with query mixins."""
+    # Create SQLSpec instance with AIOSQLite
+    spec = SQLSpec()
+    config = AiosqliteConfig(pool_config={"database": ":memory:"})
+    conf = spec.add_config(config)
+
+    # Get an async driver directly (drivers now have built-in query methods)
+    async with spec.provide_session(conf) as driver:
+        # Create a table
+        await driver.execute("""
+            CREATE TABLE products (
+                id INTEGER PRIMARY KEY,
+                name TEXT NOT NULL,
+                price REAL NOT NULL
+            )
+        """)
+
+        # Insert data
+        await driver.execute("INSERT INTO products (name, price) VALUES (?, ?)", "Laptop", 999.99)
+
+        # Insert multiple rows
+        await driver.execute_many(
+            "INSERT INTO products (name, price) VALUES (?, ?)",
+            [("Mouse", 29.99), ("Keyboard", 79.99), ("Monitor", 299.99)],
+        )
+
+        # Select all products using query mixin
+        products = await driver.select("SELECT * FROM products ORDER BY price")
+        print(f"All products: {products}")
+
+        # Select one product using query mixin
+        laptop = await driver.select_one("SELECT * FROM products WHERE name = ?", "Laptop")
+        print(f"Laptop: {laptop}")
+
+        # Select scalar value using query mixin
+        avg_price = await driver.select_value("SELECT AVG(price) FROM products")
+        print(f"Average price: ${avg_price:.2f}")
+
+        # Update
+        result = await driver.execute("UPDATE products SET price = price * 0.9 WHERE price > ?", 100.0)
+        print(f"Applied 10% discount to {result.rows_affected} expensive products")
+
+        # Use query builder with async driver
+        query = Select("name", "price").from_("products").where("price < ?").order_by("price")
+        cheap_products = await driver.select(query, 100.0)
+        print(f"Cheap products: {cheap_products}")
+
+        # Demonstrate pagination
+        page_products = await driver.select("SELECT * FROM products ORDER BY price LIMIT ? OFFSET ?", 2, 1)
+        total_count = await driver.select_value("SELECT COUNT(*) FROM products")
+        print(f"Products page 2: {len(page_products)} items, Total: {total_count}")
+
+
+async def main_async() -> None:
+    """Run AIOSQLite example with proper cleanup."""
+    print("=== AIOSQLite Driver Example ===")
+    await aiosqlite_example()
+    print("✅ AIOSQLite example completed successfully!")
+
+
+def main() -> None:
+    """Run AIOSQLite example."""
+    asyncio.run(main_async())
+
+
+if __name__ == "__main__":
+    main()

docs/examples/asyncmy_example.py

@@ -0,0 +1,115 @@
+"""Example demonstrating asyncmy driver usage with query mixins.
+
+This example shows how to use the asyncmy driver with the development MySQL
+container started by `make infra-up`.
+"""
+
+import asyncio
+
+from sqlspec import SQLSpec
+from sqlspec.adapters.asyncmy import AsyncmyConfig
+from sqlspec.builder import Select
+
+__all__ = ("asyncmy_example", "main")
+
+
+async def asyncmy_example() -> None:
+    """Demonstrate asyncmy database driver usage with query mixins."""
+    # Create SQLSpec instance with MySQL (connects to dev container)
+    spec = SQLSpec()
+    config = AsyncmyConfig(
+        pool_config={"host": "localhost", "port": 3307, "user": "root", "password": "mysql", "database": "test"}
+    )
+    spec.add_config(config)
+
+    # Get a driver directly (drivers now have built-in query methods)
+    async with spec.provide_session(config) as driver:
+        # Create a table
+        await driver.execute("""
+            CREATE TABLE IF NOT EXISTS inventory (
+                id INT AUTO_INCREMENT PRIMARY KEY,
+                item_name VARCHAR(255) NOT NULL,
+                quantity INT NOT NULL,
+                price DECIMAL(10,2) NOT NULL,
+                supplier VARCHAR(255)
+            )
+        """)
+
+        # Clean up any existing data
+        await driver.execute("TRUNCATE TABLE inventory")
+
+        # Insert data
+        await driver.execute(
+            "INSERT INTO inventory (item_name, quantity, price, supplier) VALUES (%s, %s, %s, %s)",
+            "Laptop",
+            50,
+            1299.99,
+            "TechCorp",
+        )
+
+        # Insert multiple rows
+        await driver.execute_many(
+            "INSERT INTO inventory (item_name, quantity, price, supplier) VALUES (%s, %s, %s, %s)",
+            [
+                ("Mouse", 200, 25.99, "TechCorp"),
+                ("Keyboard", 150, 89.99, "TechCorp"),
+                ("Monitor", 75, 399.99, "DisplayCo"),
+                ("Headphones", 100, 159.99, "AudioPlus"),
+            ],
+        )
+
+        # Select all items using query mixin
+        items = await driver.select("SELECT * FROM inventory ORDER BY price")
+        print(f"All inventory: {items}")
+
+        # Select one item using query mixin
+        laptop = await driver.select_one("SELECT * FROM inventory WHERE item_name = %s", "Laptop")
+        print(f"Laptop: {laptop}")
+
+        # Select one or none (no match) using query mixin
+        nothing = await driver.select_one_or_none("SELECT * FROM inventory WHERE item_name = %s", "Nothing")
+        print(f"Nothing: {nothing}")
+
+        # Select scalar value using query mixin
+        total_value = await driver.select_value("SELECT SUM(quantity * price) FROM inventory")
+        print(f"Total inventory value: ${total_value:.2f}")
+
+        # Update
+        result = await driver.execute(
+            "UPDATE inventory SET quantity = quantity + %s WHERE supplier = %s", 10, "TechCorp"
+        )
+        print(f"Added stock for {result.rows_affected} TechCorp items")
+
+        # Delete
+        result = await driver.execute("DELETE FROM inventory WHERE quantity < %s", 80)
+        print(f"Removed {result.rows_affected} low-stock items")
+
+        # Use query builder with driver - this demonstrates the QueryBuilder parameter fix
+        query = Select("*").from_("inventory").where("supplier = %s")
+        techcorp_items = await driver.select(query, "TechCorp")
+        print(f"TechCorp items: {techcorp_items}")
+
+        # Query builder with comparison
+        query = Select("item_name", "price").from_("inventory").where("price > %s").order_by("price")
+        expensive_items = await driver.select(query, 200.0)
+        print(f"Expensive items: {expensive_items}")
+
+        # Demonstrate pagination
+        page_items = await driver.select("SELECT * FROM inventory ORDER BY item_name LIMIT %s OFFSET %s", 2, 0)
+        total_count = await driver.select_value("SELECT COUNT(*) FROM inventory")
+        print(f"Page 1: {page_items}, Total: {total_count}")
+
+
+def main() -> None:
+    """Run asyncmy example."""
+    print("=== asyncmy Driver Example ===")
+    try:
+        asyncio.run(asyncmy_example())
+        print("✅ asyncmy example completed successfully!")
+    except Exception as e:
+        print(f"❌ asyncmy example failed: {e}")
+        print("Make sure MySQL is running with: make infra-up")
+
+
+if __name__ == "__main__":
+    main()