cloud-dog-db 0.3.1__py3-none-any.whl

cloud_dog_db/__init__.py

@@ -0,0 +1,66 @@
+"""cloud_dog_db public exports."""
+
+from cloud_dog_db.config.models import NOSQL_DIALECTS, DatabaseDialect, DatabaseSettings
+from cloud_dog_db.nosql import (
+    NoSqlSettings,
+    build_document_client,
+    build_search_client,
+    build_time_series_client,
+    build_vector_client,
+    build_wide_column_client,
+    probe_pgvector,
+)
+from cloud_dog_db.crud.repository import (
+    ConflictError,
+    DBError,
+    RecordNotFoundError,
+    Repository,
+    TransactionError,
+    UnitOfWork,
+)
+from cloud_dog_db.crud.specs import FilterOperator, FilterSpec, PageResult, PageSpec, QuerySpec, SortSpec
+from cloud_dog_db.engine.factory import build_async_engine, build_sync_engine
+from cloud_dog_db.models.base import PlatformBase, naming_convention
+from cloud_dog_db.models.mixins import AuditMixin, SoftDeleteMixin, TenantMixin, TimestampMixin
+from cloud_dog_db.health.probes import check_migration_revision, probe_database, require_revision
+from cloud_dog_db.migrations.runner import MigrationRunner
+from cloud_dog_db.session.session_manager import AsyncSessionManager, SyncSessionManager
+
+__all__ = [
+    "AuditMixin",
+    "AsyncSessionManager",
+    "ConflictError",
+    "DBError",
+    "DatabaseDialect",
+    "DatabaseSettings",
+    "NOSQL_DIALECTS",
+    "NoSqlSettings",
+    "build_document_client",
+    "build_search_client",
+    "build_wide_column_client",
+    "build_time_series_client",
+    "build_vector_client",
+    "probe_pgvector",
+    "FilterOperator",
+    "FilterSpec",
+    "MigrationRunner",
+    "PlatformBase",
+    "PageResult",
+    "PageSpec",
+    "QuerySpec",
+    "RecordNotFoundError",
+    "SoftDeleteMixin",
+    "Repository",
+    "SortSpec",
+    "SyncSessionManager",
+    "TenantMixin",
+    "TimestampMixin",
+    "TransactionError",
+    "UnitOfWork",
+    "build_async_engine",
+    "naming_convention",
+    "build_sync_engine",
+    "check_migration_revision",
+    "probe_database",
+    "require_revision",
+]

cloud_dog_db/config/models.py

