matrx-orm 3.1.97__tar.gz → 3.1.98__tar.gz

{matrx_orm-3.1.97 → matrx_orm-3.1.98}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.97
+Version: 3.1.98
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current

{matrx_orm-3.1.97 → matrx_orm-3.1.98}/matrx_orm/core/FEATURE.md

@@ -126,7 +126,52 @@ Pinned by `tests/level1/test_rls_session_scope.py` and
 
 Verified against code: 2026-08-17.
 
+## Idle-in-transaction ceiling and long-transaction naming
+
+**A pooled connection may not sit idle inside a transaction.** Every pool ships
+`idle_in_transaction_session_timeout = IDLE_IN_TRANSACTION_TIMEOUT_MS` (60s) in
+`server_settings`, so Postgres ends a session that opens a transaction and then
+stops talking. A long-*running* statement is `active` and is never affected —
+the timeout counts idle time only. A caller with a genuine need overrides the
+key through its own `server_settings`.
+
+Why it is not optional: an open transaction holds its locks (DDL queues behind
+it for the WHOLE database) and pins the cluster xmin horizon, which stops
+autovacuum from reclaiming dead tuples everywhere, not just on the tables that
+session touched. On 2026-08-21 one session sat idle in a transaction for 18+
+minutes; every `CREATE POLICY` on the live database blocked to `lock_timeout`
+while the migration applier told each agent to fix SQL that was correct.
+
+**Startup parameters do not survive a pooler.** Supavisor drops non-allowlisted
+startup parameters in both transaction and session mode (measured 2026-08-21:
+`SHOW idle_in_transaction_session_timeout` returns `0` on a connection that
+requested 2000ms, and `PGOPTIONS` is dropped the same way). The package default
+therefore governs direct-Postgres deployments; behind a pooler the same ceiling
+has to be a server-side role or database default. That split is the
+package-vs-implementation boundary, not a bug in either half.
+
+**The one session that legitimately needs an exemption is a backup.** A
+parallel `pg_dump` leader holds its snapshot `idle in transaction` for the whole
+dump by design, so it must be exempt — and because a pooler eats the exemption,
+a dump belongs on the DIRECT host, which is what it wants anyway (one long-lived
+session is the opposite of what a pooler is for). That is the standard shape
+everywhere: tight ceiling for application sessions, explicit exemption for the
+backup session, and the exemption VERIFIED before the dump starts rather than
+assumed (`db/mirror/refresh.py::resolve_dump_endpoint`).
+
+**`long_transactions()` names the blocker.** `matrx_orm.long_transactions`
+(async) and `matrx_orm.long_transactions_sql` (a parameter-free SQL string, so
+sync psycopg tooling runs the identical query) return every transaction open
+past a threshold, categorized `idle_in_transaction` or `long_active`, with
+`describe_transaction(s)` for the human line. One primitive serves the
+in-process guard and the migration applier, so an alarm and an error message
+can never disagree about who the blocker was.
+
+Verified against the live database: 2026-08-21.
+
 ## Change log
+- 2026-08-21: Added the idle-in-transaction ceiling on every pool and the
+  `long_transactions` blocker-naming primitive (feedback c72a32ac).
 
 - 2026-08-18: Indexed ModelMeta-derived table names so generated models remain
   discoverable by exact schema/table identity.

{matrx_orm-3.1.97 → matrx_orm-3.1.98}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.97"
+version = "3.1.98"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching"
 readme = "README.md"
 license = { text = "MIT" }