boti-data 1.3.0__tar.gz → 1.3.2__tar.gz

{boti_data-1.3.0 → boti_data-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boti-data
-Version: 1.3.0
+Version: 1.3.2
 Summary: Data infrastructure for the Boti ecosystem
 Author: Luis Valverde
 Maintainer-email: Luis Valverde <lvalverdeb@gmail.com>

{boti_data-1.3.0 → boti_data-1.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "boti-data"
-version = "1.3.0"
+version = "1.3.2"
 description = "Data infrastructure for the Boti ecosystem"
 readme = "README.md"
 requires-python = ">=3.13"

{boti_data-1.3.0 → boti_data-1.3.2}/src/boti_data/db/sql_config.py

@@ -18,7 +18,19 @@ _ALLOWED_POOLCLASS_IMPORTS = {
 
 
 class SqlDatabaseConfig(ResourceConfig):
-    """Immutable configuration for SQLAlchemy engine initialization."""
+    """Immutable configuration for SQLAlchemy engine initialization.
+
+    ``query_only=True`` enforces read-only access at the database level (via
+    a ``SET ... READ ONLY``-style statement issued on the SQLAlchemy
+    ``"connect"`` event, not just by blocking ORM methods in Python) — this
+    assumes ``connection_url`` points directly at Postgres/MySQL, or at a
+    *session*-pooling-mode connection pooler (one physical backend connection
+    dedicated to one logical client for its whole lifetime). It does **not**
+    cover a *transaction*-pooling-mode pooler (e.g. PgBouncer in ``transaction``
+    mode): there, a single physical connection can be handed to a different,
+    unrelated logical client between transactions, and session-level state set
+    once at physical-connect time is not guaranteed to survive that handoff.
+    """
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
@@ -27,7 +39,9 @@ class SqlDatabaseConfig(ResourceConfig):
         default=True,
         description=(
             "When true, native database-enforced read-only access is required. "
-            "Set explicitly to false to allow writes."
+            "Set explicitly to false to allow writes. Assumes a direct connection "
+            "or a session-pooling-mode proxy — transaction-pooling-mode poolers "
+            "(e.g. PgBouncer 'transaction' mode) are out of scope; see class docstring."
         ),
     )
     worker_connection_env_var: str | None = Field(

{boti_data-1.3.0 → boti_data-1.3.2}/src/boti_data/db/sql_model_registry.py

@@ -238,22 +238,34 @@ class SqlModelRegistry:
         md = self._get_or_create_metadata(ekey, schema)
         md_lock = self._get_or_create_md_lock(md_key)
         qname = self._qualified_key(schema, tname)
-        tbl = self._reflect_table(engine, md, md_lock, qname=qname, tname=tname, schema=schema)
-
-        context = ModelBuildContext(
-            qname=qname,
-            tname=tname,
-            base_class=base_class,
-            module_label=module_label,
-            prefer_stable_names=prefer_stable_names,
-            ekey=ekey,
-            schema=schema,
-            missing_pk_warning_suffix="Ensure ORM mutation sequences validate bounds manually.",
-        )
-        model_cls = self._resolve_or_build_model(tbl, qname, context, target_label="DB target")
-        with self._lock:
-            self._model_cache[model_key] = model_cls
-        return model_cls
+
+        # The whole reflect -> resolve-or-build -> cache-write sequence must
+        # be one atomic unit per md_key: reflection alone was already
+        # serialized via md_lock, but resolve-or-build and the cache write
+        # previously ran outside it, so two concurrent first-accesses for the
+        # same table could both pass "does a mapped class already exist?"
+        # before either finished building — each got a distinct Python class
+        # mapped to the same Table.
+        with md_lock:
+            cached = self._check_cache(model_key, refresh=False)
+            if cached is not None:
+                return cached
+
+            tbl = self._reflect_table(engine, md, qname=qname, tname=tname, schema=schema)
+            context = ModelBuildContext(
+                qname=qname,
+                tname=tname,
+                base_class=base_class,
+                module_label=module_label,
+                prefer_stable_names=prefer_stable_names,
+                ekey=ekey,
+                schema=schema,
+                missing_pk_warning_suffix="Ensure ORM mutation sequences validate bounds manually.",
+            )
+            model_cls = self._resolve_or_build_model(tbl, qname, context, target_label="DB target")
+            with self._lock:
+                self._model_cache[model_key] = model_cls
+            return model_cls
 
     async def get_model_async(
         self,
@@ -278,26 +290,33 @@ class SqlModelRegistry:
         md = self._get_or_create_metadata(ekey, schema)
         md_lock = await self._get_or_create_md_lock_async(md_key)
         qname = self._qualified_key(schema, tname)
-        tbl = await self._reflect_table_async(
-            engine, md, md_lock, qname=qname, tname=tname, schema=schema
-        )
 
-        context = ModelBuildContext(
-            qname=qname,
-            tname=tname,
-            base_class=base_class,
-            module_label=module_label,
-            prefer_stable_names=prefer_stable_names,
-            ekey=ekey,
-            schema=schema,
-            missing_pk_warning_suffix="Ensure Async ORM validation sequences capture bounds correctly.",
-        )
-        model_cls = self._resolve_or_build_model(
-            tbl, qname, context, target_label="Async DB target"
-        )
-        async with self._async_lock:
-            self._model_cache[model_key] = model_cls
-        return model_cls
+        # See get_model()'s comment: the whole sequence must be one atomic
+        # unit per md_key, not just the reflection step.
+        async with md_lock:
+            cached = await self._check_cache_async(model_key, refresh=False)
+            if cached is not None:
+                return cached
+
+            tbl = await self._reflect_table_async(
+                engine, md, qname=qname, tname=tname, schema=schema
+            )
+            context = ModelBuildContext(
+                qname=qname,
+                tname=tname,
+                base_class=base_class,
+                module_label=module_label,
+                prefer_stable_names=prefer_stable_names,
+                ekey=ekey,
+                schema=schema,
+                missing_pk_warning_suffix="Ensure Async ORM validation sequences capture bounds correctly.",
+            )
+            model_cls = self._resolve_or_build_model(
+                tbl, qname, context, target_label="Async DB target"
+            )
+            async with self._async_lock:
+                self._model_cache[model_key] = model_cls
+            return model_cls
 
     def _resolve_or_build_model(
         self,
@@ -335,12 +354,15 @@ class SqlModelRegistry:
 
     # Not a copy-pasted twin: sync md.reflect() vs conn.run_sync(md.reflect) is
     # a genuine concurrency-primitive difference (see get_model()'s comment above).
+    # Both callers (get_model/get_model_async) already hold this md_key's
+    # md_lock/md_async_lock for the whole reflect -> resolve-or-build -> cache
+    # sequence, so no locking happens here — acquiring the same (non-reentrant)
+    # lock again inside would deadlock.
     @staticmethod
     # spaghetti-ignore[sync-async-duplication]: see above
     def _reflect_table(
         engine: Engine,
         md: MetaData,
-        md_lock: threading.Lock,
         *,
         qname: str,
         tname: str,
@@ -348,18 +370,14 @@ class SqlModelRegistry:
     ) -> Table | None:
         tbl = md.tables.get(qname)
         if tbl is None:
-            with md_lock:
-                tbl = md.tables.get(qname)
-                if tbl is None:
-                    md.reflect(bind=engine, only=[tname], schema=schema)
-                tbl = md.tables.get(qname)
+            md.reflect(bind=engine, only=[tname], schema=schema)
+            tbl = md.tables.get(qname)
         return tbl
 
     @staticmethod
     async def _reflect_table_async(
         engine: AsyncEngine,
         md: MetaData,
-        md_lock: asyncio.Lock,
         *,
         qname: str,
         tname: str,
@@ -367,12 +385,9 @@ class SqlModelRegistry:
     ) -> Table | None:
         tbl = md.tables.get(qname)
         if tbl is None:
-            async with md_lock:
-                tbl = md.tables.get(qname)
-                if tbl is None:
-                    async with engine.begin() as conn:
-                        await conn.run_sync(md.reflect, only=[tname], schema=schema)
-                tbl = md.tables.get(qname)
+            async with engine.begin() as conn:
+                await conn.run_sync(md.reflect, only=[tname], schema=schema)
+            tbl = md.tables.get(qname)
         return tbl
 
     def clear(self) -> None:

{boti_data-1.3.0 → boti_data-1.3.2}/src/boti_data/db/sql_repository.py

@@ -26,6 +26,7 @@ from sqlalchemy.orm import Session
 
 from boti_data.db.sql_config import SqlDatabaseConfig
 from boti_data.db.sql_model_registry import get_global_registry
+from boti_data.db.sql_readonly import ReadOnlyAsyncSession, ReadOnlySession
 from boti_data.db.sql_resource import AsyncSqlDatabaseResource, SqlDatabaseResource
 
 __all__ = ["AsyncSqlRepository", "AsyncSqlUnitOfWork", "SqlRepository", "SqlUnitOfWork"]
@@ -297,10 +298,13 @@ class SqlUnitOfWork:
 
     def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         try:
-            if exc_type is None:
-                self._session.commit()
-            else:
+            if exc_type is not None:
                 self._session.rollback()
+            elif not isinstance(self._session, ReadOnlySession):
+                self._session.commit()
+            # else: read-only session, exited cleanly — a read never needs a
+            # commit, and ReadOnlySession.commit() always raises regardless
+            # of whether anything was actually written.
         finally:
             # Each handed-out repository has its own GC leak-warning
             # finalizer (see boti.core.lifecycle) even though its own
@@ -340,10 +344,13 @@ class AsyncSqlUnitOfWork:
 
     async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         try:
-            if exc_type is None:
-                await self._session.commit()
-            else:
+            if exc_type is not None:
                 await self._session.rollback()
+            elif not isinstance(self._session, ReadOnlyAsyncSession):
+                await self._session.commit()
+            # else: read-only session, exited cleanly — a read never needs a
+            # commit, and ReadOnlyAsyncSession.commit() always raises
+            # regardless of whether anything was actually written.
         finally:
             # See SqlUnitOfWork.__exit__'s comment: each handed-out repository
             # has its own GC leak-warning finalizer even though its _acleanup()

{boti_data-1.3.0 → boti_data-1.3.2}/src/boti_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boti-data
-Version: 1.3.0
+Version: 1.3.2
 Summary: Data infrastructure for the Boti ecosystem
 Author: Luis Valverde
 Maintainer-email: Luis Valverde <lvalverdeb@gmail.com>