What Is the Keycloak Database?
Behind every realm, every user, and every issued token sits a relational database quietly doing the actual remembering. This guide explains what the Keycloak database is, what it stores, and why getting it right matters so much.
Imagine a library where a friendly librarian (Keycloak) helps every visitor find exactly the book they’re looking for, checks their library card, and keeps track of who currently has which books checked out. The librarian doesn’t memorize all of that information personally — behind the front desk sits a filing system recording every book, every member, and every loan, which the librarian constantly reads from and writes to. The Keycloak database is exactly that filing system: the persistent storage layer where every realm, user, role, and configuration Keycloak manages is actually kept, safely, between restarts and across a growing deployment.
1What Is the Keycloak Database?
The foundation everything else in this guide builds on.
Keycloak itself is an application — it processes login requests, issues tokens, and enforces security rules, but it doesn’t permanently remember anything on its own. Every realm, every user account, every client registration, and every configuration setting is stored in a separate relational database that Keycloak connects to and constantly reads from and writes to as it runs.
Think of Keycloak as the reception desk of a large office building, and the database as the building’s own record room down the hall. The receptionist doesn’t personally memorize every tenant, badge, and access rule — every time someone asks a question or needs to be checked in, the receptionist walks to the record room, looks something up, or files something new away. Without that record room, the receptionist would forget everything the moment their shift ended.
This separation matters: Keycloak, as the running application, can be restarted, upgraded, or even run as several identical instances at once, while the actual data — the realms, users, and settings — stays safely intact in the database the whole time.
Persistent Storage
Data survives restarts, upgrades, and even complete reinstallation of the Keycloak application itself.
Separate From the Application
The database runs as its own independent system that Keycloak connects to over a network or local connection.
Relational Structure
Data is organized into structured, related tables — realms, users, roles, sessions, and more.
Constantly Read and Written
Nearly every meaningful action in Keycloak — a login, a new user, a changed setting — touches the database in some way.
Without a properly configured, durable database behind it, Keycloak has nowhere to safely keep anything — this makes the database one of the most operationally important pieces of any real Keycloak deployment.
2Keycloak’s Database vs. an LDAP Directory vs. Caching
Three different storage-related concepts that are easy to blur together.
Keycloak deals with data in a few distinct ways, and it’s worth being precise about which is which, especially if an earlier guide on LDAP integration is fresh in mind.
The Keycloak database is like the building’s own permanent record room, described above — it’s where Keycloak’s own core configuration and locally managed users truly live. An LDAP directory, covered in an earlier guide, is like a separate company’s own employee roster that the receptionist is allowed to consult, without owning or storing a full copy of it. Caching is more like the receptionist jotting a quick sticky note with a frequently asked answer, so they don’t have to walk to the record room for every single repeated question — useful, but temporary and secondary to the real record room.
| Concept | What It Is | Durability |
|---|---|---|
| Keycloak Database | The primary, authoritative storage for realms, local users, roles, and settings | Fully persistent |
| LDAP Directory (Federation) | An external directory Keycloak reads federated user data from | Owned and persisted by the external directory itself |
| Caching Layer | Temporary, faster-access copies of frequently used data | Not durable — rebuilt automatically as needed |
A cache is never a substitute for the database — it exists purely to speed things up, and losing cached data causes no permanent harm, since it can always be rebuilt from the database. Losing the actual database, by contrast, means losing the real, authoritative data itself.
3What’s Actually Stored in the Database
A closer look at the categories of information the database holds.
Realm Configuration
Every realm’s settings, security policies, and authentication flows, as covered in earlier guides.
Local User Accounts
Users managed directly by Keycloak, including their hashed credentials and profile attributes.
Clients, Roles, and Groups
Every registered application, defined role (including composite roles), and group structure.
Active Sessions
Records of currently logged-in users, supporting features like viewing and revoking active sessions.
Identity Provider and LDAP Federation Settings
Connection details for external identity sources, though not the federated users’ actual data itself.
Event and Audit Logs
Records of login attempts and administrative actions, when this feature is enabled.
For an LDAP-federated realm, the actual employee records still live in the external directory — the Keycloak database mainly stores the federation’s connection settings and, depending on sync mode, a locally cached copy of some user attributes.
4How the Database Is Used During a Login
Tracing exactly when Keycloak reaches for the database during a typical login.
Keycloak Loads the Realm’s Configuration
Settings, authentication flow, and theming for the relevant realm are read from the database.
The User’s Account Is Looked Up
For local users, Keycloak queries the database directly to find the matching account and its stored password hash.
Credentials Are Verified
The submitted password is hashed and compared against the stored hash, as covered in earlier guides on authentication.
A New Session Record Is Written
On success, Keycloak writes a new session entry to the database, tracking that this user is now logged in.
A Token Is Issued Using the Retrieved Data
Roles and other claims pulled from the database are packaged into the resulting JWT, as covered in the earlier JWT guide.
sequenceDiagram
participant U as User
participant K as Keycloak
participant DB as Keycloak Database
U->>K: Submit login credentials
K->>DB: Load realm configuration
K->>DB: Look up matching user account
DB-->>K: Return account and stored password hash
K->>K: Verify submitted password
K->>DB: Write new session record
K-->>U: Issue token
Because so much of a single login touches the database, its performance and reliability directly shape how quickly and consistently users are able to log in across the entire system.
5Kinds of Databases Keycloak Can Use
Keycloak doesn’t lock you into one specific database technology.
Lightweight, Built-In Database
Suitable for local experimentation and getting started, but not intended for real, ongoing production use.
Established Open-Source Relational Databases
Widely used, mature relational database systems commonly chosen for production Keycloak deployments.
Commercial Enterprise Databases
Larger organizations sometimes run Keycloak against an existing, centrally managed commercial database platform they already operate.
It’s similar to how a small home office might get by with a simple filing cabinet, while a large corporate headquarters relies on a dedicated, professionally managed records department — both are “storage,” but the scale and reliability expectations are very different.
The lightweight, built-in database that Keycloak can start up with is meant for quick local testing and exploration — using it as the permanent backing store for a real, ongoing deployment is a well-known anti-pattern, covered further in Chapter 9.
6Startup, Migrations, and the Database Lifecycle
The database’s role doesn’t start and end with everyday logins — it’s also central to how Keycloak itself starts up and evolves.
flowchart TD
A[Keycloak Starts Up] --> B[Connect to Configured Database]
B --> C{Schema Up to Date?}
C -->|No| D[Run Database Migration]
D --> E[Schema Updated to Match Current Version]
C -->|Yes| E
E --> F[Keycloak Ready to Serve Requests]
Whenever Keycloak is upgraded to a newer version, its expected database structure may change slightly to support new features. Keycloak handles this automatically through a migration process — carefully updating the database’s structure to match what the new version expects, rather than requiring administrators to manually rebuild it by hand.
Because migrations modify the database’s actual structure, taking a full backup before a version upgrade is one of the most important, easy-to-follow safety steps available to any team operating Keycloak.
7Understanding the Database Conceptually: Tables and Relationships
A gentle mental model for how the data is organized, without needing to read raw table names.
A relational database organizes information into tables — think of each table as its own dedicated filing drawer, holding records of one particular kind, with clear relationships connecting related drawers together.
| Conceptual “Drawer” | What It Roughly Holds |
|---|---|
| Realms Drawer | One entry per realm, with its core settings |
| Users Drawer | One entry per local user account, linked to its owning realm |
| Roles Drawer | Defined roles, including which other roles a composite role includes |
| Clients Drawer | Registered applications, linked to the realm they belong to |
| Sessions Drawer | Active login sessions, linked to the user and client involved |
Imagine a set of labeled filing drawers where every user’s folder inside the Users drawer has a small tab clipped to it pointing back to exactly which Realm drawer it belongs to — that’s essentially how relational structure keeps everything correctly connected without duplicating information everywhere.
8Security Considerations for the Keycloak Database
This database is one of the single most sensitive components in the entire deployment.
Weak or Reused Database Credentials
A weak database password puts every realm, user, and role Keycloak manages at direct risk.
Unrestricted Network Access
Leaving the database reachable from outside a tightly controlled network dramatically increases its exposure.
Unencrypted Data at Rest
Without disk-level or database-level encryption, physical or storage-layer access could expose sensitive stored data.
Missing or Untested Backups
A database without regular, verified backups risks permanent, catastrophic data loss from hardware failure or human error.
Because password hashes for every local user, and the configuration for every realm, ultimately live here, the database deserves security attention at least equal to — arguably greater than — the Keycloak application itself.
9Design Patterns and Anti-Patterns
Hard-won lessons from teams operating Keycloak in real, ongoing deployments.
Problem
Running a real, ongoing deployment on the lightweight, built-in database meant purely for quick local testing.
Why It’s Harmful
This kind of database typically isn’t designed for the durability, concurrent access, or scaling needs of a genuine production system, risking data loss or serious performance problems as real usage grows.
Correct Approach
Configure Keycloak to use a properly managed, production-grade relational database from the start of any deployment meant to serve real users.
Problem
Sharing a single database between clearly separate environments, such as development and production, purely to save on setup effort.
Why It’s Harmful
Test data, experimental configuration changes, or accidental deletions made while developing can directly and immediately affect real production users and data.
Correct Approach
Give each environment — development, staging, and production — its own fully separate database, mirroring the environment-isolated realm strategy covered in an earlier guide.
Design Pattern: Regular, Verified Backups Before Upgrades
Taking a full database backup immediately before any Keycloak version upgrade — and periodically testing that backups can actually be restored — is one of the simplest, highest-value operational habits a team running Keycloak can maintain.
10Best Practices and Common Mistakes
Practical guidance for anyone operating Keycloak’s database in a real environment.
Use a Production-Grade Database From Day One
Avoid the temptation to start with a quick, built-in option and “migrate properly later.”
Restrict Network Access Tightly
Only allow the Keycloak application itself, and authorized administrators, to reach the database directly.
Back Up Regularly, and Verify Restores Work
A backup that’s never been tested for successful restoration isn’t a reliable safety net.
Monitor Performance Under Real Load
Since so much of Keycloak’s behavior depends on database responsiveness, watch for slow queries or connection issues before they affect users.
Common missteps include skipping a backup before a major version upgrade, underestimating how much database load a growing user base creates, and forgetting that database credentials deserve exactly the same careful protection as any other highly sensitive secret.
11Choosing a Database: Trade-Offs to Weigh
A fair look at what different database choices offer, and where the compromises lie.
Built-In, Lightweight Database
Advantages
- Requires essentially no separate setup — great for quickly trying Keycloak out
- Zero additional infrastructure to install or manage
Disadvantages / Trade-offs
- Not designed for the durability and concurrency demands of real production use
- Lacks the operational tooling (robust backups, clustering) a real deployment needs
Established Production-Grade Relational Database
Advantages
- Built for durability, concurrent access, and real operational demands
- Mature backup, monitoring, and scaling tooling widely available
- Well understood by most infrastructure and database teams
Disadvantages / Trade-offs
- Requires separate installation, configuration, and ongoing maintenance
- Adds another system that needs its own monitoring and security attention
12Monitoring and Maintaining the Database
Because nearly everything Keycloak does touches this layer, watching it closely pays off.
Connection Pool Monitoring
Watching how many database connections Keycloak is using helps catch capacity issues before they cause slowdowns or failures.
Slow Query Tracking
Identifying unusually slow database operations helps pinpoint performance bottlenecks affecting real user logins.
Backup Verification Routines
Periodically restoring a backup in a test environment confirms that disaster recovery will actually work when genuinely needed.
Storage Growth Tracking
Monitoring how quickly stored data — especially sessions and audit logs — grows over time helps plan capacity ahead of problems.
13Real-World and Industry Examples
Seeing the Keycloak database’s role in realistic deployment scenarios.
Cloud-Managed Database Services
Many organizations run Keycloak’s database on a managed cloud database service, offloading routine tasks like automated backups and patching to the cloud provider rather than handling them entirely by hand.
High-Availability Keycloak Clusters
Larger deployments often run several Keycloak instances simultaneously for reliability, all connecting to the same shared, robust database — the database becomes the consistent source of truth that keeps every instance in agreement.
Regulated Industries With Strict Data Requirements
Organizations in heavily regulated sectors often apply extra database-level protections — like encryption at rest and detailed audit logging — reflecting how sensitive the identity data stored there genuinely is.
14Frequently Asked Questions
For any real, ongoing deployment, yes — while Keycloak can start up with a lightweight built-in option for quick local testing, that option isn’t intended for genuine production use.
Since the database is the authoritative, persistent store for that information, losing it without a backup means permanently losing realms, users, roles, and every other stored configuration — which is exactly why regular, verified backups are so important.
Not entirely — their authoritative record remains in the external directory. Depending on the configured sync mode, Keycloak’s database may hold a cached copy of some attributes, along with the federation’s own connection settings.
It’s the automatic process Keycloak runs when upgrading versions, updating the database’s structure to match what the new version expects, so administrators don’t need to manually rebuild the schema by hand.
Yes — this is actually a common pattern for running Keycloak reliably at scale, with several instances all connecting to one shared, properly managed database to stay consistent with each other.
No — keeping them fully separate prevents test activity or mistakes made during development from ever directly affecting real production data, mirroring the environment-isolated realm strategy covered in an earlier guide.
15Summary and Key Takeaways
The Keycloak database is the persistent, authoritative record room behind everything Keycloak does — quietly storing every realm, local user, role, client, and active session, and being read from or written to during nearly every meaningful action the application performs. Choosing a properly managed, production-grade database, securing it carefully, and maintaining regular, verified backups isn’t a minor operational detail — it’s foundational to keeping an entire Keycloak deployment trustworthy and reliable over time.
Key Takeaways
- Keycloak itself doesn’t permanently remember anything — the database is where every realm, user, and setting actually lives.
- Nearly every login touches the database, reading realm and user data and writing new session records.
- The database is separate from federated directories and caches — each plays a different role with a different level of durability.
- Database migrations automatically update the schema during version upgrades, making backups beforehand essential.
- The lightweight, built-in database is for testing only — production deployments need a properly managed, durable database.
- Database security deserves top priority, since password hashes and every realm’s configuration ultimately live there.
- Separate databases per environment, plus regular verified backups, are two of the simplest, highest-value operational habits available.