sync docs changes to md

Author: krylosov-aa

docs/api/index.html

@@ -68,6 +68,10 @@
     </li>
     <li class="toctree-l3"><a class="reference internal" href="#create_session">create_session</a>
     </li>
+        </ul>
+    </li>
+    <li class="toctree-l2"><a class="reference internal" href="#creates-a-new-session-used-internally-by-the-library-you-may-never-need-to-call-it-directly">Creates a new session. Used internally by the library. You may never need to call it directly.</a>
+        <ul>
     <li class="toctree-l3"><a class="reference internal" href="#session_maker">session_maker</a>
     </li>
     <li class="toctree-l3"><a class="reference internal" href="#close">close</a>
@@ -213,8 +217,7 @@ <h3 id="connect">connect</h3>
 </code></pre>
 <p>Establishes a connection to the specified host.
 It doesn’t need to be called explicitly.
-The first session request automatically
-establishes the connection.</p>
+The first session request automatically establishes the connection.</p>
 <hr />
 <h3 id="change_host">change_host</h3>
 <pre><code class="language-python">async def change_host(self: DBConnect, host: str) -&gt; None:
@@ -225,9 +228,7 @@ <h3 id="change_host">change_host</h3>
 <h3 id="create_session">create_session</h3>
 <pre><code class="language-python">async def create_session(self: DBConnect) -&gt; AsyncSession:
 </code></pre>
-<p>Creates a new session the library uses internally.
-You never need to call it directly. (Only maybe in some special cases.)</p>
-<hr />
+<h2 id="creates-a-new-session-used-internally-by-the-library-you-may-never-need-to-call-it-directly">Creates a new session. Used internally by the library. You may never need to call it directly.</h2>
 <h3 id="session_maker">session_maker</h3>
 <pre><code class="language-python">async def session_maker(self: DBConnect) -&gt; async_sessionmaker[AsyncSession]:
 </code></pre>
@@ -304,7 +305,8 @@ <h3 id="atomic_db_session">atomic_db_session</h3>
 </code></pre>
 <p>A context manager you can use to wrap another function which
 uses a context session, making that call isolated within its own transaction.</p>
-<p>Several options define how a function handles an open transaction.</p>
+<p>There are several options that define how the function will handle
+an open transaction.</p>
 <p>current_transaction:</p>
 <ul>
 <li><code>commit</code> - commits the open transaction and starts a new one</li>
@@ -321,15 +323,14 @@ <h3 id="commit_db_session">commit_db_session</h3>
 <h3 id="rollback_db_session">rollback_db_session</h3>
 <pre><code class="language-python">async def rollback_db_session(connect: DBConnect) -&gt; None:
 </code></pre>
-<p>Rolls back an active session.</p>
+<p>Rollbacks the active session.</p>
 <hr />
 <h3 id="close_db_session">close_db_session</h3>
 <pre><code class="language-python">async def close_db_session(connect: DBConnect) -&gt; None:
 </code></pre>
-<p>Closes the current context session and returns the connection to the pool.
-If you close an uncommitted transaction, the connection rolls back</p>
-<p>This is useful when you need to run a database query at the start of the
-handler, then continue working over time without keeping the connection open.</p>
+<p>Closes the current context session. The connection is returned to the pool.
+If you close an uncommitted transaction, the connection rolls back.</p>
+<p>Use if you have more work you need to complete without keeping the connection open.</p>
 <hr />
 <h3 id="new_non_ctx_session">new_non_ctx_session</h3>
 <pre><code class="language-python">@asynccontextmanager
@@ -404,7 +405,6 @@ <h3 id="put_savepoint_session_in_ctx">put_savepoint_session_in_ctx</h3>
 <p>Sets the context to a session that uses a save point instead of creating
         a transaction. You need to pass the session you're using inside
         your tests to attach a new session to the same connection.</p>
-
 <pre><code>It is important to use this function inside set_test_context.
 </code></pre>
 <p>Learn more about <a href="../testing/">testing</a></p>