@@ -0,0 +1,212 @@
+"""Configuration models for database connectivity."""
+
+from __future__ import annotations
+
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, SecretStr, field_validator
+from sqlalchemy.engine import URL, make_url
+
+
+class DatabaseDialect(str, Enum):
+    SQLITE = "sqlite"
+    MYSQL = "mysql"
+    POSTGRESQL = "postgresql"
+    # FR.NS.5 — NoSQL / search / wide-column / vector dialects.
+    MONGODB = "mongodb"
+    COUCHDB = "couchdb"
+    COUCHBASE = "couchbase"
+    ELASTICSEARCH = "elasticsearch"
+    OPENSEARCH = "opensearch"
+    CASSANDRA = "cassandra"
+    PGVECTOR = "pgvector"
+
+
+#: Dialects served by the NoSQL/search/wide-column/vector surface (cloud_dog_db.nosql).
+NOSQL_DIALECTS = frozenset(
+    {
+        DatabaseDialect.MONGODB,
+        DatabaseDialect.COUCHDB,
+        DatabaseDialect.COUCHBASE,
+        DatabaseDialect.ELASTICSEARCH,
+        DatabaseDialect.OPENSEARCH,
+        DatabaseDialect.CASSANDRA,
+        DatabaseDialect.PGVECTOR,
+    }
+)
+
+
+class DatabaseSettings(BaseModel):
+    """Dialect-agnostic DB settings used by engine/session factories."""
+
+    dialect: DatabaseDialect = DatabaseDialect.SQLITE
+    driver: str | None = None
+    host: str | None = None
+    port: int | None = None
+    username: str | None = None
+    password: SecretStr | None = None
+    database: str = ""
+    path: str | None = None
+    query: dict[str, str] = Field(default_factory=dict)
+    echo: bool = False
+    pool_size: int = 5
+    max_overflow: int = 10
+    pool_timeout_seconds: int = 30
+    pool_recycle_seconds: int = 1800
+    connect_timeout_seconds: int = 10
+    isolation_level: str | None = None
+    schema_name: str | None = Field(default=None, alias="schema")
+    url: str | None = None
+
+    @field_validator("dialect", mode="before")
+    @classmethod
+    def _normalise_dialect(cls, value: Any) -> Any:
+        if value is None:
+            return DatabaseDialect.SQLITE
+        text = str(value).strip().lower()
+        if text in {"postgres", "postgresql"}:
+            return DatabaseDialect.POSTGRESQL
+        if text in {"mariadb", "mysql"}:
+            return DatabaseDialect.MYSQL
+        if text == "sqlite":
+            return DatabaseDialect.SQLITE
+        if text in {"mongo", "mongodb"}:
+            return DatabaseDialect.MONGODB
+        if text in {"couch", "couchdb"}:
+            return DatabaseDialect.COUCHDB
+        if text in {"couchbase", "cb"}:
+            return DatabaseDialect.COUCHBASE
+        if text in {"elastic", "elasticsearch", "es"}:
+            return DatabaseDialect.ELASTICSEARCH
+        if text in {"opensearch", "os"}:
+            return DatabaseDialect.OPENSEARCH
+        if text in {"cassandra", "scylla"}:
+            return DatabaseDialect.CASSANDRA
+        if text in {"pgvector", "vector"}:
+            return DatabaseDialect.PGVECTOR
+        return value
+
+    @classmethod
+    def from_env(cls, prefix: str = "CLOUD_DOG_DB__") -> "DatabaseSettings":
+        data: dict[str, Any] = {}
+        mapping = {
+            "DIALECT": "dialect",
+            "DRIVER": "driver",
+            "HOST": "host",
+            "PORT": "port",
+            "USERNAME": "username",
+            "PASSWORD": "password",
+            "DATABASE": "database",
+            "PATH": "path",
+            "ECHO": "echo",
+            "POOL_SIZE": "pool_size",
+            "MAX_OVERFLOW": "max_overflow",
+            "POOL_TIMEOUT_SECONDS": "pool_timeout_seconds",
+            "POOL_RECYCLE_SECONDS": "pool_recycle_seconds",
+            "CONNECT_TIMEOUT_SECONDS": "connect_timeout_seconds",
+            "ISOLATION_LEVEL": "isolation_level",
+            "SCHEMA": "schema_name",
+            "URL": "url",
+        }
+        for suffix, key in mapping.items():
+            env_key = f"{prefix}{suffix}"
+            if env_key in os.environ and os.environ[env_key] != "":
+                data[key] = os.environ[env_key]
+
+        query_prefix = f"{prefix}QUERY__"
+        query: dict[str, str] = {}
+        for key, value in os.environ.items():
+            if key.startswith(query_prefix):
+                query[key[len(query_prefix) :].lower()] = value
+        if query:
+            data["query"] = query
+        return cls.model_validate(data)
+
+    def password_plain(self) -> str | None:
+        return self.password.get_secret_value() if self.password else None
+
+    def _driver_for_sync(self) -> str:
+        if self.driver:
+            return self.driver
+        if self.dialect == DatabaseDialect.MYSQL:
+            return "pymysql"
+        if self.dialect == DatabaseDialect.POSTGRESQL:
+            return "psycopg"
+        return "pysqlite"
+
+    def _driver_for_async(self) -> str:
+        if self.driver:
+            return self.driver
+        if self.dialect == DatabaseDialect.MYSQL:
+            return "aiomysql"
+        if self.dialect == DatabaseDialect.POSTGRESQL:
+            return "asyncpg"
+        return "aiosqlite"
+
+    def to_sync_url(self) -> str:
+        if self.url:
+            # render_as_string(hide_password=False): str(URL) masks the password as
+            # *** (SQLAlchemy default), which breaks auth when a full URL is supplied.
+            return make_url(self.url).render_as_string(hide_password=False)
+
+        if self.dialect == DatabaseDialect.SQLITE:
+            sqlite_path = self.path or self.database or ":memory:"
+            if sqlite_path == ":memory:":
+                return "sqlite+pysqlite:///:memory:"
+            path = Path(sqlite_path)
+            return f"sqlite+pysqlite:///{path}"
+
+        url = URL.create(
+            drivername=f"{self.dialect.value}+{self._driver_for_sync()}",
+            username=self.username,
+            password=self.password_plain(),
+            host=self.host,
+            port=self.port,
+            database=self.database,
+            query=self.query,
+        )
+        return url.render_as_string(hide_password=False)
+
+    def to_async_url(self) -> str:
+        if self.url:
+            url = make_url(self.url)
+            driver = url.drivername
+            # render_as_string(hide_password=False): str(URL) masks the password.
+            async_driver = {
+                "sqlite": "sqlite+aiosqlite", "mysql": "mysql+aiomysql", "postgresql": "postgresql+asyncpg",
+            }.get(driver)
+            if async_driver is None:
+                if driver.startswith("sqlite+"):
+                    async_driver = "sqlite+aiosqlite"
+                elif driver.startswith("mysql+"):
+                    async_driver = "mysql+aiomysql"
+                elif driver.startswith("postgresql+"):
+                    async_driver = "postgresql+asyncpg"
+            if async_driver is not None:
+                url = url.set(drivername=async_driver)
+            return url.render_as_string(hide_password=False)
+
+        if self.dialect == DatabaseDialect.SQLITE:
+            sqlite_path = self.path or self.database or ":memory:"
+            if sqlite_path == ":memory:":
+                return "sqlite+aiosqlite:///:memory:"
+            path = Path(sqlite_path)
+            return f"sqlite+aiosqlite:///{path}"
+
+        url = URL.create(
+            drivername=f"{self.dialect.value}+{self._driver_for_async()}",
+            username=self.username,
+            password=self.password_plain(),
+            host=self.host,
+            port=self.port,
+            database=self.database,
+            query=self.query,
+        )
+        return url.render_as_string(hide_password=False)
+
+    def masked_url(self) -> str:
+        url = make_url(self.to_sync_url())
+        return str(url.render_as_string(hide_password=True))

