Merge Feature 051: Simplify IRIS Connection Architecture

- Reduce architecture from 6 components to 1-2 modules
- Single-call API: get_iris_connection() with caching
- Automatic edition detection (Community vs Enterprise)
- Thread-safe module-level connection caching
- Optional IRISConnectionPool for high-concurrency scenarios
- Backward compatibility via deprecation warnings
- 100% test coverage (12 contract + integration tests)
- Zero breaking changes confirmed

Author: tom-dyar

iris_vector_rag/common/connection_manager.py

@@ -1,26 +1,47 @@
 """
 Centralized connection manager for RAG pipelines
 Handles JDBC, ODBC, and future dbapi connections with a unified interface
+
+DEPRECATED: This module is deprecated as of Feature 051 (Simplify IRIS Connection).
+Use iris_vector_rag.common.get_iris_connection() instead for simple connections,
+or iris_vector_rag.common.IRISConnectionPool() for pooling.
+See specs/051-simplify-iris-connection/quickstart.md for migration guide.
 """
 
 import logging
 import os
+import warnings
 from contextlib import contextmanager
 from typing import Any, List, Optional
 
 logger = logging.getLogger(__name__)
 
 
 class ConnectionManager:
-    """Manages database connections for RAG pipelines"""
+    """
+    Manages database connections for RAG pipelines
+
+    DEPRECATED: Use get_iris_connection() or IRISConnectionPool instead.
+    """
 
     def __init__(self, connection_type: str = "odbc"):
         """
         Initialize connection manager
 
         Args:
             connection_type: Either "jdbc", "odbc", or "dbapi" (default: "odbc" for stability)
+
+        DEPRECATED: This class is deprecated. Use get_iris_connection() instead:
+            from iris_vector_rag.common import get_iris_connection
+            conn = get_iris_connection()
         """
+        warnings.warn(
+            "ConnectionManager is deprecated as of Feature 051. "
+            "Use get_iris_connection() for simple connections or IRISConnectionPool for pooling. "
+            "See specs/051-simplify-iris-connection/quickstart.md for migration guide.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.connection_type = connection_type.lower()
         self._connection = None
         self._cursor = None
@@ -37,7 +58,9 @@ def connect(self):
 
         if self.connection_type == "jdbc":
             try:
-                from iris_vector_rag.common.iris_connection_manager import get_iris_jdbc_connection
+                from iris_vector_rag.common.iris_connection_manager import (
+                    get_iris_jdbc_connection,
+                )
 
                 self._connection = get_iris_jdbc_connection()
                 logger.info("Established JDBC connection")
@@ -48,7 +71,9 @@ def connect(self):
 
         elif self.connection_type == "dbapi":
             try:
-                from iris_vector_rag.common.iris_dbapi_connector import get_iris_dbapi_connection
+                from iris_vector_rag.common.iris_dbapi_connector import (
+                    get_iris_dbapi_connection,
+                )
 
                 self._connection = get_iris_dbapi_connection()
                 if not self._connection:  # If get_iris_dbapi_connection returns None

iris_vector_rag/common/exceptions.py

@@ -0,0 +1,75 @@
+"""
+Custom exceptions for IRIS connection management.
+
+This module defines the exception hierarchy for the unified IRIS connection module,
+providing clear, actionable error messages for connection failures.
+"""
+
+
+class ValidationError(ValueError):
+    """
+    Raised when connection parameters fail validation before connection attempt.
+
+    This exception is raised during parameter validation (before any connection
+    attempt), providing immediate feedback on invalid configuration.
+
+    Attributes:
+        parameter_name: Name of the parameter that failed validation
+        invalid_value: The value that was rejected
+        valid_range: Description of acceptable values
+        message: Full error message with actionable guidance
+
+    Example:
+        >>> raise ValidationError(
+        ...     parameter_name="port",
+        ...     invalid_value=99999,
+        ...     valid_range="1-65535",
+        ...     message="Invalid port 99999: must be between 1-65535"
+        ... )
+    """
+
+    def __init__(
+        self, parameter_name: str, invalid_value, valid_range: str, message: str
+    ):
+        self.parameter_name = parameter_name
+        self.invalid_value = invalid_value
+        self.valid_range = valid_range
+        super().__init__(message)
+
+
+class ConnectionLimitError(RuntimeError):
+    """
+    Raised when IRIS Community Edition connection limit is reached.
+
+    This exception is raised when attempting to create more connections than
+    allowed by the detected IRIS edition (typically 1 for Community Edition).
+
+    Attributes:
+        current_limit: Maximum connections allowed for detected edition
+        suggested_actions: List of actionable suggestions for resolving the issue
+        message: Full error message with context and suggestions
+
+    Example:
+        >>> raise ConnectionLimitError(
+        ...     current_limit=1,
+        ...     suggested_actions=[
+        ...         "Use connection queuing with IRISConnectionPool",
+        ...         "Run tests serially with pytest -n 0",
+        ...         "Set IRIS_BACKEND_MODE=community explicitly"
+        ...     ],
+        ...     message="IRIS Community Edition connection limit (1) reached. Consider: ..."
+        ... )
+    """
+
+    def __init__(self, current_limit: int, suggested_actions: list[str], message: str):
+        self.current_limit = current_limit
+        self.suggested_actions = suggested_actions
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        """Format error message with suggested actions."""
+        base_message = super().__str__()
+        if self.suggested_actions:
+            actions = "\n  - ".join(self.suggested_actions)
+            return f"{base_message}\n\nSuggested actions:\n  - {actions}"
+        return base_message