svc-infra 0.1.595__py3-none-any.whl → 1.1.0__py3-none-any.whl

svc_infra/db/sql/templates/setup/env_sync.py.tmpl

@@ -6,11 +6,10 @@ from typing import List, Tuple
 import sys, pathlib, importlib, pkgutil, traceback
 
 from alembic import context
+from sqlalchemy import MetaData
 from sqlalchemy.engine import make_url, URL
 
 from svc_infra.db.sql.utils import (
-    _coerce_sync_driver,
-    _ensure_ssl_default,
     get_database_url_from_env,
     build_engine,
 )
@@ -103,7 +102,6 @@ if not effective_url:
 
 u = make_url(effective_url)
 u = _coerce_sync_driver(u)
-u = _ensure_ssl_default(u)
 config.set_main_option("sqlalchemy.url", u.render_as_string(hide_password=False))
 
 
@@ -142,14 +140,16 @@ def _collect_metadata() -> list[object]:
 
     def _maybe_add(obj: object) -> None:
         md = getattr(obj, "metadata", None) or obj
-        if hasattr(md, "tables") and getattr(md, "tables"):
+        # Strict check: must be actual MetaData instance
+        if isinstance(md, MetaData) and md.tables:
             found.append(md)
 
     def _scan_module_objects(mod: object) -> None:
         try:
             for val in vars(mod).values():
                 md = getattr(val, "metadata", None) or None
-                if md is not None and hasattr(md, "tables") and getattr(md, "tables"):
+                # Only add if it's a SQLAlchemy MetaData object (has tables dict, not a callable/generator)
+                if md is not None and hasattr(md, "tables") and isinstance(getattr(md, "tables", None), dict):
                     found.append(md)
         except Exception:
             pass
@@ -191,9 +191,16 @@ def _collect_metadata() -> list[object]:
                 if name not in pkgs:
                     pkgs.append(name)
 
-    # Always also try a bare 'models'
+    # Only attempt a bare 'models' import if discoverable to avoid noisy tracebacks
     if "models" not in pkgs:
-        pkgs.append("models")
+        try:
+            spec = getattr(importlib, "util", None)
+            if spec is not None and getattr(spec, "find_spec", None) is not None:
+                if spec.find_spec("models") is not None:
+                    pkgs.append("models")
+        except Exception:
+            # If discovery fails, skip adding bare 'models'
+            pass
 
     def _import_and_collect(modname: str):
         try:
@@ -239,6 +246,21 @@ def _collect_metadata() -> list[object]:
     except Exception:
         _note("ModelBase import", False, traceback.format_exc())
 
+    # Core security models (AuthSession, RefreshToken, etc.)
+    try:
+        import svc_infra.security.models  # noqa: F401
+        _note("svc_infra.security.models", True, None)
+    except Exception:
+        _note("svc_infra.security.models", False, traceback.format_exc())
+
+    # OAuth models (opt-in via environment variable)
+    if os.getenv("ALEMBIC_ENABLE_OAUTH", "").lower() in {"1", "true", "yes"}:
+        try:
+            import svc_infra.security.oauth_models  # noqa: F401
+            _note("svc_infra.security.oauth_models", True, None)
+        except Exception:
+            _note("svc_infra.security.oauth_models", False, traceback.format_exc())
+
     # Optional: autobind API key model
     try:
         from svc_infra.db.sql.apikey import try_autobind_apikey_model