docs/examples/index.html

@@ -223,6 +223,7 @@ <h3 id="manually-close-the-transaction-and-session">Manually close the transacti
 
     # We closed the transaction
     await commit_db_session(connection)
+
     # We closed the session, which returned the connection to the pool automatically.
     # Use if you have more work you need to complete without keeping the connection open.
     await close_db_session(connection)

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-01-09 21:16:59.924431+00:00
+Build Date UTC : 2026-01-12 21:26:27.089860+00:00
 -->

docs/master_replica/index.html

@@ -103,24 +103,24 @@
           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
             <div class="section" itemprop="articleBody">
 
-                <h1 id="masterreplica-or-several-databases-at-the-same-time">Using multiple databases at the same time (master/replica)</h1>
-                <p><code>db_session</code> and other functions accept a <code>DBConnect</code> instance as input. This approach allows you to work with multiple hosts simultaneously. This system allows you to manage scalability and version control.</p>
-                <ul>
-                  <li><b>Master:</b> The primary database which runs the "live" version of your information, the location of your primary data set. The master database
-                    handles INSERT, DELETE, and UPDATE API calls.
-                  </li>
-                  <li><b>Replicas:</b> Secondary database(s) which run READ-ONLY versions of your information and receive updates from the master database.</li>
-                </ul>
+                <h1 id="using-multiple-database-hosts-masterreplica">Using multiple database hosts (master/replica)</h1>
+<p><code>db_session</code> and other functions accept a <code>DBConnect</code> instance as
+input.
+This approach allows you to work with multiple hosts simultaneously.
+This system allows you to manage scalability and reliability.</p>
+<ul>
+<li><strong>Master</strong> (also called <strong>Primary</strong>): The main database host that handles all write operations (INSERT, UPDATE, DELETE) and read operations. It is the single source of truth</li>
+<li><strong>Replica</strong> (also called <strong>Standby</strong> or <strong>Secondary</strong>): Secondary database host(s) which run READ-ONLY versions of your information and receive updates from the master database.</li>
+</ul>
 <p><code>DBConnect</code> accepts factory functions instead of ready-made objects, making it easy to switch hosts when needed.</p>
-
 <p><code>libpq</code> can detect the master and replica when creating an engine,
 but it only does this once - at creation time.
 The <code>before_create_session_handler</code> hook allows you to change the host at
 runtime if the master or replica changes.
-
-<p><b>You need third-party functionality to determine which host is the master or the replica.</b></p>
-<h4 id="change_host">I have an extremely lightweight microservice <a href="https://github.com/krylosov-aa/pg-status">pg-status</a> that fits perfectly here</h4>
-<p>The engine is not created when <code>DBConnect</code> initializes, also known as lazy initialization. It is created only on the first request.
+You need third-party functionality to determine which host is the master or the replica.</p>
+<h4 id="i-have-an-extremely-lightweight-microservice-pg-status-that-fits-perfectly-here">I have an extremely lightweight microservice <a href="https://github.com/krylosov-aa/pg-status">pg-status</a> that fits perfectly here.</h4>
+<p>The engine is not created when <code>DBConnect</code> initializes, also known as lazy initialization.
+It is created only on the first request.
 The library uses lazy initialization in many places.</p>
 <pre><code class="language-python">from context_async_sqlalchemy import DBConnect
 

docs/search/search_index.json

@@ -106,30 +106,36 @@
             <div class="section" itemprop="articleBody">
 
                 <h1 id="testing">Testing</h1>
