mirror of
https://github.com/d3vyce/fastapi-toolsets.git
synced 2026-08-05 16:14:08 +00:00
Deployed 06d49d5 to v5.0 with Zensical 0.0.43 and mike 2.2.0+zensical-0.1.0
This commit is contained in:
github-actions[bot]
+108
-92
@@ -2102,6 +2102,22 @@
|
||||
</span><span id="__span-0-13"><a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a> <span class="o">...</span>
|
||||
</span></code></pre></div>
|
||||
<p>The <code>Database</code> instance <strong>is</strong> the dependency: use it directly as <code>Depends(db)</code>. The whole request runs as a single transaction (CRUD writes use savepoints under it).</p>
|
||||
<p>The <strong>URL</strong> may be a plain string or a Pydantic <a href="https://docs.pydantic.dev/latest/api/networks/#pydantic.networks.PostgresDsn"><code>PostgresDsn</code></a>. In URL mode you can tune the engine: pass <code>connect_args</code> for DBAPI-level options and any other keyword for <code>create_async_engine</code> (e.g. <code>pool_size</code>, <code>echo</code>, <code>pool_pre_ping</code>):</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pydantic_settings</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseSettings</span>
|
||||
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">PostgresDsn</span>
|
||||
</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>
|
||||
</span><span id="__span-1-4"><a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a><span class="k">class</span><span class="w"> </span><span class="nc">Settings</span><span class="p">(</span><span class="n">BaseSettings</span><span class="p">):</span>
|
||||
</span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a> <span class="n">database_url</span><span class="p">:</span> <span class="n">PostgresDsn</span>
|
||||
</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a>
|
||||
</span><span id="__span-1-7"><a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a><span class="n">settings</span> <span class="o">=</span> <span class="n">Settings</span><span class="p">()</span>
|
||||
</span><span id="__span-1-8"><a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a>
|
||||
</span><span id="__span-1-9"><a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a><span class="n">db</span> <span class="o">=</span> <span class="n">Database</span><span class="p">(</span>
|
||||
</span><span id="__span-1-10"><a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a> <span class="n">settings</span><span class="o">.</span><span class="n">database_url</span><span class="p">,</span>
|
||||
</span><span id="__span-1-11"><a id="__codelineno-1-11" name="__codelineno-1-11" href="#__codelineno-1-11"></a> <span class="n">pool_size</span><span class="o">=</span><span class="mi">20</span><span class="p">,</span>
|
||||
</span><span id="__span-1-12"><a id="__codelineno-1-12" name="__codelineno-1-12" href="#__codelineno-1-12"></a> <span class="n">pool_pre_ping</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
|
||||
</span><span id="__span-1-13"><a id="__codelineno-1-13" name="__codelineno-1-13" href="#__codelineno-1-13"></a> <span class="n">connect_args</span><span class="o">=</span><span class="p">{</span><span class="s2">"server_settings"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"application_name"</span><span class="p">:</span> <span class="s2">"myapp"</span><span class="p">}},</span>
|
||||
</span><span id="__span-1-14"><a id="__codelineno-1-14" name="__codelineno-1-14" href="#__codelineno-1-14"></a><span class="p">)</span>
|
||||
</span></code></pre></div>
|
||||
<h2 id="committing-before-the-response">Committing before the response<a class="headerlink" href="#committing-before-the-response" title="Permanent link">¶</a></h2>
|
||||
<p><a href="../../reference/db/#fastapi_toolsets.db.Database"><code>db.install(app)</code></a> adds a middleware that commits the request's session when the response starts, after the endpoint returns and before the body is sent. With the middleware installed, the dependency does not commit again.</p>
|
||||
<p>The request is committed as a single transaction:</p>
|
||||
@@ -2117,75 +2133,75 @@
|
||||
</div>
|
||||
<h2 id="lifespan">Lifespan<a class="headerlink" href="#lifespan" title="Permanent link">¶</a></h2>
|
||||
<p><code>db.install(app)</code> disposes the engine on shutdown, composing around your own lifespan:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
|
||||
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>
|
||||
</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a><span class="nd">@asynccontextmanager</span>
|
||||
</span><span id="__span-1-4"><a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">app</span><span class="p">):</span>
|
||||
</span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a> <span class="k">await</span> <span class="n">warm_cache</span><span class="p">()</span> <span class="c1"># your startup</span>
|
||||
</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a> <span class="k">yield</span>
|
||||
</span><span id="__span-1-7"><a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a> <span class="k">await</span> <span class="n">flush_metrics</span><span class="p">()</span> <span class="c1"># your shutdown</span>
|
||||
</span><span id="__span-1-8"><a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a>
|
||||
</span><span id="__span-1-9"><a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">(</span><span class="n">lifespan</span><span class="o">=</span><span class="n">lifespan</span><span class="p">)</span>
|
||||
</span><span id="__span-1-10"><a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a><span class="n">db</span><span class="o">.</span><span class="n">install</span><span class="p">(</span><span class="n">app</span><span class="p">)</span> <span class="c1"># your shutdown runs first, then the engine is disposed</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
|
||||
</span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>
|
||||
</span><span id="__span-2-3"><a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="nd">@asynccontextmanager</span>
|
||||
</span><span id="__span-2-4"><a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">app</span><span class="p">):</span>
|
||||
</span><span id="__span-2-5"><a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a> <span class="k">await</span> <span class="n">warm_cache</span><span class="p">()</span> <span class="c1"># your startup</span>
|
||||
</span><span id="__span-2-6"><a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a> <span class="k">yield</span>
|
||||
</span><span id="__span-2-7"><a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a> <span class="k">await</span> <span class="n">flush_metrics</span><span class="p">()</span> <span class="c1"># your shutdown</span>
|
||||
</span><span id="__span-2-8"><a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a>
|
||||
</span><span id="__span-2-9"><a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">(</span><span class="n">lifespan</span><span class="o">=</span><span class="n">lifespan</span><span class="p">)</span>
|
||||
</span><span id="__span-2-10"><a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a><span class="n">db</span><span class="o">.</span><span class="n">install</span><span class="p">(</span><span class="n">app</span><span class="p">)</span> <span class="c1"># your shutdown runs first, then the engine is disposed</span>
|
||||
</span></code></pre></div>
|
||||
<p>If you have no lifespan of your own, <a href="../../reference/db/#fastapi_toolsets.db.Database"><code>db.lifespan</code></a> works standalone as <code>FastAPI(lifespan=db.lifespan)</code>. Engine disposal is idempotent and is a no-op when you passed your own <code>engine=</code>.</p>
|
||||
<h2 id="session-context-manager">Session context manager<a class="headerlink" href="#session-context-manager" title="Permanent link">¶</a></h2>
|
||||
<p>Use <a href="../../reference/db/#fastapi_toolsets.db.Database"><code>db.session()</code></a> for sessions outside request handlers (e.g. background tasks, CLI commands). It commits on clean exit and rolls back on exception:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">seed</span><span class="p">():</span>
|
||||
</span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a> <span class="k">async</span> <span class="k">with</span> <span class="n">db</span><span class="o">.</span><span class="n">session</span><span class="p">()</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
||||
</span><span id="__span-2-3"><a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a> <span class="o">...</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">seed</span><span class="p">():</span>
|
||||
</span><span id="__span-3-2"><a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a> <span class="k">async</span> <span class="k">with</span> <span class="n">db</span><span class="o">.</span><span class="n">session</span><span class="p">()</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
||||
</span><span id="__span-3-3"><a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a> <span class="o">...</span>
|
||||
</span></code></pre></div>
|
||||
<h2 id="transactions">Transactions<a class="headerlink" href="#transactions" title="Permanent link">¶</a></h2>
|
||||
<p><a href="../../reference/db/#fastapi_toolsets.db.transaction"><code>transaction</code></a> opens a transaction on a session, using a savepoint when one is already open so it nests safely:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">transaction</span>
|
||||
</span><span id="__span-3-2"><a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a>
|
||||
</span><span id="__span-3-3"><a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_user_with_role</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
|
||||
</span><span id="__span-3-4"><a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a> <span class="k">async</span> <span class="k">with</span> <span class="n">transaction</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
|
||||
</span><span id="__span-3-5"><a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a> <span class="o">...</span>
|
||||
</span><span id="__span-3-6"><a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a> <span class="k">async</span> <span class="k">with</span> <span class="n">transaction</span><span class="p">(</span><span class="n">session</span><span class="p">):</span> <span class="c1"># uses a savepoint</span>
|
||||
</span><span id="__span-3-7"><a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a> <span class="o">...</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-4-1"><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">transaction</span>
|
||||
</span><span id="__span-4-2"><a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a>
|
||||
</span><span id="__span-4-3"><a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_user_with_role</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
|
||||
</span><span id="__span-4-4"><a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a> <span class="k">async</span> <span class="k">with</span> <span class="n">transaction</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
|
||||
</span><span id="__span-4-5"><a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a> <span class="o">...</span>
|
||||
</span><span id="__span-4-6"><a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a> <span class="k">async</span> <span class="k">with</span> <span class="n">transaction</span><span class="p">(</span><span class="n">session</span><span class="p">):</span> <span class="c1"># uses a savepoint</span>
|
||||
</span><span id="__span-4-7"><a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a> <span class="o">...</span>
|
||||
</span></code></pre></div>
|
||||
<p>When you have a <code>Database</code>, <a href="../../reference/db/#fastapi_toolsets.db.Database"><code>db.begin()</code></a> opens a session already inside a transaction:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-4-1"><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="k">async</span> <span class="k">with</span> <span class="n">db</span><span class="o">.</span><span class="n">begin</span><span class="p">()</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
||||
</span><span id="__span-4-2"><a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a> <span class="n">session</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">User</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">"ada"</span><span class="p">))</span> <span class="c1"># commits on exit, rolls back on exception</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="k">async</span> <span class="k">with</span> <span class="n">db</span><span class="o">.</span><span class="n">begin</span><span class="p">()</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
||||
</span><span id="__span-5-2"><a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a> <span class="n">session</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">User</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">"ada"</span><span class="p">))</span> <span class="c1"># commits on exit, rolls back on exception</span>
|
||||
</span></code></pre></div>
|
||||
<h2 id="table-locking">Table locking<a class="headerlink" href="#table-locking" title="Permanent link">¶</a></h2>
|
||||
<p><a href="../../reference/db/#fastapi_toolsets.db.Database"><code>db.lock_tables</code></a> acquires PostgreSQL table-level locks for a critical section. It opens a dedicated session internally and releases the lock when the context exits:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">LockMode</span>
|
||||
</span><span id="__span-5-2"><a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a>
|
||||
</span><span id="__span-5-3"><a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><span class="k">async</span> <span class="k">with</span> <span class="n">db</span><span class="o">.</span><span class="n">lock_tables</span><span class="p">([</span><span class="n">User</span><span class="p">],</span> <span class="n">mode</span><span class="o">=</span><span class="n">LockMode</span><span class="o">.</span><span class="n">EXCLUSIVE</span><span class="p">)</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
||||
</span><span id="__span-5-4"><a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a> <span class="c1"># No other transaction can modify User until this block exits</span>
|
||||
</span><span id="__span-5-5"><a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a> <span class="o">...</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">LockMode</span>
|
||||
</span><span id="__span-6-2"><a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a>
|
||||
</span><span id="__span-6-3"><a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a><span class="k">async</span> <span class="k">with</span> <span class="n">db</span><span class="o">.</span><span class="n">lock_tables</span><span class="p">([</span><span class="n">User</span><span class="p">],</span> <span class="n">mode</span><span class="o">=</span><span class="n">LockMode</span><span class="o">.</span><span class="n">EXCLUSIVE</span><span class="p">)</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
||||
</span><span id="__span-6-4"><a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a> <span class="c1"># No other transaction can modify User until this block exits</span>
|
||||
</span><span id="__span-6-5"><a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a> <span class="o">...</span>
|
||||
</span></code></pre></div>
|
||||
<p>Available lock modes are defined in <a href="../../reference/db/#fastapi_toolsets.db.LockMode"><code>LockMode</code></a>: <code>ACCESS_SHARE</code>, <code>ROW_SHARE</code>, <code>ROW_EXCLUSIVE</code>, <code>SHARE_UPDATE_EXCLUSIVE</code>, <code>SHARE</code>, <code>SHARE_ROW_EXCLUSIVE</code>, <code>EXCLUSIVE</code>, <code>ACCESS_EXCLUSIVE</code>.</p>
|
||||
<p>Pass <code>timeout</code> to limit how long the lock waits. On timeout, a <a href="../../reference/exceptions/#fastapi_toolsets.exceptions.exceptions.LockTimeoutError"><code>LockTimeoutError</code></a> is raised instead of a raw database error:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="k">async</span> <span class="k">with</span> <span class="n">db</span><span class="o">.</span><span class="n">lock_tables</span><span class="p">([</span><span class="n">Order</span><span class="p">],</span> <span class="n">timeout</span><span class="o">=</span><span class="s2">"2s"</span><span class="p">)</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
||||
</span><span id="__span-6-2"><a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a> <span class="o">...</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="k">async</span> <span class="k">with</span> <span class="n">db</span><span class="o">.</span><span class="n">lock_tables</span><span class="p">([</span><span class="n">Order</span><span class="p">],</span> <span class="n">timeout</span><span class="o">=</span><span class="s2">"2s"</span><span class="p">)</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
||||
</span><span id="__span-7-2"><a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a> <span class="o">...</span>
|
||||
</span></code></pre></div>
|
||||
<h2 id="advisory-locking">Advisory locking<a class="headerlink" href="#advisory-locking" title="Permanent link">¶</a></h2>
|
||||
<p><a href="../../reference/db/#fastapi_toolsets.db.advisory_lock"><code>advisory_lock</code></a> acquires a PostgreSQL session-level advisory lock on a session you provide. The lock is released when the context exits:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">advisory_lock</span>
|
||||
</span><span id="__span-7-2"><a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a>
|
||||
</span><span id="__span-7-3"><a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a><span class="c1"># Blocking exclusive lock: waits until the lock is free</span>
|
||||
</span><span id="__span-7-4"><a id="__codelineno-7-4" name="__codelineno-7-4" href="#__codelineno-7-4"></a><span class="k">async</span> <span class="k">with</span> <span class="n">advisory_lock</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="mi">42</span><span class="p">):</span>
|
||||
</span><span id="__span-7-5"><a id="__codelineno-7-5" name="__codelineno-7-5" href="#__codelineno-7-5"></a> <span class="o">...</span>
|
||||
</span><span id="__span-7-6"><a id="__codelineno-7-6" name="__codelineno-7-6" href="#__codelineno-7-6"></a>
|
||||
</span><span id="__span-7-7"><a id="__codelineno-7-7" name="__codelineno-7-7" href="#__codelineno-7-7"></a><span class="c1"># Non-blocking: yields False immediately if already held</span>
|
||||
</span><span id="__span-7-8"><a id="__codelineno-7-8" name="__codelineno-7-8" href="#__codelineno-7-8"></a><span class="k">async</span> <span class="k">with</span> <span class="n">advisory_lock</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="mi">42</span><span class="p">,</span> <span class="n">nowait</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="k">as</span> <span class="n">acquired</span><span class="p">:</span>
|
||||
</span><span id="__span-7-9"><a id="__codelineno-7-9" name="__codelineno-7-9" href="#__codelineno-7-9"></a> <span class="k">if</span> <span class="ow">not</span> <span class="n">acquired</span><span class="p">:</span>
|
||||
</span><span id="__span-7-10"><a id="__codelineno-7-10" name="__codelineno-7-10" href="#__codelineno-7-10"></a> <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="mi">409</span><span class="p">,</span> <span class="s2">"Resource is locked"</span><span class="p">)</span>
|
||||
</span><span id="__span-7-11"><a id="__codelineno-7-11" name="__codelineno-7-11" href="#__codelineno-7-11"></a>
|
||||
</span><span id="__span-7-12"><a id="__codelineno-7-12" name="__codelineno-7-12" href="#__codelineno-7-12"></a><span class="c1"># Blocking with a timeout: raises LockTimeoutError if not acquired in time</span>
|
||||
</span><span id="__span-7-13"><a id="__codelineno-7-13" name="__codelineno-7-13" href="#__codelineno-7-13"></a><span class="k">async</span> <span class="k">with</span> <span class="n">advisory_lock</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="mi">42</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="s2">"5s"</span><span class="p">):</span>
|
||||
</span><span id="__span-7-14"><a id="__codelineno-7-14" name="__codelineno-7-14" href="#__codelineno-7-14"></a> <span class="o">...</span>
|
||||
</span><span id="__span-7-15"><a id="__codelineno-7-15" name="__codelineno-7-15" href="#__codelineno-7-15"></a>
|
||||
</span><span id="__span-7-16"><a id="__codelineno-7-16" name="__codelineno-7-16" href="#__codelineno-7-16"></a><span class="c1"># Shared lock: multiple readers allowed simultaneously, blocks exclusive writers</span>
|
||||
</span><span id="__span-7-17"><a id="__codelineno-7-17" name="__codelineno-7-17" href="#__codelineno-7-17"></a><span class="k">async</span> <span class="k">with</span> <span class="n">advisory_lock</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="mi">42</span><span class="p">,</span> <span class="n">shared</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
|
||||
</span><span id="__span-7-18"><a id="__codelineno-7-18" name="__codelineno-7-18" href="#__codelineno-7-18"></a> <span class="o">...</span>
|
||||
</span><span id="__span-7-19"><a id="__codelineno-7-19" name="__codelineno-7-19" href="#__codelineno-7-19"></a>
|
||||
</span><span id="__span-7-20"><a id="__codelineno-7-20" name="__codelineno-7-20" href="#__codelineno-7-20"></a><span class="c1"># Two-integer key for namespacing (e.g. lock_type + resource_id)</span>
|
||||
</span><span id="__span-7-21"><a id="__codelineno-7-21" name="__codelineno-7-21" href="#__codelineno-7-21"></a><span class="k">async</span> <span class="k">with</span> <span class="n">advisory_lock</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">user_id</span><span class="p">)):</span>
|
||||
</span><span id="__span-7-22"><a id="__codelineno-7-22" name="__codelineno-7-22" href="#__codelineno-7-22"></a> <span class="o">...</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-8-1"><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">advisory_lock</span>
|
||||
</span><span id="__span-8-2"><a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a>
|
||||
</span><span id="__span-8-3"><a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a><span class="c1"># Blocking exclusive lock: waits until the lock is free</span>
|
||||
</span><span id="__span-8-4"><a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a><span class="k">async</span> <span class="k">with</span> <span class="n">advisory_lock</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="mi">42</span><span class="p">):</span>
|
||||
</span><span id="__span-8-5"><a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a> <span class="o">...</span>
|
||||
</span><span id="__span-8-6"><a id="__codelineno-8-6" name="__codelineno-8-6" href="#__codelineno-8-6"></a>
|
||||
</span><span id="__span-8-7"><a id="__codelineno-8-7" name="__codelineno-8-7" href="#__codelineno-8-7"></a><span class="c1"># Non-blocking: yields False immediately if already held</span>
|
||||
</span><span id="__span-8-8"><a id="__codelineno-8-8" name="__codelineno-8-8" href="#__codelineno-8-8"></a><span class="k">async</span> <span class="k">with</span> <span class="n">advisory_lock</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="mi">42</span><span class="p">,</span> <span class="n">nowait</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="k">as</span> <span class="n">acquired</span><span class="p">:</span>
|
||||
</span><span id="__span-8-9"><a id="__codelineno-8-9" name="__codelineno-8-9" href="#__codelineno-8-9"></a> <span class="k">if</span> <span class="ow">not</span> <span class="n">acquired</span><span class="p">:</span>
|
||||
</span><span id="__span-8-10"><a id="__codelineno-8-10" name="__codelineno-8-10" href="#__codelineno-8-10"></a> <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="mi">409</span><span class="p">,</span> <span class="s2">"Resource is locked"</span><span class="p">)</span>
|
||||
</span><span id="__span-8-11"><a id="__codelineno-8-11" name="__codelineno-8-11" href="#__codelineno-8-11"></a>
|
||||
</span><span id="__span-8-12"><a id="__codelineno-8-12" name="__codelineno-8-12" href="#__codelineno-8-12"></a><span class="c1"># Blocking with a timeout: raises LockTimeoutError if not acquired in time</span>
|
||||
</span><span id="__span-8-13"><a id="__codelineno-8-13" name="__codelineno-8-13" href="#__codelineno-8-13"></a><span class="k">async</span> <span class="k">with</span> <span class="n">advisory_lock</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="mi">42</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="s2">"5s"</span><span class="p">):</span>
|
||||
</span><span id="__span-8-14"><a id="__codelineno-8-14" name="__codelineno-8-14" href="#__codelineno-8-14"></a> <span class="o">...</span>
|
||||
</span><span id="__span-8-15"><a id="__codelineno-8-15" name="__codelineno-8-15" href="#__codelineno-8-15"></a>
|
||||
</span><span id="__span-8-16"><a id="__codelineno-8-16" name="__codelineno-8-16" href="#__codelineno-8-16"></a><span class="c1"># Shared lock: multiple readers allowed simultaneously, blocks exclusive writers</span>
|
||||
</span><span id="__span-8-17"><a id="__codelineno-8-17" name="__codelineno-8-17" href="#__codelineno-8-17"></a><span class="k">async</span> <span class="k">with</span> <span class="n">advisory_lock</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="mi">42</span><span class="p">,</span> <span class="n">shared</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
|
||||
</span><span id="__span-8-18"><a id="__codelineno-8-18" name="__codelineno-8-18" href="#__codelineno-8-18"></a> <span class="o">...</span>
|
||||
</span><span id="__span-8-19"><a id="__codelineno-8-19" name="__codelineno-8-19" href="#__codelineno-8-19"></a>
|
||||
</span><span id="__span-8-20"><a id="__codelineno-8-20" name="__codelineno-8-20" href="#__codelineno-8-20"></a><span class="c1"># Two-integer key for namespacing (e.g. lock_type + resource_id)</span>
|
||||
</span><span id="__span-8-21"><a id="__codelineno-8-21" name="__codelineno-8-21" href="#__codelineno-8-21"></a><span class="k">async</span> <span class="k">with</span> <span class="n">advisory_lock</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">user_id</span><span class="p">)):</span>
|
||||
</span><span id="__span-8-22"><a id="__codelineno-8-22" name="__codelineno-8-22" href="#__codelineno-8-22"></a> <span class="o">...</span>
|
||||
</span></code></pre></div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
@@ -2193,67 +2209,67 @@
|
||||
</div>
|
||||
<h2 id="row-change-polling">Row-change polling<a class="headerlink" href="#row-change-polling" title="Permanent link">¶</a></h2>
|
||||
<p><a href="../../reference/db/#fastapi_toolsets.db.wait_for_row_change"><code>wait_for_row_change</code></a> polls a row until a specific column changes value:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-8-1"><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">wait_for_row_change</span>
|
||||
</span><span id="__span-8-2"><a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a>
|
||||
</span><span id="__span-8-3"><a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a><span class="c1"># Wait up to 30s for order.status to change</span>
|
||||
</span><span id="__span-8-4"><a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a><span class="k">await</span> <span class="n">wait_for_row_change</span><span class="p">(</span>
|
||||
</span><span id="__span-8-5"><a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a> <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span>
|
||||
</span><span id="__span-8-6"><a id="__codelineno-8-6" name="__codelineno-8-6" href="#__codelineno-8-6"></a> <span class="n">model</span><span class="o">=</span><span class="n">Order</span><span class="p">,</span>
|
||||
</span><span id="__span-8-7"><a id="__codelineno-8-7" name="__codelineno-8-7" href="#__codelineno-8-7"></a> <span class="n">pk_value</span><span class="o">=</span><span class="n">order_id</span><span class="p">,</span>
|
||||
</span><span id="__span-8-8"><a id="__codelineno-8-8" name="__codelineno-8-8" href="#__codelineno-8-8"></a> <span class="n">columns</span><span class="o">=</span><span class="p">[</span><span class="s2">"status"</span><span class="p">],</span>
|
||||
</span><span id="__span-8-9"><a id="__codelineno-8-9" name="__codelineno-8-9" href="#__codelineno-8-9"></a> <span class="n">interval</span><span class="o">=</span><span class="mf">1.0</span><span class="p">,</span>
|
||||
</span><span id="__span-8-10"><a id="__codelineno-8-10" name="__codelineno-8-10" href="#__codelineno-8-10"></a> <span class="n">timeout</span><span class="o">=</span><span class="mf">30.0</span><span class="p">,</span>
|
||||
</span><span id="__span-8-11"><a id="__codelineno-8-11" name="__codelineno-8-11" href="#__codelineno-8-11"></a><span class="p">)</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-9-1"><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">wait_for_row_change</span>
|
||||
</span><span id="__span-9-2"><a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a>
|
||||
</span><span id="__span-9-3"><a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></a><span class="c1"># Wait up to 30s for order.status to change</span>
|
||||
</span><span id="__span-9-4"><a id="__codelineno-9-4" name="__codelineno-9-4" href="#__codelineno-9-4"></a><span class="k">await</span> <span class="n">wait_for_row_change</span><span class="p">(</span>
|
||||
</span><span id="__span-9-5"><a id="__codelineno-9-5" name="__codelineno-9-5" href="#__codelineno-9-5"></a> <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span>
|
||||
</span><span id="__span-9-6"><a id="__codelineno-9-6" name="__codelineno-9-6" href="#__codelineno-9-6"></a> <span class="n">model</span><span class="o">=</span><span class="n">Order</span><span class="p">,</span>
|
||||
</span><span id="__span-9-7"><a id="__codelineno-9-7" name="__codelineno-9-7" href="#__codelineno-9-7"></a> <span class="n">pk_value</span><span class="o">=</span><span class="n">order_id</span><span class="p">,</span>
|
||||
</span><span id="__span-9-8"><a id="__codelineno-9-8" name="__codelineno-9-8" href="#__codelineno-9-8"></a> <span class="n">columns</span><span class="o">=</span><span class="p">[</span><span class="s2">"status"</span><span class="p">],</span>
|
||||
</span><span id="__span-9-9"><a id="__codelineno-9-9" name="__codelineno-9-9" href="#__codelineno-9-9"></a> <span class="n">interval</span><span class="o">=</span><span class="mf">1.0</span><span class="p">,</span>
|
||||
</span><span id="__span-9-10"><a id="__codelineno-9-10" name="__codelineno-9-10" href="#__codelineno-9-10"></a> <span class="n">timeout</span><span class="o">=</span><span class="mf">30.0</span><span class="p">,</span>
|
||||
</span><span id="__span-9-11"><a id="__codelineno-9-11" name="__codelineno-9-11" href="#__codelineno-9-11"></a><span class="p">)</span>
|
||||
</span></code></pre></div>
|
||||
<h2 id="creating-a-database">Creating a database<a class="headerlink" href="#creating-a-database" title="Permanent link">¶</a></h2>
|
||||
<p><a href="../../reference/db/#fastapi_toolsets.db.testing.create_database"><code>create_database</code></a> (in <code>fastapi_toolsets.db.testing</code>) connects to <em>server_url</em> and issues a <code>CREATE DATABASE</code> statement:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-9-1"><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db.testing</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_database</span>
|
||||
</span><span id="__span-9-2"><a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a>
|
||||
</span><span id="__span-9-3"><a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></a><span class="n">SERVER_URL</span> <span class="o">=</span> <span class="s2">"postgresql+asyncpg://postgres:postgres@localhost/postgres"</span>
|
||||
</span><span id="__span-9-4"><a id="__codelineno-9-4" name="__codelineno-9-4" href="#__codelineno-9-4"></a>
|
||||
</span><span id="__span-9-5"><a id="__codelineno-9-5" name="__codelineno-9-5" href="#__codelineno-9-5"></a><span class="k">await</span> <span class="n">create_database</span><span class="p">(</span><span class="n">db_name</span><span class="o">=</span><span class="s2">"myapp_test"</span><span class="p">,</span> <span class="n">server_url</span><span class="o">=</span><span class="n">SERVER_URL</span><span class="p">)</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db.testing</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_database</span>
|
||||
</span><span id="__span-10-2"><a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a>
|
||||
</span><span id="__span-10-3"><a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a><span class="n">SERVER_URL</span> <span class="o">=</span> <span class="s2">"postgresql+asyncpg://postgres:postgres@localhost/postgres"</span>
|
||||
</span><span id="__span-10-4"><a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a>
|
||||
</span><span id="__span-10-5"><a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a><span class="k">await</span> <span class="n">create_database</span><span class="p">(</span><span class="n">db_name</span><span class="o">=</span><span class="s2">"myapp_test"</span><span class="p">,</span> <span class="n">server_url</span><span class="o">=</span><span class="n">SERVER_URL</span><span class="p">)</span>
|
||||
</span></code></pre></div>
|
||||
<p>For test isolation with automatic cleanup, use <a href="../../reference/pytest/#fastapi_toolsets.pytest.utils.create_worker_database"><code>create_worker_database</code></a> from the <code>pytest</code> module, which handles drop-before, create, and drop-after.</p>
|
||||
<h2 id="cleaning-up-tables">Cleaning up tables<a class="headerlink" href="#cleaning-up-tables" title="Permanent link">¶</a></h2>
|
||||
<p><a href="../../reference/db/#fastapi_toolsets.db.testing.cleanup_tables"><code>cleanup_tables</code></a> (in <code>fastapi_toolsets.db.testing</code>) truncates all tables:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db.testing</span><span class="w"> </span><span class="kn">import</span> <span class="n">cleanup_tables</span>
|
||||
</span><span id="__span-10-2"><a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a>
|
||||
</span><span id="__span-10-3"><a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">fixture</span><span class="p">(</span><span class="n">autouse</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
</span><span id="__span-10-4"><a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">clean</span><span class="p">(</span><span class="n">db_session</span><span class="p">):</span>
|
||||
</span><span id="__span-10-5"><a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a> <span class="k">yield</span>
|
||||
</span><span id="__span-10-6"><a id="__codelineno-10-6" name="__codelineno-10-6" href="#__codelineno-10-6"></a> <span class="k">await</span> <span class="n">cleanup_tables</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">db_session</span><span class="p">,</span> <span class="n">base</span><span class="o">=</span><span class="n">Base</span><span class="p">)</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-11-1"><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db.testing</span><span class="w"> </span><span class="kn">import</span> <span class="n">cleanup_tables</span>
|
||||
</span><span id="__span-11-2"><a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a>
|
||||
</span><span id="__span-11-3"><a id="__codelineno-11-3" name="__codelineno-11-3" href="#__codelineno-11-3"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">fixture</span><span class="p">(</span><span class="n">autouse</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
</span><span id="__span-11-4"><a id="__codelineno-11-4" name="__codelineno-11-4" href="#__codelineno-11-4"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">clean</span><span class="p">(</span><span class="n">db_session</span><span class="p">):</span>
|
||||
</span><span id="__span-11-5"><a id="__codelineno-11-5" name="__codelineno-11-5" href="#__codelineno-11-5"></a> <span class="k">yield</span>
|
||||
</span><span id="__span-11-6"><a id="__codelineno-11-6" name="__codelineno-11-6" href="#__codelineno-11-6"></a> <span class="k">await</span> <span class="n">cleanup_tables</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="n">db_session</span><span class="p">,</span> <span class="n">base</span><span class="o">=</span><span class="n">Base</span><span class="p">)</span>
|
||||
</span></code></pre></div>
|
||||
<h2 id="many-to-many-helpers">Many-to-Many helpers<a class="headerlink" href="#many-to-many-helpers" title="Permanent link">¶</a></h2>
|
||||
<p>The three <code>m2m_*</code> helpers modify a many-to-many association table with direct SQL, without loading the ORM collection.</p>
|
||||
<h3 id="m2m_add-insert-associations"><code>m2m_add</code>: insert associations<a class="headerlink" href="#m2m_add-insert-associations" title="Permanent link">¶</a></h3>
|
||||
<p><a href="../../reference/db/#fastapi_toolsets.db.m2m_add"><code>m2m_add</code></a> inserts one or more rows into a secondary table:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-11-1"><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">m2m_add</span>
|
||||
</span><span id="__span-11-2"><a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a>
|
||||
</span><span id="__span-11-3"><a id="__codelineno-11-3" name="__codelineno-11-3" href="#__codelineno-11-3"></a><span class="k">async</span> <span class="k">with</span> <span class="n">db</span><span class="o">.</span><span class="n">lock_tables</span><span class="p">([</span><span class="n">Tag</span><span class="p">])</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
||||
</span><span id="__span-11-4"><a id="__codelineno-11-4" name="__codelineno-11-4" href="#__codelineno-11-4"></a> <span class="n">tag</span> <span class="o">=</span> <span class="k">await</span> <span class="n">TagCrud</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">TagCreate</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">"python"</span><span class="p">))</span>
|
||||
</span><span id="__span-11-5"><a id="__codelineno-11-5" name="__codelineno-11-5" href="#__codelineno-11-5"></a> <span class="k">await</span> <span class="n">m2m_add</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">post</span><span class="p">,</span> <span class="n">Post</span><span class="o">.</span><span class="n">tags</span><span class="p">,</span> <span class="n">tag</span><span class="p">)</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-12-1"><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">m2m_add</span>
|
||||
</span><span id="__span-12-2"><a id="__codelineno-12-2" name="__codelineno-12-2" href="#__codelineno-12-2"></a>
|
||||
</span><span id="__span-12-3"><a id="__codelineno-12-3" name="__codelineno-12-3" href="#__codelineno-12-3"></a><span class="k">async</span> <span class="k">with</span> <span class="n">db</span><span class="o">.</span><span class="n">lock_tables</span><span class="p">([</span><span class="n">Tag</span><span class="p">])</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
||||
</span><span id="__span-12-4"><a id="__codelineno-12-4" name="__codelineno-12-4" href="#__codelineno-12-4"></a> <span class="n">tag</span> <span class="o">=</span> <span class="k">await</span> <span class="n">TagCrud</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">TagCreate</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">"python"</span><span class="p">))</span>
|
||||
</span><span id="__span-12-5"><a id="__codelineno-12-5" name="__codelineno-12-5" href="#__codelineno-12-5"></a> <span class="k">await</span> <span class="n">m2m_add</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">post</span><span class="p">,</span> <span class="n">Post</span><span class="o">.</span><span class="n">tags</span><span class="p">,</span> <span class="n">tag</span><span class="p">)</span>
|
||||
</span></code></pre></div>
|
||||
<p>Pass <code>ignore_conflicts=True</code> to skip associations that already exist:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-12-1"><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="k">await</span> <span class="n">m2m_add</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">post</span><span class="p">,</span> <span class="n">Post</span><span class="o">.</span><span class="n">tags</span><span class="p">,</span> <span class="n">tag</span><span class="p">,</span> <span class="n">ignore_conflicts</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-13-1"><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a><span class="k">await</span> <span class="n">m2m_add</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">post</span><span class="p">,</span> <span class="n">Post</span><span class="o">.</span><span class="n">tags</span><span class="p">,</span> <span class="n">tag</span><span class="p">,</span> <span class="n">ignore_conflicts</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
</span></code></pre></div>
|
||||
<h3 id="m2m_remove-delete-associations"><code>m2m_remove</code>: delete associations<a class="headerlink" href="#m2m_remove-delete-associations" title="Permanent link">¶</a></h3>
|
||||
<p><a href="../../reference/db/#fastapi_toolsets.db.m2m_remove"><code>m2m_remove</code></a> deletes specific association rows. Removing a non-existent association is a no-op:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-13-1"><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">m2m_remove</span><span class="p">,</span> <span class="n">transaction</span>
|
||||
</span><span id="__span-13-2"><a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a>
|
||||
</span><span id="__span-13-3"><a id="__codelineno-13-3" name="__codelineno-13-3" href="#__codelineno-13-3"></a><span class="k">async</span> <span class="k">with</span> <span class="n">transaction</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
|
||||
</span><span id="__span-13-4"><a id="__codelineno-13-4" name="__codelineno-13-4" href="#__codelineno-13-4"></a> <span class="k">await</span> <span class="n">m2m_remove</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">post</span><span class="p">,</span> <span class="n">Post</span><span class="o">.</span><span class="n">tags</span><span class="p">,</span> <span class="n">tag1</span><span class="p">,</span> <span class="n">tag2</span><span class="p">)</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-14-1"><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">m2m_remove</span><span class="p">,</span> <span class="n">transaction</span>
|
||||
</span><span id="__span-14-2"><a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a>
|
||||
</span><span id="__span-14-3"><a id="__codelineno-14-3" name="__codelineno-14-3" href="#__codelineno-14-3"></a><span class="k">async</span> <span class="k">with</span> <span class="n">transaction</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
|
||||
</span><span id="__span-14-4"><a id="__codelineno-14-4" name="__codelineno-14-4" href="#__codelineno-14-4"></a> <span class="k">await</span> <span class="n">m2m_remove</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">post</span><span class="p">,</span> <span class="n">Post</span><span class="o">.</span><span class="n">tags</span><span class="p">,</span> <span class="n">tag1</span><span class="p">,</span> <span class="n">tag2</span><span class="p">)</span>
|
||||
</span></code></pre></div>
|
||||
<h3 id="m2m_set-replace-the-full-set"><code>m2m_set</code>: replace the full set<a class="headerlink" href="#m2m_set-replace-the-full-set" title="Permanent link">¶</a></h3>
|
||||
<p><a href="../../reference/db/#fastapi_toolsets.db.m2m_set"><code>m2m_set</code></a> replaces all associations: it deletes every existing row for the owner instance then inserts the new set. Passing no related instances clears the association:</p>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-14-1"><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">m2m_set</span><span class="p">,</span> <span class="n">transaction</span>
|
||||
</span><span id="__span-14-2"><a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a>
|
||||
</span><span id="__span-14-3"><a id="__codelineno-14-3" name="__codelineno-14-3" href="#__codelineno-14-3"></a><span class="c1"># Replace all tags</span>
|
||||
</span><span id="__span-14-4"><a id="__codelineno-14-4" name="__codelineno-14-4" href="#__codelineno-14-4"></a><span class="k">async</span> <span class="k">with</span> <span class="n">transaction</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
|
||||
</span><span id="__span-14-5"><a id="__codelineno-14-5" name="__codelineno-14-5" href="#__codelineno-14-5"></a> <span class="k">await</span> <span class="n">m2m_set</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">post</span><span class="p">,</span> <span class="n">Post</span><span class="o">.</span><span class="n">tags</span><span class="p">,</span> <span class="n">tag_a</span><span class="p">,</span> <span class="n">tag_b</span><span class="p">)</span>
|
||||
</span><span id="__span-14-6"><a id="__codelineno-14-6" name="__codelineno-14-6" href="#__codelineno-14-6"></a>
|
||||
</span><span id="__span-14-7"><a id="__codelineno-14-7" name="__codelineno-14-7" href="#__codelineno-14-7"></a><span class="c1"># Clear all tags</span>
|
||||
</span><span id="__span-14-8"><a id="__codelineno-14-8" name="__codelineno-14-8" href="#__codelineno-14-8"></a><span class="k">async</span> <span class="k">with</span> <span class="n">transaction</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
|
||||
</span><span id="__span-14-9"><a id="__codelineno-14-9" name="__codelineno-14-9" href="#__codelineno-14-9"></a> <span class="k">await</span> <span class="n">m2m_set</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">post</span><span class="p">,</span> <span class="n">Post</span><span class="o">.</span><span class="n">tags</span><span class="p">)</span>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-15-1"><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.db</span><span class="w"> </span><span class="kn">import</span> <span class="n">m2m_set</span><span class="p">,</span> <span class="n">transaction</span>
|
||||
</span><span id="__span-15-2"><a id="__codelineno-15-2" name="__codelineno-15-2" href="#__codelineno-15-2"></a>
|
||||
</span><span id="__span-15-3"><a id="__codelineno-15-3" name="__codelineno-15-3" href="#__codelineno-15-3"></a><span class="c1"># Replace all tags</span>
|
||||
</span><span id="__span-15-4"><a id="__codelineno-15-4" name="__codelineno-15-4" href="#__codelineno-15-4"></a><span class="k">async</span> <span class="k">with</span> <span class="n">transaction</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
|
||||
</span><span id="__span-15-5"><a id="__codelineno-15-5" name="__codelineno-15-5" href="#__codelineno-15-5"></a> <span class="k">await</span> <span class="n">m2m_set</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">post</span><span class="p">,</span> <span class="n">Post</span><span class="o">.</span><span class="n">tags</span><span class="p">,</span> <span class="n">tag_a</span><span class="p">,</span> <span class="n">tag_b</span><span class="p">)</span>
|
||||
</span><span id="__span-15-6"><a id="__codelineno-15-6" name="__codelineno-15-6" href="#__codelineno-15-6"></a>
|
||||
</span><span id="__span-15-7"><a id="__codelineno-15-7" name="__codelineno-15-7" href="#__codelineno-15-7"></a><span class="c1"># Clear all tags</span>
|
||||
</span><span id="__span-15-8"><a id="__codelineno-15-8" name="__codelineno-15-8" href="#__codelineno-15-8"></a><span class="k">async</span> <span class="k">with</span> <span class="n">transaction</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
|
||||
</span><span id="__span-15-9"><a id="__codelineno-15-9" name="__codelineno-15-9" href="#__codelineno-15-9"></a> <span class="k">await</span> <span class="n">m2m_set</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="n">post</span><span class="p">,</span> <span class="n">Post</span><span class="o">.</span><span class="n">tags</span><span class="p">)</span>
|
||||
</span></code></pre></div>
|
||||
<p>All three helpers raise <code>TypeError</code> if the relationship attribute is not a Many-to-Many (i.e. has no secondary table).</p>
|
||||
<hr />
|
||||
|
||||
Reference in New Issue
Block a user