Engineering a MANUAL_UPDATE DB Migration Strategy for Keycloak #47015

arisDir · 2026-03-10T10:54:43Z

arisDir
Mar 10, 2026

The Architectural Gap

While integrating Keycloak into a high-availability environment, I identified a significant friction point in the official migration strategies.

Keycloak currently offers:

UPDATE: Automates execution but requires that the initial node experiences a significant delay while executing migration scripts.
MANUAL: Generates scripts but requires external human or tool intervention to execute them, which is difficult to scale.

The Problem: There is no native way to tell Keycloak: "Execute the pending migrations now, and exit successfully so my pipeline can proceed to the next stage."

The Conclusion: The Need for `MANUAL_UPDATE`

To resolve these issues, I concluded that a new migration strategy, MANUAL_UPDATE, is necessary to support "migration-as-code" within containerized environments.
This strategy would decouple the database migration phase from the application runtime phase.

Proposed Logic:

Start the dedicated migration mode: The Keycloak instance is launched with a specific flag (e.g., --spi-connections-jpa--quarkus--migration-strategy=manual_update).
Execution: Keycloak identifies missing changesets and executes the SQL directly against the target DB.
Exit: Upon completion, the process returns a 0 exit code, signaling to the orchestrator (like Kubernetes or Jenkins) that the environment is ready for the actual server nodes to spin up.

Technical Reflection

By proposing this change, I aim to move away from "workaround" scripts that are fragile and version-dependent.
The MANUAL_UPDATE strategy honors Keycloak’s internal Liquibase logic while providing the exit-code signals required by modern infrastructure-as-code practices.

shawkins · 2026-03-10T13:13:13Z

shawkins
Mar 10, 2026
Collaborator

Something like this would have been needed for the description of #41002, but see the comments below as the preferred direction has moved towards refining the server startup behavior instead.

The closest workaround we have to perform a migration, but not start the server are currently:

run an export of some realm that should exist, such as master
or explicitly set the nonserver profile (this should not be considered supported, and could be affected by the resolution of Allow long-running DB migrations on Kubernetes #41002):
./kc.sh --profile=nonserver start ...

cc @ahus1 @pruivo

4 replies

pruivo Mar 10, 2026
Collaborator

Why not run the import command with an empty directory? From the source code, it does nothing if no json file is found

keycloak/model/storage-services/src/main/java/org/keycloak/exportimport/dir/DirImportProvider.java

Lines 117 to 134 in 56c2721

    
           private List<String> getRealmsToImport() { 
        
               File[] realmFiles = getRootDirectory().listFiles((dir, name) -> (name.endsWith("-realm.json"))); 
        
               Objects.requireNonNull(realmFiles, "Directory not found: " + getRootDirectory().getName()); 
        
               List<String> realmNames = new ArrayList<>(); 
        
               for (File file : realmFiles) { 
        
                   String fileName = file.getName(); 
        
                   // Parse "foo" from "foo-realm.json" 
        
                   String realmName = fileName.substring(0, fileName.length() - 11); 
        
                   // Ensure that master realm is imported first 
        
                   if (Config.getAdminRealm().equals(realmName)) { 
        
                       realmNames.add(0, realmName); 
        
                   } else { 
        
                       realmNames.add(realmName); 
        
                   } 
        
               } 
        
               return realmNames; 
        
           }

I tested with an freshly started DB and it created the tables just fine.

[pedro@pedro-desktop keycloak-999.0.0-SNAPSHOT]$ mkdir /tmp/empty
[pedro@pedro-desktop keycloak-999.0.0-SNAPSHOT]$ ll /tmp/empty/
total 0
[pedro@pedro-desktop keycloak-999.0.0-SNAPSHOT]$ ./bin/kc.sh import --db=postgres --db-url-host=keycloak-database --db-username="***" --db-password="***" --dir /tmp/empty
2026-03-10 14:09:06,924 INFO  [org.infinispan.CONTAINER] (main) ISPN000974: Virtual threads support: enabled
2026-03-10 14:09:07,562 INFO  [org.hibernate.orm.jdbc.batch] (JPA Startup Thread) HHH100501: Automatic JDBC statement batching enabled (maximum batch size 32)
2026-03-10 14:09:08,191 INFO  [org.keycloak.quarkus.runtime.storage.database.liquibase.QuarkusJpaUpdaterProvider] (main) Initializing database schema. Using changelog META-INF/jpa-changelog-master.xml
2026-03-10 14:09:12,301 INFO  [org.keycloak.jgroups.certificates.CertificateReloadManager] (main) Starting JGroups certificate reload manager
2026-03-10 14:09:12,527 INFO  [org.infinispan.CONTAINER] (main) ISPN000556: Starting user marshaller 'org.infinispan.commons.marshall.ImmutableProtoStreamMarshaller'
2026-03-10 14:09:12,730 INFO  [org.keycloak.connections.infinispan.DefaultInfinispanConnectionProviderFactory] (main) Node name: node_322294, Site name: null
2026-03-10 14:09:12,846 INFO  [org.keycloak.exportimport.dir.DirImportProvider] (main) Importing from directory /tmp/empty
2026-03-10 14:09:12,850 INFO  [org.keycloak.services] (main) KC-SERVICES0050: Initializing master realm
2026-03-10 14:09:13,426 INFO  [org.keycloak.services] (main) KC-SERVICES0030: Full model import requested. Strategy: OVERWRITE_EXISTING
2026-03-10 14:09:13,426 INFO  [org.keycloak.services] (main) KC-SERVICES0032: Import finished successfully
2026-03-10 14:09:13,485 INFO  [io.quarkus] (main) Keycloak 999.0.0-SNAPSHOT on JVM (powered by Quarkus 3.32.2) started in 8.666s. Listening on: 
2026-03-10 14:09:13,486 INFO  [io.quarkus] (main) Profile nonserver activated. 
2026-03-10 14:09:13,486 INFO  [io.quarkus] (main) Installed features: [agroal, cdi, hibernate-orm, jdbc-postgresql, keycloak, narayana-jta, opentelemetry, reactive-routes, rest, rest-jackson, smallrye-context-propagation, vertx]
2026-03-10 14:09:14,492 INFO  [org.keycloak.jgroups.certificates.CertificateReloadManager] (main) Stopping JGroups certificate reload manager
2026-03-10 14:09:14,495 INFO  [com.arjuna.ats.jbossatx] (main) ARJUNA032014: Stopping transaction recovery manager
2026-03-10 14:09:14,507 INFO  [io.quarkus] (main) Keycloak stopped in 1.021s
[pedro@pedro-desktop keycloak-999.0.0-SNAPSHOT]$ echo $?
0

@aschei does this work for you?
@shawkins @ahus1 do we need to add more complexity?

shawkins Mar 10, 2026
Collaborator

@pruivo yes, this is another valid workaround.

@shawkins @ahus1 do we need to add more complexity?

We don't need a lot of complexity, but users will require that the workaround remains valid and possibly documented. If at some point in the future for example we throw an exception when nothing is imported via a directory import, that will break this usage.

pruivo Mar 10, 2026
Collaborator

oh 😢
I assume the import directory behavior was intentional, as it makes total sense to me. I didn't consider my suggestion as a workaround but the proper way to do it.

arisDir Mar 10, 2026
Author

@shawkins I want to study the idea you have proposed further.
However, I would say that I tested the workaround you suggested locally, and with it, I can achieve the goal I had set.
Also, I would say that I would prefer the export command over the import command for starting the server for the workaround.
Thank you for the quick response.

ahus1 · 2026-03-10T13:36:58Z

ahus1
Mar 10, 2026
Collaborator

@arisDir - thank you for raising this topic. I agree that the pipeline you describe could benefit from an additional command.

Still, I'd like to introduce you to the update-compatibaility command that does something related, still different: It tells you if the new version and the new configuration allows for a rolling update, or not.

https://www.keycloak.org/server/update-compatibility

This can be used to figure if out you should scale down your deployment to zero first, before starting a new instance, or if you can do a rolling update.

Starting with release 26.6, rolling updates for patch releases will be supported.

Let me know if this change of perspective helps you to have a pipeline that fits your needs.
If not, please describe the different steps you have in your pipeline, so we can understand why this might not be a good fit.

1 reply

arisDir Mar 10, 2026
Author

I recently noticed this new feature. I want to study it to see how it could benefit me.
But I would definitely like a part related to the database to be included in the rolling updates.

shawkins · 2026-03-10T14:38:44Z

shawkins
Mar 10, 2026
Collaborator

Should also link in #11678 as it discusses some of the potential relationship with update-compatibility that @ahus1 is referencing.

0 replies

Navigation Menu

Repository navigation

Engineering a MANUAL_UPDATE DB Migration Strategy for Keycloak #47015

Uh oh!

{{title}}

Uh oh!

Replies: 3 comments 5 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Engineering a MANUAL_UPDATE DB Migration Strategy for Keycloak #47015

Uh oh!

arisDir Mar 10, 2026

The Architectural Gap

The Conclusion: The Need for MANUAL_UPDATE

Technical Reflection

Replies: 3 comments · 5 replies

Uh oh!

shawkins Mar 10, 2026 Collaborator

Uh oh!

pruivo Mar 10, 2026 Collaborator

Uh oh!

shawkins Mar 10, 2026 Collaborator

Uh oh!

pruivo Mar 10, 2026 Collaborator

Uh oh!

arisDir Mar 10, 2026 Author

Uh oh!

ahus1 Mar 10, 2026 Collaborator

Uh oh!

arisDir Mar 10, 2026 Author

Uh oh!

shawkins Mar 10, 2026 Collaborator

arisDir
Mar 10, 2026

The Conclusion: The Need for `MANUAL_UPDATE`

Replies: 3 comments 5 replies

shawkins
Mar 10, 2026
Collaborator

pruivo Mar 10, 2026
Collaborator

shawkins Mar 10, 2026
Collaborator

pruivo Mar 10, 2026
Collaborator

arisDir Mar 10, 2026
Author

ahus1
Mar 10, 2026
Collaborator

arisDir Mar 10, 2026
Author

shawkins
Mar 10, 2026
Collaborator