-<p>When testing with a real database, one important problem needs to be solved: ensuring data isolation between tests. There are two approaches:
-  <ol>
-    <li><b>Separate sessions</b>: The test uses its own session that prepares data and verifies results after execution. The application also has its own session.
-    <ul>
-      <li>It is a more "honest" way to test the application.</li>
-      <li>Verifies how it handles sessions and transactions automatically.</li>
-      <li>The ability to inspect the database state when the test is paused.</li>
-      <li>Complex session management scenarios make other test methods difficult or impossible (e.g., concurrent query execution).</li>
-    </ul>
-    <li><b>Shared session and transaction:</b> The test and the application share the same session and transaction.
-    <ul>
-      <li>Rolling back transactions is faster and takes less time than starting a new session.</li>
-      </ul>
-  </ol>
-</p>
-
+<p>When testing with a real database, one important problem needs to be solved: ensuring data isolation between tests.
+There are two approaches:</p>
+<ol>
+<li>
+<p><strong>Separate sessions</strong>: The test uses its own session that prepares data and
+verifies results after execution. The application also has its own session.</p>
+</li>
+<li>
+<p>It is a more "honest" way to test the application.</p>
+</li>
+<li>Verifies how it handles sessions and transactions automatically.</li>
+<li>
+<p>The ability to inspect the database state when the test is paused.
+Complex session management scenarios make other test methods difficult or impossible (e.g., concurrent query execution).</p>
+</li>
+<li>
+<p><strong>Shared session and transaction</strong>: The test and the application share the same session and transaction.</p>
+</li>
+<li>
+<p>Rolling back transactions is faster and takes less time than starting a new session.</p>
+</li>
+</ol>
 <p>In my projects, I use both approaches at the same time:</p>
 <ul>
 <li>For most tests with simple or common logic, I use a shared transaction for the test and the application</li>
 <li>For more complex cases, or ones that cannot be tested with separate sessions, I use separate transactions.</li>
 </ul>
-<p>The library provides several utilities that can be used in tests (e.g., fixtures). They create tests that share a common transaction between the test
-and the application. You achieve data isolation by rolling back transactions.
-
+<p>The library provides several utilities that can be used in tests (e.g., fixtures).
+They create tests that share a common transaction between the test
+and the application. You achieve data isolation by rolling back transactions.</p>
 <p>You can see these capabilities in the examples:</p>
 <p><a href="https://github.com/krylosov-aa/context-async-sqlalchemy/blob/main/examples/fastapi_example/tests/transactional">Here are tests with a common transaction between the
 application and the tests.</a></p>

docs/sitemap.xml.gz

@@ -68,8 +68,7 @@ async def connect(self: DBConnect, host: str) -> None:
 ```
 Establishes a connection to the specified host.
 It doesn’t need to be called explicitly.
-If you don't use the call, the first session request will automatically
-establishes the connection.
+The first session request automatically establishes the connection.
 
 ---
 
@@ -317,7 +316,7 @@ It is intended to test the application when it shares a single transaction.
 Use `auto_close=False` if you’re using a test session and transaction
 that you close elsewhere in your code.
 
-Use `auto_close=True` if you want to call a function
+Use `auto_close=True` to call a function
 in a test that uses a context while the middleware is not
 active. All sessions close automatically.
 

docs/testing/index.html

@@ -3,12 +3,12 @@
 
 Concurrent query execution deserves special attention.
 In SQLAlchemy, you can’t run multiple queries concurrently within the same
-session - you need to create a new one.
+session. You need to create a new one.
 
 The library provides two simple ways to execute queries concurrently:
 
-- Run a function in a new context - `run_in_new_ctx`
-- Create a new session that is completely independent of the current context -
+- Run a function in a new context: `run_in_new_ctx`
+- Create a new session that is independent of the current context:
 `new_non_ctx_atomic_session` or `new_non_ctx_session`
 
 

docs_sources/docs/api.md

@@ -121,7 +121,7 @@ async def _insert_2() -> None:
     # We closed the transaction
     await commit_db_session(connection)
 
-    # We closed the session and returned the connection to the pool.
+    # We closed the session, which returned the connection to the pool automatically.
     # Use if you have more work you need to complete without keeping the connection open.
     await close_db_session(connection)
 
@@ -227,7 +227,7 @@ async def handler_with_db_session_and_exception() -> None:
     await session.execute(stmt)
 
     raise Exception("Some exception")
-    # transaction rolls back automatically
+    # transaction automatically rolls back
 ```
 
 ```python