svc_infra/db/sql/tenant.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .service import SqlService
+
+
+class TenantSqlService(SqlService):
+    """
+    SQL service wrapper that automatically scopes operations to a tenant.
+
+    - Adds a where filter (model.tenant_field == tenant_id) for list/get/update/delete/search/count.
+    - On create, if the model has the tenant field and it's not set in data, injects tenant_id.
+    """
+
+    def __init__(self, repo, *, tenant_id: str, tenant_field: str = "tenant_id"):
+        super().__init__(repo)
+        self.tenant_id = tenant_id
+        self.tenant_field = tenant_field
+
+    def _where(self) -> Sequence[Any]:
+        model = self.repo.model
+        col = getattr(model, self.tenant_field, None)
+        if col is None:
+            return []
+        return [col == self.tenant_id]
+
+    async def list(self, session: AsyncSession, *, limit: int, offset: int, order_by=None):
+        return await self.repo.list(
+            session, limit=limit, offset=offset, order_by=order_by, where=self._where()
+        )
+
+    async def count(self, session: AsyncSession) -> int:
+        return await self.repo.count(session, where=self._where())
+
+    async def get(self, session: AsyncSession, id_value: Any):
+        return await self.repo.get(session, id_value, where=self._where())
+
+    async def create(self, session: AsyncSession, data: dict[str, Any]):
+        data = await self.pre_create(data)
+        # inject tenant_id if model supports it and value missing
+        if self.tenant_field in self.repo._model_columns() and self.tenant_field not in data:
+            data[self.tenant_field] = self.tenant_id
+        return await self.repo.create(session, data)
+
+    async def update(self, session: AsyncSession, id_value: Any, data: dict[str, Any]):
+        data = await self.pre_update(data)
+        return await self.repo.update(session, id_value, data, where=self._where())
+
+    async def delete(self, session: AsyncSession, id_value: Any) -> bool:
+        return await self.repo.delete(session, id_value, where=self._where())
+
+    async def search(
+        self,
+        session: AsyncSession,
+        *,
+        q: str,
+        fields: Sequence[str],
+        limit: int,
+        offset: int,
+        order_by=None,
+    ):
+        return await self.repo.search(
+            session,
+            q=q,
+            fields=fields,
+            limit=limit,
+            offset=offset,
+            order_by=order_by,
+            where=self._where(),
+        )
+
+    async def count_filtered(self, session: AsyncSession, *, q: str, fields: Sequence[str]) -> int:
+        return await self.repo.count_filtered(session, q=q, fields=fields, where=self._where())
+
+
+__all__ = ["TenantSqlService"]

svc_infra/db/sql/uniq.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, Iterable, List, Optional, Tuple, Type
+from collections.abc import Iterable
+from typing import Any
 
 from sqlalchemy import Index, func
 
@@ -9,13 +10,13 @@ from svc_infra.db.utils import as_tuple as _as_tuple
 
 
 def make_unique_sql_indexes(
-    model: Type[Any],
+    model: type[Any],
     *,
     unique_cs: Iterable[KeySpec] = (),
     unique_ci: Iterable[KeySpec] = (),
-    tenant_field: Optional[str] = None,
+    tenant_field: str | None = None,
     name_prefix: str = "uq",
-) -> List[Index]:
+) -> list[Index]:
     """Return SQLAlchemy Index objects that enforce uniqueness.
 
     - unique_cs: case-sensitive unique specs
@@ -26,12 +27,12 @@ def make_unique_sql_indexes(
 
     Declare right after your model class; Alembic or metadata.create_all will pick them up.
     """
-    idxs: List[Index] = []
+    idxs: list[Index] = []
 
     def _col(name: str):
         return getattr(model, name)
 
-    def _to_sa_cols(spec: Tuple[str, ...], *, ci: bool):
+    def _to_sa_cols(spec: tuple[str, ...], *, ci: bool):
         cols = []
         for cname in spec:
             c = _col(cname)
