feat(architecture): major database adapter refactoring

- Refactor database adapter architecture for better modularity
- Add dedicated adapters for PostgreSQL, SQLite, and StarRocks
- Enhance session management and connection handling
- Update documentation and examples

Author: HosseinNejatiJavaremi

archipy/adapters/orm/__init__.py archipy/adapters/base/__init__.pyarchipy/adapters/orm/__init__.py renamed to archipy/adapters/base/__init__.py

@@ -16,7 +16,7 @@
 AnyExecuteParams = _CoreMultiExecuteParams | _CoreSingleExecuteParams
 
 
-class SqlAlchemyPort:
+class SQLAlchemyPort:
     """Abstract interface defining synchronous SQLAlchemy database operations.
 
     This interface defines the contract that all synchronous SQLAlchemy adapters must
@@ -139,7 +139,7 @@ def scalars(self, statement: Executable, params: AnyExecuteParams | None = None)
         raise NotImplementedError
 
 
-class AsyncSqlAlchemyPort:
+class AsyncSQLAlchemyPort:
     """Abstract interface defining asynchronous SQLAlchemy database operations.
 
     This interface defines the contract that all asynchronous SQLAlchemy adapters must

…hipy/adapters/orm/sqlalchemy/__init__.py …ipy/adapters/base/sqlalchemy/__init__.pyarchipy/adapters/orm/sqlalchemy/__init__.py renamed to archipy/adapters/base/sqlalchemy/__init__.py archipy/adapters/orm/sqlalchemy/__init__.py renamed to archipy/adapters/base/sqlalchemy/__init__.py

@@ -14,21 +14,6 @@ class SessionManagerPort:
     Implementing classes must provide mechanisms to:
     1. Retrieve a properly configured SQLAlchemy session
     2. Release/remove sessions when they're no longer needed
-
-    Examples:
-        >>> from archipy.adapters.orm.sqlalchemy.session_manager_ports import SessionManagerPort
-        >>>
-        >>> class CustomSessionManager(SessionManagerPort):
-        ...     def __init__(self):
-        ...         # Initialize session factory
-        ...         self._session_factory = create_session_factory()
-        ...
-        ...     def get_session(self) -> Session:
-        ...         return self._session_factory()
-        ...
-        ...     def remove_session(self) -> None:
-        ...         # Cleanup logic
-        ...         pass
     """
 
     @abstractmethod
@@ -54,13 +39,6 @@ def remove_session(self) -> None:
         This method should be called to clean up the session when it's
         no longer needed, helping to prevent resource leaks and ensure
         proper session management.
-
-        Examples:
-            >>> try:
-            ...     session = session_manager.get_session()
-            ...     # Perform database operations
-            ... finally:
-            ...     session_manager.remove_session()
         """
         raise NotImplementedError
 
@@ -75,21 +53,6 @@ class AsyncSessionManagerPort:
     Implementing classes must provide mechanisms to:
     1. Retrieve a properly configured asynchronous SQLAlchemy session
     2. Release/remove sessions asynchronously when they're no longer needed
-
-    Examples:
-        >>> from archipy.adapters.orm.sqlalchemy.session_manager_ports import AsyncSessionManagerPort
-        >>>
-        >>> class CustomAsyncSessionManager(AsyncSessionManagerPort):
-        ...     def __init__(self):
-        ...         # Initialize async session factory
-        ...         self._session_factory = create_async_session_factory()
-        ...
-        ...     def get_session(self) -> AsyncSession:
-        ...         return self._session_factory()
-        ...
-        ...     async def remove_session(self) -> None:
-        ...         # Async cleanup logic
-        ...         await self._session_factory.remove()
     """
 
     @abstractmethod
@@ -101,11 +64,6 @@ def get_session(self) -> AsyncSession:
 
         Returns:
             AsyncSession: An asynchronous SQLAlchemy session object
-
-        Examples:
-            >>> session = session_manager.get_session()
-            >>> results = await session.execute(select(User))
-            >>> users = results.scalars().all()
         """
         raise NotImplementedError
 
@@ -116,12 +74,5 @@ async def remove_session(self) -> None:
         This method should be called to clean up the session when it's
         no longer needed, helping to prevent resource leaks and ensure
         proper session management in async contexts.
-
-        Examples:
-            >>> try:
-            ...     session = session_manager.get_session()
-            ...     # Perform async database operations
-            ... finally:
-            ...     await session_manager.remove_session()
         """
         raise NotImplementedError

…hipy/adapters/orm/sqlalchemy/adapters.py …ipy/adapters/base/sqlalchemy/adapters.pyarchipy/adapters/orm/sqlalchemy/adapters.py renamed to archipy/adapters/base/sqlalchemy/adapters.py archipy/adapters/orm/sqlalchemy/adapters.py renamed to archipy/adapters/base/sqlalchemy/adapters.py

@@ -0,0 +1,81 @@
+from typing import TYPE_CHECKING
+
+from archipy.models.errors import InternalError
+
+if TYPE_CHECKING:
+    from archipy.adapters.base.sqlalchemy.session_manager_ports import AsyncSessionManagerPort, SessionManagerPort
+
+
+class SessionManagerRegistry:
+    """Registry for SQLAlchemy session managers.
+
+    This registry provides a centralized access point for both synchronous and
+    asynchronous session managers, implementing the Service Locator pattern.
+
+    Subclasses should override get_sync_manager and get_async_manager to provide
+    concrete session managers, or use set_sync_manager and set_async_manager to
+    register managers manually.
+
+    Examples:
+        >>> from archipy.adapters.postgres.sqlalchemy.session_manager_registry import PostgresSessionManagerRegistry
+        >>> sync_manager = PostgresSessionManagerRegistry.get_sync_manager()
+        >>> session = sync_manager.get_session()
+    """
+
+    _sync_instance = None
+    _async_instance = None
+
+    @classmethod
+    def get_sync_manager(cls) -> "SessionManagerPort":
+        """Get the synchronous session manager instance.
+
+        Returns:
+            SessionManagerPort: The registered synchronous session manager
+
+        Raises:
+            InternalError: If no synchronous session manager is set
+        """
+        if cls._sync_instance is None:
+            raise InternalError("Synchronous session manager not initialized")
+        return cls._sync_instance
+
+    @classmethod
+    def set_sync_manager(cls, manager: "SessionManagerPort") -> None:
+        """Set a custom synchronous session manager.
+
+        Args:
+            manager: An instance implementing SessionManagerPort
+        """
+        cls._sync_instance = manager
+
+    @classmethod
+    def get_async_manager(cls) -> "AsyncSessionManagerPort":
+        """Get the asynchronous session manager instance.
+
+        Returns:
+            AsyncSessionManagerPort: The registered asynchronous session manager
+
+        Raises:
+            InternalError: If no asynchronous session manager is set
+        """
+        if cls._async_instance is None:
+            raise InternalError("Asynchronous session manager not initialized")
+        return cls._async_instance
+
+    @classmethod
+    def set_async_manager(cls, manager: "AsyncSessionManagerPort") -> None:
+        """Set a custom asynchronous session manager.
+
+        Args:
+            manager: An instance implementing AsyncSessionManagerPort
+        """
+        cls._async_instance = manager
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the registry to its initial state.
+
+        This method clears both registered managers, useful for testing.
+        """
+        cls._sync_instance = None
+        cls._async_instance = None