vs-db 0.1.0__py3-none-any.whl

vs_db/base/vs_audit_mixin.py

@@ -0,0 +1,22 @@
+from datetime import datetime
+
+from sqlalchemy import DateTime, event
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class AuditMixin:
+
+    created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+
+
+@event.listens_for(AuditMixin, "before_insert", propagate=True)
+def set_created_at(mapper, connection, target):
+    now = datetime.utcnow()
+    target.created_at = now
+    target.updated_at = now
+
+
+@event.listens_for(AuditMixin, "before_update", propagate=True)
+def set_updated_at(mapper, connection, target):
+    target.updated_at = datetime.utcnow()

vs_db/base/vs_db_base.py

@@ -0,0 +1,39 @@
+from sqlalchemy import inspect
+from sqlalchemy.orm import DeclarativeBase
+from datetime import datetime, date
+from decimal import Decimal
+from enum import Enum
+
+class VsDbBase(DeclarativeBase):
+    """
+    Shared declarative base for all Viveka entities.
+
+    All entity classes must inherit from VivekaBase so their table definitions
+    are registered in a single shared metadata object. This allows
+    VivekaDbBase.metadata.create_all(engine) to create every table in one call,
+    with correct dependency ordering for foreign keys.
+
+    Mapping is intentionally deferred: subclasses without __tablename__ in
+    their class body are marked __abstract__ so SQLAlchemy skips them.
+    The @table decorator sets __tablename__ and triggers mapping via
+    _as_declarative, preserving the Spring JPA-style decorator API.
+    """
+
+    @classmethod
+    def __init_subclass__(cls, **kwargs):
+        if '__tablename__' not in cls.__dict__:
+            cls.__abstract__ = True
+        super().__init_subclass__(**kwargs)
+
+    def to_dict(self) -> dict:
+        result = {}
+        for column in inspect(self).mapper.column_attrs:
+            value = getattr(self, column.key)
+            if isinstance(value, (datetime, date)):
+                value = value.isoformat()
+            elif isinstance(value, Decimal):
+                value = float(value)
+            elif isinstance(value, Enum):
+                value = value.value
+            result[column.key] = value
+        return result

vs_db/base/vs_db_repo.py

@@ -0,0 +1,132 @@
+from dataclasses import dataclass
+from typing import Any, Generic, List, Optional, Type, TypeVar, Union
+
+from sqlalchemy import select, func, exists, inspect, ColumnElement
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.dialects.mysql import insert as mysql_insert
+
+T = TypeVar('T')
+
+
+@dataclass
+class Page(Generic[T]):
+    items: List[T]
+    total: int
+    page: int
+    page_size: int
+    pages: int
+
+
+class VsDbRepo(Generic[T]):
+
+    def __init__(self, model_class: Type[T]):
+        self.model_class = model_class
+        self._db: Optional[AsyncSession] = None
+
+    @property
+    def db(self) -> Optional[AsyncSession]:
+        if self._db is not None:
+            return self._db
+        from vs_db.context.db_context import get_session, has_session
+        return get_session() if has_session() else None
+
+    @db.setter
+    def db(self, value: Optional[AsyncSession]):
+        self._db = value
+
+    async def create(self, entity: T) -> T:
+        self.db.add(entity)
+        await self.db.flush()
+        await self.db.refresh(entity)
+        return entity
+
+    async def insert_all(self, entities: List[T]) -> List[T]:
+        self.db.add_all(entities)
+        await self.db.flush()
+        return entities
+
+    async def get_by_id(self, id: Any) -> Optional[T]:
+        return await self.db.get(self.model_class, id)
+
+    async def get_all(self, skip: int = 0, limit: int = 100) -> List[T]:
+        result = await self.db.execute(
+            select(self.model_class).offset(skip).limit(limit)
+        )
+        return list(result.scalars().all())
+
+    async def get_page(self, page: int = 1, page_size: int = 20) -> Page[T]:
+        total = await self.count()
+        result = await self.db.execute(
+            select(self.model_class).offset((page - 1) * page_size).limit(page_size)
+        )
+        items = list(result.scalars().all())
+        return Page(
+            items=items,
+            total=total,
+            page=page,
+            page_size=page_size,
+            pages=(total + page_size - 1) // page_size,
+        )
+
+    async def update(self, entity: T) -> T:
+        merged = await self.db.merge(entity)
+        await self.db.flush()
+        return merged
+
+    async def delete(self, id: Any) -> bool:
+        entity = await self.get_by_id(id)
+        if entity:
+            await self.db.delete(entity)
+            await self.db.flush()
+            return True
+        return False
+
+    async def delete_entity(self, entity: T) -> bool:
+        await self.db.delete(entity)
+        await self.db.flush()
+        return True
+
+    async def soft_delete(self, id: Any) -> bool:
+        entity = await self.get_by_id(id)
+        if entity and hasattr(entity, 'deleted_at'):
+            from datetime import datetime
+            entity.deleted_at = datetime.utcnow()
+            await self.db.flush()
+            return True
+        return False
+
+    async def exists(self, id: Any) -> bool:
+        pk = inspect(self.model_class).mapper.primary_key[0]
+        result = await self.db.execute(select(exists().where(pk == id)))
+        return result.scalar()
+
+    async def count(self) -> int:
+        result = await self.db.execute(
+            select(func.count()).select_from(self.model_class)
+        )
+        return result.scalar()
+
+    async def find_by_field(self, field: ColumnElement, value: Any) -> Optional[T]:
+        result = await self.db.execute(
+            select(self.model_class).where(field == value)
+        )
+        return result.scalars().first()
+
+    async def find_all_by_field(self, field: ColumnElement, value: Any) -> List[T]:
+        result = await self.db.execute(
+            select(self.model_class).where(field == value)
+        )
+        return list(result.scalars().all())
+
+    async def upsert(self, entity: T, conflict_fields: List[str]) -> T:
+        data = {c.key: getattr(entity, c.key) for c in inspect(entity).mapper.column_attrs}
+        pk = inspect(self.model_class).mapper.primary_key[0].name
+        stmt = (
+            mysql_insert(self.model_class)
+            .values(**data)
+            .on_duplicate_key_update(**{k: v for k, v in data.items() if k != pk})
+        )
+        result = await self.db.execute(stmt)
+        await self.db.flush()
+        entity_id = result.lastrowid or data.get(pk)
+        return await self.get_by_id(entity_id)

