before_commit callback in middleware

Author: krylosov-aa

docs/examples/index.html

@@ -61,12 +61,10 @@
     <li class="toctree-l2"><a class="reference internal" href="#manually-close-the-transaction-and-session">Manually close the transaction and session</a>
     </li>
     <li class="toctree-l2"><a class="reference internal" href="#multiple-sessions-and-concurrent-execution">Multiple sessions and concurrent execution</a>
-        <ul>
-    <li class="toctree-l3"><a class="reference internal" href="#read-your-own-writes">Read Your Own Writes</a>
     </li>
-    <li class="toctree-l3"><a class="reference internal" href="#rollback">Rollback</a>
+    <li class="toctree-l2"><a class="reference internal" href="#rollback">Rollback</a>
     </li>
-        </ul>
+    <li class="toctree-l2"><a class="reference internal" href="#read-your-own-writes">Read Your Own Writes</a>
     </li>
     </ul>
                 </li>
@@ -238,7 +236,7 @@ <h3 id="manually-close-the-transaction-and-session">Manually close the transacti
     )
     await session.execute(stmt)
 </code></pre>
-<h2 id="multiple-sessions-and-concurrent-execution">Multiple sessions and concurrent execution</h2>
+<h3 id="multiple-sessions-and-concurrent-execution">Multiple sessions and concurrent execution</h3>
 <pre><code class="language-python">import asyncio
 
 from context_async_sqlalchemy import (
@@ -309,6 +307,73 @@ <h2 id="multiple-sessions-and-concurrent-execution">Multiple sessions and concur
         await session.execute(stmt)
         await session.commit()
 </code></pre>
+<h3 id="rollback">Rollback</h3>
+<pre><code class="language-python">from context_async_sqlalchemy import db_session
+from sqlalchemy import insert
+
+from ..database import connection
+from ..models import ExampleTable
+
+
+async def handler_with_db_session_and_exception() -&gt; None:
+    &quot;&quot;&quot;
+    let's imagine that an exception occurred.
+    &quot;&quot;&quot;
+    session = await db_session(connection)
+    stmt = insert(ExampleTable).values(text=&quot;example_with_db_session&quot;)
+    await session.execute(stmt)
+
+    raise Exception(&quot;Some exception&quot;)
+    # transaction automatically rolls back
+</code></pre>
+<pre><code class="language-python">from fastapi import HTTPException
+
+from context_async_sqlalchemy import db_session
+from sqlalchemy import insert
+
+from ..database import connection
+from ..models import ExampleTable
+
+
+async def handler_with_db_session_and_http_exception() -&gt; None:
+    &quot;&quot;&quot;
+    let's imagine that an http exception occurred.
+    &quot;&quot;&quot;
+    session = await db_session(connection)
+    stmt = insert(ExampleTable).values(text=&quot;example_with_db_session&quot;)
+    await session.execute(stmt)
+
+    raise HTTPException(status_code=500)
+    # transaction rolls back automatically by status code
+</code></pre>
+<pre><code class="language-python">from context_async_sqlalchemy import db_session, rollback_db_session
+from sqlalchemy import insert
+
+from ..database import connection
+from ..models import ExampleTable
+
+
+async def handler_with_db_session_and_manual_rollback() -&gt; None:
+    &quot;&quot;&quot;
+    An example of a handle that uses a rollback
+    &quot;&quot;&quot;
+    # it's convenient this way
+    await _insert()
+    await rollback_db_session(connection)
+
+    # but it's possible this way too
+    await _insert()
+    session = await db_session(connection)
+    await session.rollback()
+
+
+async def _insert() -&gt; None:
+    session = await db_session(connection)
+    stmt = insert(ExampleTable).values(
+        text=&quot;example_with_db_session_and_manual_close&quot;
+    )
+    await session.execute(stmt)
+</code></pre>
 <h3 id="read-your-own-writes">Read Your Own Writes</h3>
 <p>The "Read Your Own Writes" pattern ensures that after a write request, subsequent read requests
 always see the data that was just written — even when reads are served by a replica.</p>
@@ -389,74 +454,6 @@ <h3 id="read-your-own-writes">Read Your Own Writes</h3>
 <p>The <a href="https://github.com/krylosov-aa/pg-status">pg-status</a> provides a ready-made helper
 for exactly this: it lets you poll replicas and pick the first one whose replay LSN is at or
 ahead of the required value, falling back to the primary if none qualifies.</p>
-<hr />
-<h3 id="rollback">Rollback</h3>
-<pre><code class="language-python">from context_async_sqlalchemy import db_session
-from sqlalchemy import insert
-
-from ..database import connection
-from ..models import ExampleTable
-
-
-async def handler_with_db_session_and_exception() -&gt; None:
-    &quot;&quot;&quot;
-    let's imagine that an exception occurred.
-    &quot;&quot;&quot;
-    session = await db_session(connection)
-    stmt = insert(ExampleTable).values(text=&quot;example_with_db_session&quot;)
-    await session.execute(stmt)
-
-    raise Exception(&quot;Some exception&quot;)
-    # transaction automatically rolls back
-</code></pre>
-<pre><code class="language-python">from fastapi import HTTPException
-
-from context_async_sqlalchemy import db_session
-from sqlalchemy import insert
-
-from ..database import connection
-from ..models import ExampleTable
-
-
-async def handler_with_db_session_and_http_exception() -&gt; None:
-    &quot;&quot;&quot;
-    let's imagine that an http exception occurred.
-    &quot;&quot;&quot;
-    session = await db_session(connection)
-    stmt = insert(ExampleTable).values(text=&quot;example_with_db_session&quot;)
-    await session.execute(stmt)
-
-    raise HTTPException(status_code=500)
-    # transaction rolls back automatically by status code
-</code></pre>
-<pre><code class="language-python">from context_async_sqlalchemy import db_session, rollback_db_session
-from sqlalchemy import insert
-
-from ..database import connection
-from ..models import ExampleTable
-
-
-async def handler_with_db_session_and_manual_rollback() -&gt; None:
-    &quot;&quot;&quot;
-    An example of a handle that uses a rollback
-    &quot;&quot;&quot;
-    # it's convenient this way
-    await _insert()
-    await rollback_db_session(connection)
-
-    # but it's possible this way too
-    await _insert()
-    session = await db_session(connection)
-    await session.rollback()
-
-
-async def _insert() -&gt; None:
-    session = await db_session(connection)
-    stmt = insert(ExampleTable).values(
-        text=&quot;example_with_db_session_and_manual_close&quot;
-    )
-    await session.execute(stmt)
-</code></pre>
 
             </div>
           </div><footer>

docs/index.html

@@ -221,5 +221,5 @@ <h2 id="how-it-works">How it works</h2>
 
 <!--
 MkDocs version : 1.6.1
-Build Date UTC : 2026-06-14 09:48:21.276136+00:00
+Build Date UTC : 2026-06-14 09:53:08.796219+00:00
 -->

docs/search/search_index.json

@@ -134,7 +134,7 @@ async def _insert_3() -> None:
     await session.execute(stmt)
 ```
 
-## Multiple sessions and concurrent execution
+### Multiple sessions and concurrent execution
 
 ```python
 import asyncio
@@ -208,6 +208,80 @@ async def _insert_non_ctx_manual() -> None:
         await session.commit()
 ```
 
+### Rollback
+
+```python
+from context_async_sqlalchemy import db_session
+from sqlalchemy import insert
+
+from ..database import connection
+from ..models import ExampleTable
+
+
+async def handler_with_db_session_and_exception() -> None:
+    """
+    let's imagine that an exception occurred.
+    """
+    session = await db_session(connection)
+    stmt = insert(ExampleTable).values(text="example_with_db_session")
+    await session.execute(stmt)
+
+    raise Exception("Some exception")
+    # transaction automatically rolls back
+```
+
+```python
+from fastapi import HTTPException
+
+from context_async_sqlalchemy import db_session
+from sqlalchemy import insert
+
+from ..database import connection
+from ..models import ExampleTable
+
+
+async def handler_with_db_session_and_http_exception() -> None:
+    """
+    let's imagine that an http exception occurred.
+    """
+    session = await db_session(connection)
+    stmt = insert(ExampleTable).values(text="example_with_db_session")
+    await session.execute(stmt)
+
+    raise HTTPException(status_code=500)
+    # transaction rolls back automatically by status code
+```
+
+```python
+from context_async_sqlalchemy import db_session, rollback_db_session
+from sqlalchemy import insert
+
+from ..database import connection
+from ..models import ExampleTable
+
+
+async def handler_with_db_session_and_manual_rollback() -> None:
+    """
+    An example of a handle that uses a rollback
+    """
+    # it's convenient this way
+    await _insert()
+    await rollback_db_session(connection)
+
+    # but it's possible this way too
+    await _insert()
+    session = await db_session(connection)
+    await session.rollback()
+
+
+async def _insert() -> None:
+    session = await db_session(connection)
+    stmt = insert(ExampleTable).values(
+        text="example_with_db_session_and_manual_close"
+    )
+    await session.execute(stmt)
+```
+
 ### Read Your Own Writes
 
 The "Read Your Own Writes" pattern ensures that after a write request, subsequent read requests
@@ -303,79 +377,3 @@ it against the client-supplied LSN.
 The [pg-status](https://github.com/krylosov-aa/pg-status) provides a ready-made helper
 for exactly this: it lets you poll replicas and pick the first one whose replay LSN is at or
 ahead of the required value, falling back to the primary if none qualifies.
-
----
-
-### Rollback
-
-```python
-from context_async_sqlalchemy import db_session
-from sqlalchemy import insert
-
-from ..database import connection
-from ..models import ExampleTable
-
-
-async def handler_with_db_session_and_exception() -> None:
-    """
-    let's imagine that an exception occurred.
-    """
-    session = await db_session(connection)
-    stmt = insert(ExampleTable).values(text="example_with_db_session")
-    await session.execute(stmt)
-
-    raise Exception("Some exception")
-    # transaction automatically rolls back
-```
-
-```python
-from fastapi import HTTPException
-
-from context_async_sqlalchemy import db_session
-from sqlalchemy import insert
-
-from ..database import connection
-from ..models import ExampleTable
-
-
-async def handler_with_db_session_and_http_exception() -> None:
-    """
-    let's imagine that an http exception occurred.
-    """
-    session = await db_session(connection)
-    stmt = insert(ExampleTable).values(text="example_with_db_session")
-    await session.execute(stmt)
-
-    raise HTTPException(status_code=500)
-    # transaction rolls back automatically by status code
-```
-
-```python
-from context_async_sqlalchemy import db_session, rollback_db_session
-from sqlalchemy import insert
-
-from ..database import connection
-from ..models import ExampleTable
-
-
-async def handler_with_db_session_and_manual_rollback() -> None:
-    """
-    An example of a handle that uses a rollback
-    """
-    # it's convenient this way
-    await _insert()
-    await rollback_db_session(connection)
-
-    # but it's possible this way too
-    await _insert()
-    session = await db_session(connection)
-    await session.rollback()
-
-
-async def _insert() -> None:
-    session = await db_session(connection)
-    stmt = insert(ExampleTable).values(
-        text="example_with_db_session_and_manual_close"
-    )
-    await session.execute(stmt)
-```