fix(oracle): automatic CLOB hydration for msgspec integration (#140)

Adds automatic CLOB-to-string conversion in Oracle adapter to enable seamless msgspec/Pydantic integration. CLOB handles are now read automatically before schema conversion, eliminating the need for `DBMS_LOB.SUBSTR` workarounds.

Author: cofin

AGENTS.md

@@ -619,6 +619,230 @@ async def test_numpy_vector_roundtrip(oracle_session):
 - Test against actual databases using the docker infrastructure
 - The SQL builder API is experimental and will change significantly
 
+## LOB (Large Object) Hydration Pattern
+
+### Overview
+
+Some database drivers (Oracle, PostgreSQL with large objects) return handle objects for large data types that must be explicitly read before use. SQLSpec provides automatic hydration to ensure typed schemas receive concrete Python values.
+
+### When to Use LOB Hydration
+
+Use LOB hydration helpers when:
+
+- Database driver returns handle objects (LOB, AsyncLOB) instead of concrete values
+- Typed schemas (msgspec, Pydantic) expect concrete types (str, bytes, dict)
+- Users would otherwise need manual workarounds (`DBMS_LOB.SUBSTR`)
+
+### Implementation Pattern
+
+**Step 1: Create Hydration Helpers**
+
+Add helpers in the adapter's `driver.py` to read LOB handles:
+
+```python
+def _coerce_sync_row_values(row: "tuple[Any, ...]") -> "list[Any]":
+    """Coerce LOB handles to concrete values for synchronous execution.
+
+    Processes each value in the row, reading LOB objects and applying
+    type detection for JSON values stored in CLOBs.
+
+    Args:
+        row: Tuple of column values from database fetch.
+
+    Returns:
+        List of coerced values with LOBs read to strings/bytes.
+    """
+    coerced_values: list[Any] = []
+    for value in row:
+        if hasattr(value, "read"):  # Duck-typing for LOB detection
+            try:
+                processed_value = value.read()
+            except Exception:
+                coerced_values.append(value)
+                continue
+            if isinstance(processed_value, str):
+                processed_value = _type_converter.convert_if_detected(processed_value)
+            coerced_values.append(processed_value)
+        else:
+            coerced_values.append(value)
+    return coerced_values
+
+
+async def _coerce_async_row_values(row: "tuple[Any, ...]") -> "list[Any]":
+    """Coerce LOB handles to concrete values for asynchronous execution.
+
+    Processes each value in the row, reading LOB objects asynchronously
+    and applying type detection for JSON values stored in CLOBs.
+
+    Args:
+        row: Tuple of column values from database fetch.
+
+    Returns:
+        List of coerced values with LOBs read to strings/bytes.
+    """
+    coerced_values: list[Any] = []
+    for value in row:
+        if hasattr(value, "read"):
+            try:
+                processed_value = await _type_converter.process_lob(value)
+            except Exception:
+                coerced_values.append(value)
+                continue
+            if isinstance(processed_value, str):
+                processed_value = _type_converter.convert_if_detected(processed_value)
+            coerced_values.append(processed_value)
+        else:
+            coerced_values.append(value)
+    return coerced_values
+```
+
+**Step 2: Integrate into Execution Path**
+
+Call hydration helpers before dict construction in `_execute_statement`:
+
+```python
+# Sync driver
+async for row in cursor:
+    coerced = _coerce_sync_row_values(row)
+    rows.append(dict(zip(columns, coerced)))
+
+# Async driver
+async for row in cursor:
+    coerced = await _coerce_async_row_values(row)
+    rows.append(dict(zip(columns, coerced)))
+```
+
+### Key Design Principles
+
+**Duck-Typing for LOB Detection**:
+
+- Use `hasattr(value, "read")` to detect LOB handles
+- This is appropriate duck-typing, NOT defensive programming
+- Avoids importing driver-specific types
+
+**Error Handling**:
+
+- Catch exceptions during LOB reading
+- Fall back to original value on error
+- Prevents breaking queries with unexpected handle types
+
+**Type Detection After Reading**:
+
+- Apply `convert_if_detected()` to string results
+- Enables JSON detection for JSON-in-CLOB scenarios
+- Preserves binary data (bytes) without conversion
+
+**Separation of Concerns**:
+
+- Hydration happens at result-fetching layer
+- Type conversion handled by existing type converter
+- Schema conversion remains unchanged
+
+### Testing Requirements
+
+**Integration Tests** - Test with real database and typed schemas:
+
+```python
+import msgspec
+
+class Article(msgspec.Struct):
+    id: int
+    content: str  # CLOB column
+
+async def test_clob_msgspec_hydration(session):
+    large_text = "x" * 5000  # >4KB to ensure CLOB
+    await session.execute(
+        "INSERT INTO articles (id, content) VALUES (:1, :2)",
+        (1, large_text)
+    )
+
+    result = await session.execute(
+        "SELECT id, content FROM articles WHERE id = :1",
+        (1,)
+    )
+
+    article = result.get_first(schema_type=Article)
+    assert isinstance(article.content, str)
+    assert article.content == large_text
+```
+
+**Test Coverage Areas**:
+
+1. Basic CLOB/text LOB hydration to string
+2. BLOB/binary LOB hydration to bytes
+3. JSON detection in CLOB content
+4. Mixed CLOB and regular columns
+5. Multiple LOB columns in one row
+6. NULL/empty LOB handling
+7. Both sync and async drivers
+
+### Performance Considerations
+
+**Memory Usage**:
+
+- LOBs are fully materialized into memory
+- Document limitations for very large LOBs (>100MB)
+- Consider pagination for multi-GB LOBs
+
+**Sync vs Async**:
+
+- Sync uses `.read()` directly
+- Async uses `await` for LOB reading
+- Both approaches have equivalent performance
+
+### Examples from Existing Adapters
+
+**Oracle CLOB Hydration** (`oracledb/driver.py`):
+
+- Automatically reads CLOB handles to strings
+- Preserves BLOB as bytes
+- Enables JSON detection for JSON-in-CLOB
+- No configuration required - always enabled
+- Eliminates need for `DBMS_LOB.SUBSTR` workaround
+
+### Documentation Requirements
+
+When implementing LOB hydration:
+
+1. **Update adapter guide** - Document new behavior and before/after comparison
+2. **Add examples** - Show typed schema usage without manual workarounds
+3. **Note performance** - Mention memory considerations for large LOBs
+4. **Show JSON detection** - Demonstrate automatic JSON parsing in LOBs
+
+Example documentation structure:
+
+```markdown
+## CLOB/BLOB Handling
+
+### Automatic CLOB Hydration
+
+CLOB values are automatically read and converted to Python strings:
+
+[Example with msgspec]
+
+### JSON Detection in CLOBs
+
+[Example showing JSON parsing]
+
+### BLOB Handling (Binary Data)
+
+BLOB columns remain as bytes:
+
+[Example with bytes]
+
+### Before and After
+
+**Before (manual workaround):**
+[SQL with DBMS_LOB.SUBSTR]
+
+**After (automatic):**
+[Clean SQL without workarounds]
+
+### Performance Considerations
+- Memory usage notes
+- When to use pagination
+```
+
 ## driver_features Pattern
 
 ### Overview

docs/guides/adapters/oracle.md

@@ -102,6 +102,122 @@ If `use_in_memory=True` but In-Memory is not available/licensed, table creation
 
 **Recommendation:** Use `use_in_memory=False` (default) unless you have confirmed licensing and configuration.
 
+## CLOB/BLOB Handling
+
+Oracle's `oracledb` driver returns LOB (Large Object) handles for CLOB and BLOB columns, which must be read before use. SQLSpec **automatically reads CLOB columns into strings** to provide seamless integration with typed schemas like msgspec and Pydantic.
+
+### Automatic CLOB Hydration
+
+CLOB values are automatically read and converted to Python strings:
+
+```python
+from sqlspec.adapters.oracledb import OracleAsyncConfig
+import msgspec
+
+class Article(msgspec.Struct):
+    id: int
+    title: str
+    content: str  # CLOB column automatically becomes string
+
+config = OracleAsyncConfig(pool_config={"dsn": "oracle://..."})
+
+async with config.provide_session() as session:
+    # Insert large text content
+    large_text = "x" * 5000  # >4KB content
+    await session.execute(
+        "INSERT INTO articles (id, title, content) VALUES (:1, :2, :3)",
+        (1, "My Article", large_text)
+    )
+
+    # Query returns string, not LOB handle
+    result = await session.execute(
+        "SELECT id, title, content FROM articles WHERE id = :1",
+        (1,)
+    )
+
+    # Works seamlessly with msgspec
+    article = result.get_first(schema_type=Article)
+    assert isinstance(article.content, str)
+    assert len(article.content) == 5000
+```
+
+### JSON Detection in CLOBs
+
+When CLOB content contains JSON, it is automatically detected and parsed into Python dictionaries:
+
+```python
+import json
+
+class Document(msgspec.Struct):
+    id: int
+    metadata: dict  # JSON stored in CLOB
+
+# Store JSON in CLOB
+metadata = {"key": "value", "nested": {"data": "example"}}
+await session.execute(
+    "INSERT INTO documents (id, metadata) VALUES (:1, :2)",
+    (1, json.dumps(metadata))
+)
+
+# Retrieved as parsed dict, not string
+result = await session.execute(
+    "SELECT id, metadata FROM documents WHERE id = :1",
+    (1,)
+)
+doc = result.get_first(schema_type=Document)
+assert isinstance(doc.metadata, dict)
+assert doc.metadata["key"] == "value"
+```
+
+### BLOB Handling (Binary Data)
+
+BLOB columns remain as bytes and are not converted to strings:
+
+```python
+class FileRecord(msgspec.Struct):
+    id: int
+    data: bytes  # BLOB column remains bytes
+
+binary_data = b"\x00\x01\x02\x03" * 2000
+await session.execute(
+    "INSERT INTO files (id, data) VALUES (:1, :2)",
+    (1, binary_data)
+)
+
+result = await session.execute(
+    "SELECT id, data FROM files WHERE id = :1",
+    (1,)
+)
+file_record = result.get_first(schema_type=FileRecord)
+assert isinstance(file_record.data, bytes)
+```
+
+### Before and After
+
+**Before (manual workaround required):**
+
+```python
+# Had to use DBMS_LOB.SUBSTR, truncating to 4000 chars
+result = await session.execute(
+    "SELECT id, DBMS_LOB.SUBSTR(content, 4000) as content FROM articles"
+)
+```
+
+**After (automatic, no truncation):**
+
+```python
+# CLOB automatically read to full string
+result = await session.execute(
+    "SELECT id, content FROM articles"
+)
+```
+
+### Performance Considerations
+
+- **Memory usage:** Large CLOBs (>100MB) are fully materialized into memory. For multi-GB CLOBs, consider using database-side processing or pagination.
+- **Sync vs Async:** Both sync and async drivers perform automatic CLOB hydration with equivalent performance.
+- **Multiple CLOBs:** All CLOB columns in a result row are hydrated automatically.
+
 ## Column Name Normalization
 
 Oracle returns unquoted identifiers in uppercase (for example `ID`, `PRODUCT_NAME`). When those rows feed into schema libraries that expect snake_case fields, the uppercase keys can trigger validation errors. SQLSpec resolves this automatically through the `enable_lowercase_column_names` driver feature, which is **enabled by default**.