vs_db/base/vs_soft_delete_mixin.py

@@ -0,0 +1,14 @@
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import DateTime
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class SoftDeleteMixin:
+
+    deleted_at: Mapped[Optional[datetime]] = mapped_column(DateTime, nullable=True, default=None)
+
+    @property
+    def is_deleted(self) -> bool:
+        return self.deleted_at is not None

vs_db/base/vs_version_mixin.py

@@ -0,0 +1,12 @@
+from sqlalchemy import Integer
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.orm import DeclarativeBaseNoMeta
+
+
+class VersionMixin:
+
+    version: Mapped[int] = mapped_column(Integer, nullable=False, default=1)
+
+    __mapper_args__ = {
+        "version_id_col": version,
+    }

vs_db/context/db_context.py

@@ -0,0 +1,39 @@
+from contextvars import ContextVar
+from typing import List, Optional
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+_db_session: ContextVar[Optional[AsyncSession]] = ContextVar('db_session', default=None)
+_pending_evictions: ContextVar[Optional[List[str]]] = ContextVar('pending_evictions', default=None)
+
+
+def get_session() -> AsyncSession:
+    session = _db_session.get()
+    if session is None:
+        raise RuntimeError(
+            "No database session in context. "
+            "Ensure DatabaseSessionFactory is initialized and VsDbMiddleware is registered."
+        )
+    return session
+
+
+def has_session() -> bool:
+    return _db_session.get() is not None
+
+
+def set_session(session: Optional[AsyncSession]) -> None:
+    _db_session.set(session)
+
+
+def init_pending_evictions() -> None:
+    _pending_evictions.set([])
+
+
+def add_pending_eviction(pattern: str) -> None:
+    evictions = _pending_evictions.get()
+    if evictions is not None:
+        evictions.append(pattern)
+
+
+def get_pending_evictions() -> List[str]:
+    return _pending_evictions.get() or []

vs_db/decorator/vs_db_decorator.py

