Skip to content

Commit a6bc7a3

Browse files
ahus1ahus1
committed
Deploying to main from @ 57a20b88d624829c073b8c302e3d04cb451cc384 🚀
1 parent 9554ab4 commit a6bc7a3

File tree

5 files changed

+130
-133
lines changed

5 files changed

+130
-133
lines changed

‎nightly/observability/health.html‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -146,11 +146,15 @@ <h2 id="_keycloak_health_check_endpoints"><a class="anchor" href="#_keycloak_hea
146146
</div>
147147
</div>
148148
<div class="listingblock">
149-
<div class="title">Successful response for endpoints with information on the database connection:</div>
149+
<div class="title">Successful response for endpoints with additional per-check information:</div>
150150
<div class="content">
151151
<pre class="highlight"><code class="language-json" data-lang="json">{
152152
"status": "UP",
153153
"checks": [
154+
{
155+
"name": "Keycloak Initialized",
156+
"status": "UP"
157+
},
154158
{
155159
"name": "Graceful Shutdown",
156160
"status": "UP"
@@ -308,6 +312,11 @@ <h2 id="_available_checks"><a class="anchor" href="#_available_checks"></a>Avail
308312
<td class="tableblock halign-left valign-top"><p class="tableblock">Will start to return "DOWN" once the pre-shutdown phase started.</p></td>
309313
<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
310314
</tr>
315+
<tr>
316+
<td class="tableblock halign-left valign-top"><p class="tableblock">Keycloak Initialized</p></td>
317+
<td class="tableblock halign-left valign-top"><p class="tableblock">Returns the status of the server initialization.</p></td>
318+
<td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td>
319+
</tr>
311320
</tbody>
312321
</table>
313322
<div class="paragraph">

‎nightly/server/all-config.html‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -913,6 +913,27 @@ <h2 id="category-database"><a class="anchor" href="#category-database"></a>Datab
913913
</tr>
914914
<tr>
915915
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
916+
<p><span class="options-key"><code>db-connect-timeout</code></span></p>
917+
</div>
918+
<div class="paragraph">
919+
<p><span class="options-description">Sets the JDBC driver connection timeout and login timeout.</span></p>
920+
</div>
921+
<div id="option-extended-database-db-connect-timeout" class="openblock options-extended">
922+
<div class="content">
923+
<div class="paragraph">
924+
<p><span class="options-description-extended">May be an ISO 8601 duration value, an integer number of seconds, or an integer followed by one of [ms, h, m, s, d].</span></p>
925+
</div>
926+
<div class="paragraph">
927+
<p><strong>CLI:</strong> <code>--db-connect-timeout</code><br>
928+
<strong>Env:</strong> <code>KC_DB_CONNECT_TIMEOUT</code></p>
929+
</div>
930+
</div>
931+
</div></div></td>
932+
<td class="tableblock halign-left valign-top"><p class="tableblock"><em>String</em></p></td>
933+
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>10s</code></p></td>
934+
</tr>
935+
<tr>
936+
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
916937
<p><span class="options-key"><code>db-debug-jpql</code></span></p>
917938
</div>
918939
<div class="paragraph">
@@ -5537,6 +5558,48 @@ <h2 id="category-openapi"><a class="anchor" href="#category-openapi"></a>OpenAPI
55375558
</div>
55385559
</div>
55395560
<div class="sect1">
5561+
<h2 id="category-server"><a class="anchor" href="#category-server"></a>Server configuration</h2>
5562+
<div class="sectionbody">
5563+
<table class="tableblock frame-all grid-all stretch options">
5564+
<colgroup>
5565+
<col style="width: 75%;">
5566+
<col style="width: 12.5%;">
5567+
<col style="width: 12.5%;">
5568+
</colgroup>
5569+
<thead>
5570+
<tr>
5571+
<th class="tableblock halign-left valign-top"></th>
5572+
<th class="tableblock halign-left valign-top"><em>Type</em> or Values</th>
5573+
<th class="tableblock halign-left valign-top">Default</th>
5574+
</tr>
5575+
</thead>
5576+
<tbody>
5577+
<tr>
5578+
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
5579+
<p><span class="options-key"><code>server-async-bootstrap</code></span></p>
5580+
</div>
5581+
<div class="paragraph">
5582+
<p><span class="options-description">If true, endpoints are opened while the bootstrap runs in the background.</span></p>
5583+
</div>
5584+
<div id="option-extended-server-server-async-bootstrap" class="openblock options-extended">
5585+
<div class="content">
5586+
<div class="paragraph">
5587+
<p><span class="options-description-extended">If false, endpoints are opened after bootstrap completes, ensuring the server is ready to handle requests.</span></p>
5588+
</div>
5589+
<div class="paragraph">
5590+
<p><strong>CLI:</strong> <code>--server-async-bootstrap</code><br>
5591+
<strong>Env:</strong> <code>KC_SERVER_ASYNC_BOOTSTRAP</code></p>
5592+
</div>
5593+
</div>
5594+
</div></div></td>
5595+
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code>, <code>false</code></p></td>
5596+
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code></p></td>
5597+
</tr>
5598+
</tbody>
5599+
</table>
5600+
</div>
5601+
</div>
5602+
<div class="sect1">
55405603
<h2 id="category-bootstrap_admin"><a class="anchor" href="#category-bootstrap_admin"></a>Bootstrap Admin</h2>
55415604
<div class="sectionbody">
55425605
<table class="tableblock frame-all grid-all stretch options">

‎nightly/server/configuration-production.html‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,30 @@ <h2 id="_limit_the_number_of_queued_requests"><a class="anchor" href="#_limit_th
191191
</div>
192192
</div>
193193
<div class="sect1">
194+
<h2 id="_server_bootstrap_behavior"><a class="anchor" href="#_server_bootstrap_behavior"></a>Server bootstrap behavior</h2>
195+
<div class="sectionbody">
196+
<div class="paragraph">
197+
<p>Server initialization, such as database migrations, may take a significant amount of time to complete.
198+
By default, Keycloak opens its HTTP(S) and Management endpoints while initialization is still in progress in the background.
199+
This allows the startup and liveness probes to report UP early, preventing orchestrators like Kubernetes from killing the container during a long-running migration, while the readiness probe reports DOWN until initialization completes.</p>
200+
</div>
201+
<div class="paragraph">
202+
<p>If you run Keycloak behind a proxy or load balancer, configure an HTTP health check with the path <code>/health/ready</code> to ensure traffic is routed only to instances that have completed initialization.</p>
203+
</div>
204+
<div class="paragraph">
205+
<p>If an HTTP health check is not possible, or you prefer the server to accept connections only after initialization completes, start Keycloak with the following option:</p>
206+
</div>
207+
<div class="listingblock">
208+
<div class="content">
209+
<pre class="highlight"><code class="language-bash" data-lang="bash">bin/kc.[sh|bat] start --server-async-bootstrap=false</code></pre>
210+
</div>
211+
</div>
212+
<div class="paragraph">
213+
<p>With this setting, Keycloak opens its endpoints only after the bootstrap is complete and the server is ready to handle requests.</p>
214+
</div>
215+
</div>
216+
</div>
217+
<div class="sect1">
194218
<h2 id="_production_grade_database"><a class="anchor" href="#_production_grade_database"></a>Production grade database</h2>
195219
<div class="sectionbody">
196220
<div class="paragraph">

‎nightly/server/db.html‎

Lines changed: 31 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -556,140 +556,20 @@ <h3 id="_configuring_unicode_support_for_a_microsoft_sql_server_database"><a cla
556556
</div>
557557
</div>
558558
<div class="sect1">
559-
<h2 id="_automatic_database_connection_timeout"><a class="anchor" href="#_automatic_database_connection_timeout"></a>Automatic database connection timeout</h2>
559+
<h2 id="_database_connection_and_login_timeout"><a class="anchor" href="#_database_connection_and_login_timeout"></a>Database connection and login timeout</h2>
560560
<div class="sectionbody">
561561
<div class="paragraph">
562562
<p>When Keycloak connects to the database, network problems can occur, especially during failovers or switchovers.
563-
To improve resilience and ensure faster recovery, Keycloak automatically sets a default connection timeout of 10 seconds for selected database vendors when using the standard JDBC driver.</p>
564-
</div>
565-
<div class="paragraph">
566-
<p>The following table lists the affected vendors, the JDBC driver property used, and the default value applied by Keycloak:</p>
567-
</div>
568-
<table class="tableblock frame-all grid-all fit-content">
569-
<colgroup>
570-
<col>
571-
<col>
572-
<col>
573-
<col>
574-
</colgroup>
575-
<thead>
576-
<tr>
577-
<th class="tableblock halign-left valign-top">Database</th>
578-
<th class="tableblock halign-left valign-top">JDBC driver property</th>
579-
<th class="tableblock halign-left valign-top">Default value</th>
580-
<th class="tableblock halign-left valign-top">Unit</th>
581-
</tr>
582-
</thead>
583-
<tbody>
584-
<tr>
585-
<td class="tableblock halign-left valign-top"><p class="tableblock">MySQL</p></td>
586-
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>connectTimeout</code></p></td>
587-
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>10000</code></p></td>
588-
<td class="tableblock halign-left valign-top"><p class="tableblock">milliseconds</p></td>
589-
</tr>
590-
<tr>
591-
<td class="tableblock halign-left valign-top"><p class="tableblock">MariaDB</p></td>
592-
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>connectTimeout</code></p></td>
593-
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>10000</code></p></td>
594-
<td class="tableblock halign-left valign-top"><p class="tableblock">milliseconds</p></td>
595-
</tr>
596-
<tr>
597-
<td class="tableblock halign-left valign-top"><p class="tableblock">PostgreSQL</p></td>
598-
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>connectTimeout</code></p></td>
599-
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>10</code></p></td>
600-
<td class="tableblock halign-left valign-top"><p class="tableblock">seconds</p></td>
601-
</tr>
602-
<tr>
603-
<td class="tableblock halign-left valign-top"><p class="tableblock">Oracle Database</p></td>
604-
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>oracle.net.CONNECT_TIMEOUT</code></p></td>
605-
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>10000</code></p></td>
606-
<td class="tableblock halign-left valign-top"><p class="tableblock">milliseconds</p></td>
607-
</tr>
608-
<tr>
609-
<td class="tableblock halign-left valign-top"><p class="tableblock">Microsoft SQL Server</p></td>
610-
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>loginTimeout</code></p></td>
611-
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>10</code></p></td>
612-
<td class="tableblock halign-left valign-top"><p class="tableblock">seconds</p></td>
613-
</tr>
614-
</tbody>
615-
</table>
616-
<div class="paragraph">
617-
<p>Keycloak applies these defaults automatically, but only when all of the following conditions are met:</p>
618-
</div>
619-
<div class="ulist">
620-
<ul>
621-
<li>
622-
<p>The database vendor is configured via <code>--db</code>.</p>
623-
</li>
624-
<li>
625-
<p>Keycloak is using the standard JDBC driver for that vendor.</p>
626-
</li>
627-
<li>
628-
<p>The timeout property has not already been set explicitly by the user in <code>db-url</code> or <code>db-url-properties</code>.</p>
629-
</li>
630-
</ul>
631-
</div>
632-
<div class="sect2">
633-
<h3 id="_overriding_the_default_connection_timeout"><a class="anchor" href="#_overriding_the_default_connection_timeout"></a>Overriding the default connection timeout</h3>
634-
<div class="paragraph">
635-
<p>To use a different connection timeout, set the relevant JDBC driver property explicitly via <code>db-url</code> or <code>db-url-properties</code>.</p>
636-
</div>
637-
<div class="paragraph">
638-
<p>For MySQL:</p>
639-
</div>
640-
<div class="listingblock">
641-
<div class="content">
642-
<pre class="highlight"><code class="language-bash" data-lang="bash">bin/kc.[sh|bat] start --db mysql --db-url-properties='?connectTimeout=30000'</code></pre>
643-
</div>
644-
</div>
645-
<div class="paragraph">
646-
<p>For MariaDB:</p>
647-
</div>
648-
<div class="listingblock">
649-
<div class="content">
650-
<pre class="highlight"><code class="language-bash" data-lang="bash">bin/kc.[sh|bat] start --db mariadb --db-url-properties='?connectTimeout=30000'</code></pre>
651-
</div>
652-
</div>
653-
<div class="paragraph">
654-
<p>For Microsoft SQL Server:</p>
655-
</div>
656-
<div class="listingblock">
657-
<div class="content">
658-
<pre class="highlight"><code class="language-bash" data-lang="bash">bin/kc.[sh|bat] start --db mssql --db-url-properties=';loginTimeout=20'</code></pre>
659-
</div>
660-
</div>
661-
<div class="paragraph">
662-
<p>For PostgreSQL:</p>
663-
</div>
664-
<div class="listingblock">
665-
<div class="content">
666-
<pre class="highlight"><code class="language-bash" data-lang="bash">bin/kc.[sh|bat] start --db postgres --db-url-properties='?connectTimeout=30'</code></pre>
667-
</div>
668-
</div>
669-
<div class="admonitionblock note">
670-
<table>
671-
<tr>
672-
<td class="icon">
673-
<i class="fa icon-note" title="Note"></i>
674-
</td>
675-
<td class="content">
676-
<div class="paragraph">
677-
<p>When using <code>db-url-properties</code>, prepend the correct delimiter for your vendor&#8217;s JDBC URL format:</p>
678-
</div>
679-
<div class="ulist">
680-
<ul>
681-
<li>
682-
<p>PostgreSQL, MySQL, and MariaDB: use <code>?</code> as the first property delimiter, or <code>&amp;</code> for subsequent properties.</p>
683-
</li>
684-
<li>
685-
<p>Microsoft SQL Server: use <code>;</code> as the property delimiter.</p>
686-
</li>
687-
</ul>
688-
</div>
689-
</td>
690-
</tr>
691-
</table>
563+
To improve failover behavior and startup resilience during network issues, Keycloak sets a default connection timeout of 10s for all supported database vendors when using the standard JDBC driver.</p>
692564
</div>
565+
<div class="dlist">
566+
<dl>
567+
<dt class="hdlist1"><code>db-connect-timeout</code></dt>
568+
<dd>
569+
<p>Sets the JDBC driver connection timeout and login timeout.
570+
Default: <code>10s</code>.</p>
571+
</dd>
572+
</dl>
693573
</div>
694574
</div>
695575
</div>
@@ -1339,6 +1219,27 @@ <h2 id="_relevant_options"><a class="anchor" href="#_relevant_options"></a>Relev
13391219
</tr>
13401220
<tr>
13411221
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
1222+
<p><span class="options-key"><code>db-connect-timeout</code></span></p>
1223+
</div>
1224+
<div class="paragraph">
1225+
<p><span class="options-description">Sets the JDBC driver connection timeout and login timeout.</span></p>
1226+
</div>
1227+
<div class="openblock options-extended">
1228+
<div class="content">
1229+
<div class="paragraph">
1230+
<p><span class="options-description-extended">May be an ISO 8601 duration value, an integer number of seconds, or an integer followed by one of [ms, h, m, s, d].</span></p>
1231+
</div>
1232+
<div class="paragraph">
1233+
<p><strong>CLI:</strong> <code>--db-connect-timeout</code><br>
1234+
<strong>Env:</strong> <code>KC_DB_CONNECT_TIMEOUT</code></p>
1235+
</div>
1236+
</div>
1237+
</div></div></td>
1238+
<td class="tableblock halign-left valign-top"><p class="tableblock"><em>String</em></p></td>
1239+
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>10s</code></p></td>
1240+
</tr>
1241+
<tr>
1242+
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
13421243
<p><span class="options-key"><code>db-debug-jpql</code></span></p>
13431244
</div>
13441245
<div class="paragraph">

‎translations.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -600,7 +600,7 @@ <h1>Translations</h1>
600600
</a>
601601
</td>
602602
<td style="text-align: right">
603-
<a rel="nofollow" href="https://hosted.weblate.org/translate/keycloak/-/pt_BR/?q=state%3A%3Dtranslated&sort_by=-priority%2Cposition&checksum=">6</a>
603+
&check;
604604
</td>
605605
</tr>
606606
<tr>
@@ -810,7 +810,7 @@ <h1>Translations</h1>
810810
</tbody>
811811
</table>
812812

813-
<p data-nosnippet>(Statistics updated daily. Last update: 2026-03-19T20:26:50Z)</p>
813+
<p data-nosnippet>(Statistics updated daily. Last update: 2026-03-20T05:26:32Z)</p>
814814

815815
</div>
816816

0 commit comments

Comments
 (0)