FastAPI health check endpoint with dependency checks

<p>I need a /health endpoint for Docker healthchecks and load balancer probes. The endpoint should verify the database connection and Redis connection are alive, return structured health status, and respond quickly (under 1 second).</p>

<p>Implement a health check that tests real connections:</p> <div class="highlight"><pre><span></span><code><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">APIRouter</span><span class="p">,</span> <span class="n">Depends</span> <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">BaseModel</span> <span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span> <span class="n">router</span> <span class="o">=</span> <span class="n">APIRouter</span><span class="p">()</span> <span class="k">class</span><span class="w"> </span><span class="nc">HealthStatus</span><span class="p">(</span><span class="n">BaseModel</span><span class="p">):</span> <span class="n">status</span><span class="p">:</span> <span class="nb">str</span> <span class="c1"># 'healthy' | 'degraded' | 'unhealthy'</span> <span class="n">database</span><span class="p">:</span> <span class="nb">str</span> <span class="n">redis</span><span class="p">:</span> <span class="nb">str</span> <span class="n">version</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s1">'1.0.0'</span> <span class="nd">@router</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'/health'</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">HealthStatus</span><span class="p">,</span> <span class="n">include_in_schema</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">health_check</span><span class="p">(</span><span class="n">db</span><span class="p">:</span> <span class="n">DbSession</span><span class="p">,</span> <span class="n">redis</span><span class="o">=</span><span class="n">Depends</span><span class="p">(</span><span class="n">get_redis</span><span class="p">)):</span> <span class="n">db_status</span> <span class="o">=</span> <span class="s1">'unknown'</span> <span class="n">redis_status</span> <span class="o">=</span> <span class="s1">'unknown'</span> <span class="c1"># Check DB with timeout</span> <span class="k">try</span><span class="p">:</span> <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">wait_for</span><span class="p">(</span> <span class="n">db</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">text</span><span class="p">(</span><span class="s1">'SELECT 1'</span><span class="p">)),</span> <span class="n">timeout</span><span class="o">=</span><span class="mf">1.0</span> <span class="p">)</span> <span class="n">db_status</span> <span class="o">=</span> <span class="s1">'ok'</span> <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span> <span class="n">db_status</span> <span class="o">=</span> <span class="sa">f</span><span class="s1">'error: </span><span class="si">{</span><span class="nb">type</span><span class="p">(</span><span class="n">e</span><span class="p">)</span><span class="o">.</span><span class="vm">__name__</span><span class="si">}</span><span class="s1">'</span> <span class="c1"># Check Redis</span> <span class="k">try</span><span class="p">:</span> <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">wait_for</span><span class="p">(</span><span class="n">redis</span><span class="o">.</span><span class="n">ping</span><span class="p">(),</span> <span class="n">timeout</span><span class="o">=</span><span class="mf">1.0</span><span class="p">)</span> <span class="n">redis_status</span> <span class="o">=</span> <span class="s1">'ok'</span> <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span> <span class="n">redis_status</span> <span class="o">=</span> <span class="sa">f</span><span class="s1">'error: </span><span class="si">{</span><span class="nb">type</span><span class="p">(</span><span class="n">e</span><span class="p">)</span><span class="o">.</span><span class="vm">__name__</span><span class="si">}</span><span class="s1">'</span> <span class="n">all_ok</span> <span class="o">=</span> <span class="n">db_status</span> <span class="o">==</span> <span class="s1">'ok'</span> <span class="ow">and</span> <span class="n">redis_status</span> <span class="o">==</span> <span class="s1">'ok'</span> <span class="k">return</span> <span class="n">HealthStatus</span><span class="p">(</span> <span class="n">status</span><span class="o">=</span><span class="s1">'healthy'</span> <span class="k">if</span> <span class="n">all_ok</span> <span class="k">else</span> <span class="s1">'degraded'</span><span class="p">,</span> <span class="n">database</span><span class="o">=</span><span class="n">db_status</span><span class="p">,</span> <span class="n">redis</span><span class="o">=</span><span class="n">redis_status</span><span class="p">,</span> <span class="p">)</span> </code></pre></div> <p>Docker Compose healthcheck:</p> <div class="highlight"><pre><span></span><code><span class="nt">healthcheck</span><span class="p">:</span> <span class="w"> </span><span class="nt">test</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"CMD-SHELL"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"curl</span><span class="nv"> </span><span class="s">-f</span><span class="nv"> </span><span class="s">http://localhost:8000/health</span><span class="nv"> </span><span class="s">||</span><span class="nv"> </span><span class="s">exit</span><span class="nv"> </span><span class="s">1"</span><span class="p p-Indicator">]</span> <span class="w"> </span><span class="nt">interval</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10s</span> <span class="w"> </span><span class="nt">timeout</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5s</span> <span class="w"> </span><span class="nt">retries</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3</span> </code></pre></div> <p>Key points: - Always timeout dependency checks — a hung DB check hangs your health endpoint - Return <code>degraded</code> not <code>unhealthy</code> when optional services (Redis) are down - Use <code>SELECT 1</code> for lightweight DB check — no actual data access - Exclude from OpenAPI schema with <code>include_in_schema=False</code></p>