@@ -0,0 +1,119 @@
+import asyncio
+import functools
+from enum import Enum
+from typing import Callable, List, Optional, Type, Tuple
+
+from vs_common.log.vs_log_manager import VsLogManager
+from vs_db.context.db_context import has_session, set_session
+from vs_db.transaction.vs_transaction_manager import VsTransactionManager
+
+_logger = VsLogManager.get_instance(__name__)
+
+_entity_registry: List[Type] = []
+
+
+def get_registered_entities() -> List[Type]:
+    return list(_entity_registry)
+
+
+def entity(table: str):
+    def decorator(cls):
+        from vs_db.base.vs_db_base import VsDbBase
+        if not issubclass(cls, VsDbBase):
+            raise TypeError(f"{cls.__name__} must inherit from VsDbBase")
+        cls.__tablename__ = table
+        if '__abstract__' in cls.__dict__:
+            del cls.__abstract__
+            from sqlalchemy.orm.decl_base import _as_declarative
+            _as_declarative(cls._sa_registry, cls, cls.__dict__)
+        cls._is_entity = True
+        _entity_registry.append(cls)
+        return cls
+    return decorator
+
+
+class Propagation(Enum):
+    REQUIRED = "REQUIRED"
+    REQUIRES_NEW = "REQUIRES_NEW"
+
+
+class Isolation(Enum):
+    DEFAULT = "DEFAULT"
+    READ_COMMITTED = "READ COMMITTED"
+    REPEATABLE_READ = "REPEATABLE READ"
+    SERIALIZABLE = "SERIALIZABLE"
+
+
+def transactional(
+    func: Optional[Callable] = None,
+    *,
+    propagation: Propagation = Propagation.REQUIRED,
+    isolation: Isolation = Isolation.DEFAULT,
+    rollback_on: Tuple[Type[Exception], ...] = (Exception,),
+):
+    def decorator(fn: Callable) -> Callable:
+
+        if asyncio.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(self, *args, **kwargs):
+                from vs_db.session.vs_db_session_factory import VsDbSessionFactory
+
+                if propagation == Propagation.REQUIRES_NEW:
+                    async with VsDbSessionFactory.get_instance().open_session() as new_session:
+                        previous = None
+                        if has_session():
+                            previous = VsTransactionManager.get_session()
+                        set_session(new_session)
+                        try:
+                            if isolation != Isolation.DEFAULT:
+                                await new_session.execute(
+                                    __import__('sqlalchemy').text(f"SET TRANSACTION ISOLATION LEVEL {isolation.value}")
+                                )
+                            self.db = new_session
+                            return await fn(self, *args, **kwargs)
+                        finally:
+                            set_session(previous)
+
+                if has_session():
+                    session = VsTransactionManager.get_session()
+                    self.db = session
+                    _logger.debug(f"[{fn.__qualname__}] Reusing request session (savepoint)")
+                    async with session.begin_nested():
+                        return await fn(self, *args, **kwargs)
+
+                _logger.info(f"[{fn.__qualname__}] No session in context — opening standalone session")
+                async with VsDbSessionFactory.get_instance().open_session() as session:
+                    set_session(session)
+                    try:
+                        if isolation != Isolation.DEFAULT:
+                            await session.execute(
+                                __import__('sqlalchemy').text(f"SET TRANSACTION ISOLATION LEVEL {isolation.value}")
+                            )
+                        self.db = session
+                        return await fn(self, *args, **kwargs)
+                    except rollback_on as e:
+                        _logger.error(f"[{fn.__qualname__}] Rolling back: {e}")
+                        raise
+                    finally:
+                        set_session(None)
+
+            return async_wrapper
+
+        else:
+
+            @functools.wraps(fn)
+            def sync_wrapper(self, *args, **kwargs):
+                if has_session():
+                    self.db = VsTransactionManager.get_session()
+                    return fn(self, *args, **kwargs)
+                raise RuntimeError(
+                    f"[{fn.__qualname__}] No session in context. "
+                    "Sync @transactional requires an active request session."
+                )
+
+            return sync_wrapper
+
+    if func is not None:
+        return decorator(func)
+    return decorator

vs_db/middleware/vs_db_middleware.py

@@ -0,0 +1,39 @@
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+
+from vs_common.log.vs_log_manager import VsLogManager
+from vs_db.context.db_context import set_session, init_pending_evictions, get_pending_evictions
+from vs_db.session.vs_db_session_factory import VsDbSessionFactory
+from vs_db.transaction.vs_transaction_manager import VsTransactionManager
+
+_logger = VsLogManager.get_instance(__name__)
+
+
+class VsDbMiddleware(BaseHTTPMiddleware):
+
+    def __init__(self, app):
+        super().__init__(app)
+        self._session_factory = VsDbSessionFactory.get_instance().session_factory
+        _logger.info("VsDbMiddleware initialized")
+
+    async def dispatch(self, request: Request, call_next):
+        session = self._session_factory()
+        set_session(session)
+        init_pending_evictions()
+        try:
+            response = await call_next(request)
+            await VsTransactionManager.commit()
+            await self._flush_evictions()
+            return response
+        except Exception as e:
+            _logger.error(f"Request failed, rolling back: {e}")
+            await VsTransactionManager.rollback()
+            raise
+        finally:
+            await session.close()
+            set_session(None)
+
+    async def _flush_evictions(self) -> None:
+        from vs_common.cache.vs_cache_manager import VsCacheManager
+        for pattern in get_pending_evictions():
+            await VsCacheManager.delete_pattern(pattern)

vs_db/session/vs_db_session_factory.py

