Running Keycloak using PostgreSQL database

Abhishek koserwal
May 28 · 2 min read

In this post, we will be going over how to configure the PostgreSQL database with Keycloak. Keycloak standard distribution comes with H2 embedded database. The process discussed in this post can be used for other supported databases like Mysql.


Github repository: keycloak-integration

git clone


Postgres Module Configuration

For EAP/Wildfly distribution. it follows the Java convention for the package structure. Like a reverse domain name.

Let’s name the module as com.postgres and the folder structure would look like this:


The main folder will contain

  • module.xml
  • Postgresql driver


<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.3" name="com.postgres">
<resource-root path="postgresql-42.2.20.jar" />
<module name="javax.api"/>
<module name="javax.transaction.api"/>

We need to create this module in the Keycloak installation director


To make it easier to configure, I have already provided a sample module structure in the repository. Follow the instructions to configure.

Download the PostgreSQL driver and copy the driver to the modules directory in the repository.

After cloning the repository

cd keycloak-integrations/keycloak-postgresql/

Run to download the driver.

cd keycloak-config/postgres/main && { wget ; cd -; }

Set your Keycloak installation directory path. In my case it is the root directory

export KEYCLOAK_DIR=~/keycloak-X.X.X

Copy the Postgres module to the Keycloak modules directory path

rsync -r keycloak-config/* $KEYCLOAK_DIR/modules/system/layers/keycloak/com

Run the PostgreSQL Database

Run this shell script to spin up an ephemeral instance of PostgreSQL DB


Check if the PostgreSQL database is up & running

$ docker ps -a
//In my case it is running on

Keycloak: update the data source configuration

cd $KEYCLOAK_DIR/standalone/configuration

Open the standalone.xml in an editor. Search for the datasource & update the config with:

Refer link: standalone.xml#L439

  • make sure the connection url is correct, In my case it is jdbc:postgresql://localhost:32769/keycloak
  • Use the same <user-name></user-name> asPOSTGRES_USER
  • Use the same <password></password> as POSTGRES_PASSWORD

Below, add the driver configuration. You can see reference to the module=”com.postgres”

Refer link: standalone.xml#L457

Replace the ExampleDS with KeycloakDS

Please refer: standalone.xml#L108

That’s all you needed to configure the PostgreSQL database with keycloak.

Start the Keycloak Server



A similar process can be followed for configuring other supported database with Keycloak.

Steps we followed:

  • Create the module structure
  • Download the driver
  • Configure the data source configuration

If you like this post, give it a Cheer!!!

Follow the Collection: Keycloak for learning more…

Happy Secure Coding ❤


Open Source Identity Solution for Applications, Services…