diff --git a/nixos/modules/services/web-apps/keycloak.nix b/nixos/modules/services/web-apps/keycloak.nix
index a93e93279331..5b578cd8c4a9 100644
--- a/nixos/modules/services/web-apps/keycloak.nix
+++ b/nixos/modules/services/web-apps/keycloak.nix
@@ -171,6 +171,12 @@ in
         Username to use when connecting to an external or manually
         provisioned database; has no effect when a local database is
         automatically provisioned.
+
+        To use this with a local database, set <xref
+        linkend="opt-services.keycloak.databaseCreateLocally" /> to
+        <literal>false</literal> and create the database and user
+        manually. The database should be called
+        <literal>keycloak</literal>.
       '';
     };