@@ -0,0 +1,100 @@
+import re
+import threading
+from contextlib import asynccontextmanager
+from typing import Optional
+
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncEngine, AsyncSession
+
+from vs_common.log.vs_log_manager import VsLogManager
+from vs_common.config.vs_base_config import VsBaseConfig
+
+
+class VsDbSessionFactory:
+
+    _instance: Optional['VsDbSessionFactory'] = None
+    _initialized: bool = False
+    _lock: threading.RLock = threading.RLock()
+
+    def __new__(cls, config: VsBaseConfig):
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self, config: VsBaseConfig):
+        if VsDbSessionFactory._initialized:
+            return
+        with VsDbSessionFactory._lock:
+            if VsDbSessionFactory._initialized:
+                return
+            self._logger = VsLogManager.get_instance(__name__)
+            self._logger.info("Initializing VsDbSessionFactory...")
+            self._engine: AsyncEngine = self._create_engine(config)
+            self._session_factory = async_sessionmaker(
+                self._engine,
+                expire_on_commit=False,
+                class_=AsyncSession
+            )
+            VsDbSessionFactory._initialized = True
+            self._logger.info("VsDbSessionFactory ready")
+
+    @classmethod
+    def get_instance(cls) -> 'VsDbSessionFactory':
+        if cls._instance is None or not cls._initialized:
+            raise RuntimeError(
+                "VsDbSessionFactory is not initialized. "
+                "Call VsDbSessionFactory(config) at application startup."
+            )
+        return cls._instance
+
+    def _create_engine(self, config: VsBaseConfig) -> AsyncEngine:
+        db_url = config.get("database.url")
+        if not db_url:
+            raise ValueError(
+                "database.url not configured. "
+                "Set it in config.ini [database] section or DATABASE_URL environment variable."
+            )
+
+        masked_url = re.sub(r'://([^:]+):([^@]+)@', r'://\1:****@', db_url)
+        self._logger.info(f"Connecting to: {masked_url}")
+
+        pool_size    = config.get("database.pool_size",    default=10,    data_type=int)
+        max_overflow = config.get("database.max_overflow", default=20,    data_type=int)
+        echo         = config.get("database.echo",         default=False, data_type=bool)
+
+        self._logger.info(f"Pool — size: {pool_size}, max_overflow: {max_overflow}, echo: {echo}")
+
+        try:
+            engine = create_async_engine(
+                db_url,
+                pool_size=pool_size,
+                max_overflow=max_overflow,
+                echo=echo,
+                pool_pre_ping=True,
+            )
+            self._logger.info("Async engine created")
+            return engine
+        except Exception as e:
+            self._logger.error(f"Failed to create engine: {e}", exc_info=True)
+            raise
+
+    @asynccontextmanager
+    async def open_session(self):
+        session: AsyncSession = self._session_factory()
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+        finally:
+            await session.close()
+
+    @property
+    def engine(self) -> AsyncEngine:
+        return self._engine
+
+    @property
+    def session_factory(self):
+        return self._session_factory

vs_db/transaction/vs_transaction_manager.py

@@ -0,0 +1,64 @@
+from typing import Optional
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from vs_common.log.vs_log_manager import VsLogManager
+from vs_db.context.db_context import get_session, has_session, set_session
+from vs_db.session.vs_db_session_factory import VsDbSessionFactory
+
+_logger = VsLogManager.get_instance(__name__)
+
+
+class VsTransactionManager:
+
+    @classmethod
+    def get_session(cls) -> AsyncSession:
+        return get_session()
+
+    @classmethod
+    async def begin(cls) -> AsyncSession:
+        session = get_session()
+        if not session.in_transaction():
+            await session.begin()
+            _logger.debug("Transaction began")
+        return session
+
+    @classmethod
+    async def commit(cls) -> None:
+        session = get_session()
+        try:
+            await session.commit()
+            _logger.debug("Transaction committed")
+        except Exception as e:
+            _logger.error(f"Commit failed: {e}", exc_info=True)
+            await cls.rollback()
+            raise
+
+    @classmethod
+    async def rollback(cls) -> None:
+        session = get_session()
+        try:
+            await session.rollback()
+            _logger.debug("Transaction rolled back")
+        except Exception as e:
+            _logger.error(f"Rollback failed: {e}", exc_info=True)
+
+    @classmethod
+    def is_active(cls) -> bool:
+        return has_session()
+
+    @classmethod
+    async def open_unmanaged_session(cls) -> AsyncSession:
+        session: AsyncSession = VsDbSessionFactory.get_instance().session_factory()
+        set_session(session)
+        await session.begin()
+        return session
+
+    @classmethod
+    async def close_unmanaged_session(cls) -> None:
+        if has_session():
+            session = get_session()
+            try:
+                await session.close()
+            finally:
+                set_session(None)