@@ -40,7 +41,7 @@ def make_unique_sql_indexes(
 
     tenant_col = _col(tenant_field) if tenant_field else None
 
-    def _name(ci: bool, spec: Tuple[str, ...], null_bucket: Optional[str] = None):
+    def _name(ci: bool, spec: tuple[str, ...], null_bucket: str | None = None):
         parts = [name_prefix, model.__tablename__]
         if tenant_field:
             parts.append(tenant_field)

svc_infra/db/sql/uniq_hooks.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple, Union
+from collections.abc import Callable, Iterable, Sequence
+from typing import Any
 
 from fastapi import HTTPException
 from sqlalchemy import func
@@ -11,14 +12,14 @@ from svc_infra.db.sql.service_with_hooks import SqlServiceWithHooks
 
 from .uniq import _as_tuple
 
-ColumnSpec = Union[str, Sequence[str]]
+ColumnSpec = str | Sequence[str]
 
 
-def _all_present(data: Dict[str, Any], fields: Sequence[str]) -> bool:
+def _all_present(data: dict[str, Any], fields: Sequence[str]) -> bool:
     return all(f in data for f in fields)
 
 
-def _nice_label(fields: Sequence[str], data: Dict[str, Any]) -> str:
+def _nice_label(fields: Sequence[str], data: dict[str, Any]) -> str:
     if len(fields) == 1:
         f = fields[0]
         return f"{f}={data.get(f)!r}"
@@ -30,10 +31,10 @@ def dedupe_sql_service(
     *,
     unique_cs: Iterable[ColumnSpec] = (),
     unique_ci: Iterable[ColumnSpec] = (),
-    tenant_field: Optional[str] = None,
-    messages: Optional[dict[Tuple[str, ...], str]] = None,
-    pre_create: Optional[Callable[[dict], dict]] = None,
-    pre_update: Optional[Callable[[dict], dict]] = None,
+    tenant_field: str | None = None,
+    messages: dict[tuple[str, ...], str] | None = None,
+    pre_create: Callable[[dict], dict] | None = None,
+    pre_update: Callable[[dict], dict] | None = None,
 ):
     """
     Build a Service subclass with uniqueness pre-checks:
@@ -46,9 +47,9 @@ def dedupe_sql_service(
     messages = messages or {}
 
     def _build_where(
-        spec: Tuple[str, ...], data: Dict[str, Any], *, ci: bool, exclude_id: Any | None
+        spec: tuple[str, ...], data: dict[str, Any], *, ci: bool, exclude_id: Any | None
     ):
-        clauses: List[Any] = []
+        clauses: list[Any] = []
         for col_name in spec:
             col = getattr(Model, col_name)
             val = data.get(col_name)
@@ -73,7 +74,7 @@ def dedupe_sql_service(
 
         return clauses
 
-    async def _precheck(session, data: Dict[str, Any], *, exclude_id: Any | None) -> None:
+    async def _precheck(session, data: dict[str, Any], *, exclude_id: Any | None) -> None:
         # Check CI specs first to catch the broadest conflicts, then CS.
         for ci, spec_list in ((True, unique_ci), (False, unique_cs)):
             for spec in spec_list:

svc_infra/db/sql/utils.py

@@ -2,8 +2,9 @@ from __future__ import annotations
 
 import asyncio
 import os
+from collections.abc import Sequence
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Optional, Sequence, Set, Union
+from typing import TYPE_CHECKING, Any, cast
 
 from alembic.config import Config
 from dotenv import load_dotenv
@@ -17,24 +18,24 @@ if TYPE_CHECKING:
     from sqlalchemy.engine import Engine as SyncEngine
     from sqlalchemy.ext.asyncio import AsyncEngine as AsyncEngineType
 else:
-    SyncEngine = Any  # type: ignore
-    AsyncEngineType = Any  # type: ignore
+    SyncEngine = Any  # type: ignore[assignment]
+    AsyncEngineType = Any  # type: ignore[assignment]
 
 try:
     # Runtime import (may be missing if async extras aren’t installed)
-    from sqlalchemy.ext.asyncio import create_async_engine as _create_async_engine  # type: ignore
+    from sqlalchemy.ext.asyncio import create_async_engine as _create_async_engine
 except Exception:  # pragma: no cover - optional dep
-    _create_async_engine = None  # type: ignore
+    _create_async_engine = None  # type: ignore[assignment]
 
 try:
-    from sqlalchemy import create_engine as _create_engine  # type: ignore
+    from sqlalchemy import create_engine as _create_engine
 except Exception:  # pragma: no cover - optional env
-    _create_engine = None  # type: ignore
+    _create_engine = None  # type: ignore[assignment]
 
 
 def prepare_process_env(
     project_root: Path | str,
-    discover_packages: Optional[Sequence[str]] = None,
+    discover_packages: Sequence[str] | None = None,
 ) -> None:
     """
     Prepare process environment so Alembic can import the project cleanly.
@@ -60,7 +61,7 @@ def prepare_process_env(
         os.environ["ALEMBIC_DISCOVER_PACKAGES"] = ",".join(discover_packages)
 
 
-def _read_secret_from_file(path: str) -> Optional[str]:
+def _read_secret_from_file(path: str) -> str | None:
     """Return file contents if path exists, else None."""
     try:
         p = Path(path)
@@ -71,7 +72,7 @@ def _read_secret_from_file(path: str) -> Optional[str]:
     return None
 
 
-def _compose_url_from_parts() -> Optional[str]:
+def _compose_url_from_parts() -> str | None:
     """
     Compose a SQLAlchemy URL from component env vars.
     Supports private DNS hostnames and Unix sockets.
@@ -124,18 +125,62 @@ def _compose_url_from_parts() -> Optional[str]:
 # ---------- Environment helpers ----------
 
 
+def _normalize_database_url(url: str) -> str:
+    """
+    Normalize database URL for SQLAlchemy compatibility.
+
+    Handles:
+      - postgres:// → postgresql:// (Heroku/Railway legacy format)
+      - Strips whitespace
+
+    Args:
+        url: Raw database URL string
+
+    Returns:
+        Normalized URL suitable for SQLAlchemy
+    """
+    url = url.strip()
+    # Heroku and Railway historically use 'postgres://' which SQLAlchemy doesn't accept
+    if url.startswith("postgres://"):
+        url = "postgresql://" + url[len("postgres://") :]
+    return url
+
+
 def get_database_url_from_env(
     required: bool = True,
     env_vars: Sequence[str] = DEFAULT_DB_ENV_VARS,
-) -> Optional[str]:
+    normalize: bool = True,
+) -> str | None:
     """
     Resolve the database connection string, with support for:
-      - Primary env vars (in order): DEFAULT_DB_ENV_VARS (e.g. SQL_URL, PRIVATE_SQL_URL, DB_URL).
+      - Primary env vars (in order): DEFAULT_DB_ENV_VARS
+        (SQL_URL, DB_URL, DATABASE_URL, DATABASE_URL_PRIVATE, PRIVATE_SQL_URL)
       - Secret file pointers: <NAME>_FILE (reads file contents).
       - Well-known locations: SQL_URL_FILE, /run/secrets/database_url.
       - Composed from parts: DB_* (host, port, name, user, password, params).
-    When a value is found, it is also written back into os.environ["SQL_URL"] for downstream code.
+
+    When a value is found, it is also written back into os.environ["SQL_URL"]
+    for downstream code.
+
+    Args:
+        required: If True, raise RuntimeError when no URL is found
+        env_vars: Sequence of environment variable names to check
+        normalize: If True, convert postgres:// to postgresql:// (default: True)
+
+    Returns:
+        Database URL string, or None if not found and not required
+
+    Raises:
+        RuntimeError: If required=True and no URL is found
     """
+
+    def _finalize(url: str) -> str:
+        """Normalize and cache the URL."""
+        if normalize:
+            url = _normalize_database_url(url)
+        os.environ["SQL_URL"] = url
+        return url
+
     # Load .env without clobbering existing process env
     load_dotenv(override=False)
 
@@ -150,10 +195,8 @@ def get_database_url_from_env(
             if os.path.isabs(s) and Path(s).exists():
                 file_val = _read_secret_from_file(s)
                 if file_val:
-                    os.environ["SQL_URL"] = file_val
-                    return file_val
-            os.environ["SQL_URL"] = s
-            return s
+                    return _finalize(file_val)
+            return _finalize(s)
 
         # Companion NAME_FILE secret path (e.g., SQL_URL_FILE)
         file_key = f"{key}_FILE"
@@ -161,32 +204,28 @@ def get_database_url_from_env(
         if file_path:
             file_val = _read_secret_from_file(file_path)
             if file_val:
-                os.environ["SQL_URL"] = file_val
-                return file_val
+                return _finalize(file_val)
 
     # 2) Conventional secret envs
     file_path = os.getenv("SQL_URL_FILE")
     if file_path:
         file_val = _read_secret_from_file(file_path)
         if file_val:
-            os.environ["SQL_URL"] = file_val
-            return file_val
+            return _finalize(file_val)
 
     # 3) Docker/K8s default secret mount
     file_val = _read_secret_from_file("/run/secrets/database_url")
     if file_val:
-        os.environ["SQL_URL"] = file_val
-        return file_val
+        return _finalize(file_val)
 
     # 4) Compose from parts (DB_DIALECT/DB_DRIVER/DB_HOST/.../DB_PARAMS)
     composed = _compose_url_from_parts()
     if composed:
-        os.environ["SQL_URL"] = composed
-        return composed
+        return _finalize(composed)
 
     if required:
         raise RuntimeError(
-            "Database URL not set. Set SQL_URL (or PRIVATE_SQL_URL / DB_URL), "
+            "Database URL not set. Set SQL_URL, DATABASE_URL, or DATABASE_URL_PRIVATE, "
             "or provide DB_* parts (DB_HOST, DB_NAME, etc.), or a *_FILE secret."
         )
     return None
@@ -196,10 +235,17 @@ def _ensure_timeout_default(u: URL) -> URL:
     """
     Ensure a conservative connection timeout is present for libpq-based drivers.
     For psycopg/psycopg2, 'connect_timeout' is honored via the query string.
+    For asyncpg, timeout is set via connect_args (not query string).
     """
     backend = (u.get_backend_name() or "").lower()
     if backend not in ("postgresql", "postgres"):
         return u
+
+    # asyncpg doesn't support connect_timeout in query string - use connect_args instead
+    dn = (u.drivername or "").lower()
+    if "+asyncpg" in dn:
+        return u
+
     if "connect_timeout" in u.query:
         return u
     # Default 10s unless overridden
@@ -216,7 +262,7 @@ def is_async_url(url: URL | str) -> bool:
     return bool(ASYNC_DRIVER_HINT.search(dn))
 
 
-def with_database(url: URL | str, database: Optional[str]) -> URL:
+def with_database(url: URL | str, database: str | None) -> URL:
     """Return a copy of URL with the database name replaced.
 
     Works for most dialects. For SQLite/DuckDB file URLs, `database` is the file path.
@@ -337,9 +383,8 @@ def _ensure_ssl_default(u: URL) -> URL:
     mode = (mode_env or "").strip()
 
     if "+asyncpg" in driver:
-        # asyncpg: use 'ssl=true' (SQLAlchemy forwards to asyncpg)
-        if "ssl" not in u.query:
-            return u.set(query={**u.query, "ssl": "true"})
+        # asyncpg: SSL is handled in connect_args in build_engine(), not in URL query
+        # Do not add ssl parameter to URL query for asyncpg
         return u
     else:
         # libpq-based drivers: use sslmode (default 'require' for hosted PG)
@@ -366,7 +411,7 @@ def _certifi_ca() -> str | None:
         return None
 
 
-def build_engine(url: URL | str, echo: bool = False) -> Union[SyncEngine, AsyncEngineType]:
+def build_engine(url: URL | str, echo: bool = False) -> SyncEngine | AsyncEngineType:
     u = make_url(url) if isinstance(url, str) else url
 
     # Keep your existing PG helpers
@@ -382,10 +427,18 @@ def build_engine(url: URL | str, echo: bool = False) -> Union[SyncEngine, AsyncE
                 "Async driver URL provided but SQLAlchemy async extras are not available."
             )
 
-        # asyncpg: honor connection timeout
+        # asyncpg: honor connection timeout only (NOT connect_timeout)
         if "+asyncpg" in (u.drivername or ""):
             connect_args["timeout"] = int(os.getenv("DB_CONNECT_TIMEOUT", "10"))
 
+            # asyncpg doesn't accept sslmode or ssl=true in query params
+            # Remove these and set ssl='require' in connect_args
+            if "ssl" in u.query or "sslmode" in u.query:
+                new_query = {k: v for k, v in u.query.items() if k not in ("ssl", "sslmode")}
+                u = u.set(query=new_query)
+            # Set ssl in connect_args - 'require' is safest for hosted databases
+            connect_args["ssl"] = "require"
+
         # NEW: aiomysql SSL default
         if "+aiomysql" in (u.drivername or "") and not any(
             k in u.query for k in ("ssl", "ssl_ca", "sslmode")
@@ -404,10 +457,10 @@ def build_engine(url: URL | str, echo: bool = False) -> Union[SyncEngine, AsyncE
             except Exception:
                 connect_args["ssl"] = True  # minimal hint to enable TLS
 
-        kwargs: dict[str, Any] = {"echo": echo, "pool_pre_ping": True}
+        async_engine_kwargs: dict[str, Any] = {"echo": echo, "pool_pre_ping": True}
         if connect_args:
-            kwargs["connect_args"] = connect_args
-        return _create_async_engine(u, **kwargs)
+            async_engine_kwargs["connect_args"] = connect_args
+        return _create_async_engine(u, **async_engine_kwargs)
 
     # ----------------- SYNC -----------------
     u = _coerce_sync_driver(u)
@@ -435,10 +488,10 @@ def build_engine(url: URL | str, echo: bool = False) -> Union[SyncEngine, AsyncE
         # Optional: if your provider requires it, you can also add:
         # connect_args.setdefault("client_flag", 0)
 
-    kwargs: dict[str, Any] = {"echo": echo, "pool_pre_ping": True}
+    sync_engine_kwargs: dict[str, Any] = {"echo": echo, "pool_pre_ping": True}
     if connect_args:
-        kwargs["connect_args"] = connect_args
-    return _create_engine(u, **kwargs)
+        sync_engine_kwargs["connect_args"] = connect_args
+    return _create_engine(u, **sync_engine_kwargs)
 
 
 # ---------- Identifier quoting helpers ----------
@@ -485,7 +538,7 @@ async def _pg_create_database_async(url: URL) -> None:
             )
             if not exists:
                 quoted = _pg_quote_ident(target_db)
-                await conn.execution_options(isolation_level="AUTOCOMMIT").execute(
+                await conn.execution_options(isolation_level="AUTOCOMMIT").execute(  # type: ignore[attr-defined]
                     text(f'CREATE DATABASE "{quoted}"')
                 )
     except DBAPIError as e:
@@ -789,17 +842,19 @@ def ensure_database_exists(url: URL | str) -> None:
     try:
         eng = build_engine(u)
         if is_async_url(u):
+            async_eng = cast("AsyncEngineType", eng)
 
             async def _ping_and_dispose():
-                async with eng.begin() as conn:  # type: ignore[call-arg]
+                async with async_eng.begin() as conn:
                     await conn.execute(text("SELECT 1"))
-                await eng.dispose()  # type: ignore[attr-defined]
+                await async_eng.dispose()
 
             asyncio.run(_ping_and_dispose())
         else:
-            with eng.begin() as conn:  # type: ignore[call-arg]
+            sync_eng = cast("SyncEngine", eng)
+            with sync_eng.begin() as conn:
                 conn.execute(text("SELECT 1"))
-            eng.dispose()  # type: ignore[attr-defined]
+            sync_eng.dispose()
     except OperationalError as exc:  # pragma: no cover (depends on env)
         raise RuntimeError(f"Failed to connect to database: {exc}") from exc
 
@@ -811,9 +866,12 @@ def repair_alembic_state_if_needed(cfg: Config) -> None:
         return
 
     # Gather local revision ids from versions/
-    script_location = Path(cfg.get_main_option("script_location"))
+    script_location_str = cfg.get_main_option("script_location")
+    if not script_location_str:
+        return
+    script_location = Path(script_location_str)
     versions_dir = script_location / "versions"
-    local_ids: Set[str] = set()
+    local_ids: set[str] = set()
     if versions_dir.exists():
         for p in versions_dir.glob("*.py"):
             try:
@@ -831,7 +889,7 @@ def repair_alembic_state_if_needed(cfg: Config) -> None:
     if is_async_url(url_obj):
 
         async def _run() -> None:
-            eng = build_engine(url_obj)  # AsyncEngine
+            eng = cast("AsyncEngineType", build_engine(url_obj))
             try:
                 async with eng.begin() as conn:
                     # Do sync-y inspector / SQL via run_sync
@@ -854,7 +912,7 @@ def repair_alembic_state_if_needed(cfg: Config) -> None:
 
         asyncio.run(_run())
     else:
-        eng = build_engine(url_obj)  # sync Engine
+        eng = cast("SyncEngine", build_engine(url_obj))
         try:
             with eng.begin() as c:
                 insp = inspect(c)

svc_infra/db/sql/versioning.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from sqlalchemy import Integer
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class Versioned:
+    """Mixin for optimistic locking with integer version.
+
+    - Initialize version=1 on insert (via default=1)
+    - Bump version in app code before commit to detect mismatches.
+    """
+
+    version: Mapped[int] = mapped_column(Integer, nullable=False, default=1)

svc_infra/db/utils.py

@@ -1,10 +1,10 @@
+from collections.abc import Sequence
 from pathlib import Path
-from typing import Sequence, Tuple, Union
 
-KeySpec = Union[str, Sequence[str]]
+KeySpec = str | Sequence[str]
 
 
-def as_tuple(spec: KeySpec) -> Tuple[str, ...]:
+def as_tuple(spec: KeySpec) -> tuple[str, ...]:
     return (spec,) if isinstance(spec, str) else tuple(spec)