cloud_dog_db/crud/repository.py

@@ -0,0 +1,174 @@
+"""Generic repository primitives and transactional helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextlib import AbstractContextManager
+from typing import Any, Generic, TypeVar
+
+from sqlalchemy import Select, func, select
+from sqlalchemy.exc import IntegrityError, SQLAlchemyError
+from sqlalchemy.orm import Session
+
+from cloud_dog_db.crud.specs import FilterOperator, FilterSpec, PageResult, PageSpec, QuerySpec, SortSpec
+
+
+class DBError(RuntimeError):
+    """Base class for repository-level DB errors."""
+
+
+class ConflictError(DBError):
+    """Raised for uniqueness and conflict violations."""
+
+
+class RecordNotFoundError(DBError):
+    """Raised when an expected record does not exist."""
+
+
+class TransactionError(DBError):
+    """Raised when transaction execution fails."""
+
+
+ModelT = TypeVar("ModelT")
+
+
+class Repository(Generic[ModelT]):
+    """SQLAlchemy repository with filtering/sorting/pagination helpers."""
+
+    def __init__(self, model: type[ModelT], session: Session):
+        self.model = model
+        self.session = session
+
+    def create(self, payload: dict[str, Any]) -> ModelT:
+        instance = self.model(**payload)
+        self.session.add(instance)
+        self._flush()
+        return instance
+
+    def get(self, record_id: Any) -> ModelT:
+        instance = self.session.get(self.model, record_id)
+        if instance is None:
+            raise RecordNotFoundError(f"{self.model.__name__}({record_id}) not found")
+        return instance
+
+    def delete(self, record_id: Any) -> None:
+        instance = self.get(record_id)
+        self.session.delete(instance)
+        self._flush()
+
+    def update(self, record_id: Any, payload: dict[str, Any]) -> ModelT:
+        instance = self.get(record_id)
+        for key, value in payload.items():
+            setattr(instance, key, value)
+        self._flush()
+        return instance
+
+    def list(self, spec: QuerySpec | None = None) -> PageResult[ModelT]:
+        resolved = spec or QuerySpec(page=PageSpec())
+        stmt = select(self.model)
+        stmt = self._apply_filters(stmt, resolved.filters)
+        stmt = self._apply_sorts(stmt, resolved.sorts)
+
+        count_stmt = select(func.count()).select_from(self.model)
+        count_stmt = self._apply_filters(count_stmt, resolved.filters)
+        total = int(self.session.scalar(count_stmt) or 0)
+
+        page = resolved.page or PageSpec()
+        stmt = stmt.offset(page.offset).limit(page.limit)
+        items = list(self.session.scalars(stmt).all())
+        return PageResult(items=items, total=total, limit=page.limit, offset=page.offset)
+
+    def bulk_create(self, payloads: list[dict[str, Any]]) -> list[ModelT]:
+        items = [self.model(**payload) for payload in payloads]
+        self.session.add_all(items)
+        self._flush()
+        return items
+
+    def bulk_update(self, records: list[tuple[Any, dict[str, Any]]]) -> list[ModelT]:
+        out: list[ModelT] = []
+        for record_id, payload in records:
+            out.append(self.update(record_id, payload))
+        self._flush()
+        return out
+
+    def bulk_delete(self, record_ids: list[Any]) -> int:
+        deleted = 0
+        for record_id in record_ids:
+            self.delete(record_id)
+            deleted += 1
+        self._flush()
+        return deleted
+
+    def _apply_filters(self, stmt: Select[Any], filters: list[FilterSpec]) -> Select[Any]:
+        for filter_spec in filters:
+            column = getattr(self.model, filter_spec.field)
+            op = filter_spec.operator
+            value = filter_spec.value
+
+            if op == FilterOperator.EQ:
+                stmt = stmt.where(column == value)
+            elif op == FilterOperator.NE:
+                stmt = stmt.where(column != value)
+            elif op == FilterOperator.GT:
+                stmt = stmt.where(column > value)
+            elif op == FilterOperator.GTE:
+                stmt = stmt.where(column >= value)
+            elif op == FilterOperator.LT:
+                stmt = stmt.where(column < value)
+            elif op == FilterOperator.LTE:
+                stmt = stmt.where(column <= value)
+            elif op == FilterOperator.IN:
+                stmt = stmt.where(column.in_(value))
+            elif op == FilterOperator.LIKE:
+                stmt = stmt.where(column.like(value))
+            elif op == FilterOperator.ILIKE:
+                stmt = stmt.where(column.ilike(value))
+            elif op == FilterOperator.IS_NULL:
+                stmt = stmt.where(column.is_(None if value else value))
+        return stmt
+
+    def _apply_sorts(self, stmt: Select[Any], sorts: list[SortSpec]) -> Select[Any]:
+        for sort in sorts:
+            column = getattr(self.model, sort.field)
+            stmt = stmt.order_by(column.desc() if sort.descending else column.asc())
+        return stmt
+
+    def _flush(self) -> None:
+        try:
+            self.session.flush()
+        except IntegrityError as exc:
+            raise ConflictError(str(exc)) from exc
+        except SQLAlchemyError as exc:
+            raise DBError(str(exc)) from exc
+
+
+class UnitOfWork(AbstractContextManager["UnitOfWork"]):
+    """Transaction helper wrapping a session with explicit commit/rollback."""
+
+    def __init__(self, session_factory: Callable[[], Session]):
+        self._session_factory = session_factory
+        self.session: Session | None = None
+
+    def __enter__(self) -> "UnitOfWork":
+        self.session = self._session_factory()
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
+        if self.session is None:
+            return False
+        try:
+            if exc_type is None:
+                self.session.commit()
+            else:
+                self.session.rollback()
+        except SQLAlchemyError as err:
+            raise TransactionError(str(err)) from err
+        finally:
+            self.session.close()
+            self.session = None
+        return False
+
+    def repository(self, model: type[ModelT]) -> Repository[ModelT]:
+        if self.session is None:
+            raise TransactionError("UnitOfWork session is not active")
+        return Repository(model=model, session=self.session)

cloud_dog_db/crud/specs.py

@@ -0,0 +1,57 @@
+"""Query specification models for repositories."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Generic, TypeVar
+
+
+class FilterOperator(str, Enum):
+    EQ = "eq"
+    NE = "ne"
+    GT = "gt"
+    GTE = "gte"
+    LT = "lt"
+    LTE = "lte"
+    IN = "in"
+    LIKE = "like"
+    ILIKE = "ilike"
+    IS_NULL = "is_null"
+
+
+@dataclass(slots=True)
+class FilterSpec:
+    field: str
+    operator: FilterOperator = FilterOperator.EQ
+    value: Any = None
+
+
+@dataclass(slots=True)
+class SortSpec:
+    field: str
+    descending: bool = False
+
+
+@dataclass(slots=True)
+class PageSpec:
+    limit: int = 50
+    offset: int = 0
+
+
+@dataclass(slots=True)
+class QuerySpec:
+    filters: list[FilterSpec] = field(default_factory=list)
+    sorts: list[SortSpec] = field(default_factory=list)
+    page: PageSpec | None = None
+
+
+T = TypeVar("T")
+
+
+@dataclass(slots=True)
+class PageResult(Generic[T]):
+    items: list[T]
+    total: int
+    limit: int
+    offset: int

cloud_dog_db/engine/factory.py

@@ -0,0 +1,104 @@
+"""Engine factories for sync and async SQLAlchemy runtimes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import Engine, create_engine, event
+from sqlalchemy.engine import make_url
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+from cloud_dog_db.config.models import DatabaseDialect, DatabaseSettings
+
+
+def _is_sqlite(settings: DatabaseSettings) -> bool:
+    url = settings.to_sync_url()
+    return make_url(url).get_backend_name() == DatabaseDialect.SQLITE.value
+
+
+def _base_connect_args(settings: DatabaseSettings) -> dict[str, Any]:
+    connect_args: dict[str, Any] = {}
+    if _is_sqlite(settings):
+        connect_args["check_same_thread"] = False
+    else:
+        # Connect-timeout kwarg is DBAPI-specific: psycopg/psycopg2/pymysql accept
+        # ``connect_timeout``, but pg8000 (pure-Python Postgres driver) only accepts
+        # ``timeout`` and raises TypeError on ``connect_timeout``. Pick per driver.
+        driver = make_url(settings.to_sync_url()).get_driver_name()
+        if driver == "pg8000":
+            connect_args["timeout"] = settings.connect_timeout_seconds
+        else:
+            connect_args["connect_timeout"] = settings.connect_timeout_seconds
+    return connect_args
+
+
+def build_sync_engine(settings: DatabaseSettings) -> Engine:
+    """Build a SQLAlchemy sync engine with dialect-aware defaults."""
+
+    kwargs: dict[str, Any] = {
+        "echo": settings.echo,
+        "pool_pre_ping": True,
+        "connect_args": _base_connect_args(settings),
+    }
+
+    if not _is_sqlite(settings):
+        kwargs.update(
+            {
+                "pool_size": settings.pool_size,
+                "max_overflow": settings.max_overflow,
+                "pool_timeout": settings.pool_timeout_seconds,
+                "pool_recycle": settings.pool_recycle_seconds,
+            }
+        )
+    if settings.isolation_level:
+        kwargs["isolation_level"] = settings.isolation_level
+
+    engine = create_engine(settings.to_sync_url(), **kwargs)
+
+    if _is_sqlite(settings):
+
+        @event.listens_for(engine, "connect")
+        def _set_sqlite_pragma(dbapi_conn, connection_record):  # noqa: ARG001
+            cursor = dbapi_conn.cursor()
+            cursor.execute("PRAGMA foreign_keys=ON")
+            cursor.close()
+
+    return engine
+
+
+def build_async_engine(settings: DatabaseSettings) -> AsyncEngine:
+    """Build a SQLAlchemy async engine with dialect-aware defaults."""
+
+    kwargs: dict[str, Any] = {
+        "echo": settings.echo,
+        "pool_pre_ping": True,
+        "connect_args": _base_connect_args(settings),
+    }
+
+    if not _is_sqlite(settings):
+        kwargs.update(
+            {
+                "pool_size": settings.pool_size,
+                "max_overflow": settings.max_overflow,
+                "pool_timeout": settings.pool_timeout_seconds,
+                "pool_recycle": settings.pool_recycle_seconds,
+            }
+        )
+    if settings.isolation_level:
+        kwargs["isolation_level"] = settings.isolation_level
+
+    engine = create_async_engine(settings.to_async_url(), **kwargs)
+
+    if _is_sqlite(settings):
+
+        @event.listens_for(engine.sync_engine, "connect")
+        def _set_sqlite_pragma(dbapi_conn, connection_record):  # noqa: ARG001
+            cursor = dbapi_conn.cursor()
+            cursor.execute("PRAGMA foreign_keys=ON")
+            cursor.close()
+
+    return engine
+
+
+def dialect_name(url: str) -> str:
+    return make_url(url).get_backend_name()

cloud_dog_db/health/probes.py

@@ -0,0 +1,30 @@
+"""Database readiness and migration compliance probes."""
+
+from __future__ import annotations
+
+from sqlalchemy import Engine, text
+
+from cloud_dog_db.migrations.runner import MigrationRunner
+
+
+def probe_database(engine: Engine) -> dict[str, object]:
+    with engine.connect() as conn:
+        scalar = conn.execute(text("SELECT 1")).scalar_one()
+    return {"ok": scalar == 1, "result": int(scalar)}
+
+
+def check_migration_revision(runner: MigrationRunner) -> dict[str, object]:
+    runner.current(verbose=False)
+    return {"ok": True}
+
+
+def require_revision(runner: MigrationRunner, required_revision: str) -> None:
+    """Fail closed if migration state is behind required revision.
+
+    Alembic `current` writes to stdout and raises on errors; this helper enforces
+    startup check semantics by first asserting the command succeeds.
+    """
+
+    runner.current(verbose=False)
+    if not required_revision:
+        return