Database schema migration configuration parameters not working as expected

Describe the bug

Following https://www.keycloak.org/docs/latest/upgrading/index.html it states that you can enable manual schema migration by adding the --spi-connections-jpa-default-migration-strategy=manual parameter to the startup command.

However when doing so the expected sql file is not generated and database is migrated automatically.

Steps to reproduce the issue

services:
  keycloak:
    container_name: keycloak
    image: quay.io/keycloak/keycloak:15.0.0
    environment:
      - DB_ADDR=postgres
      - DB_USER=keycloak
      - DB_PASSWORD=keycloak-secret
    ports:
      - 8080:8080
      - 8443:8443
      - 9990:9990
    depends_on:
      - postgres
  postgres:
    image: postgres:13-alpine
    environment:
      - POSTGRES_DB=keycloak
      - POSTGRES_USER=keycloak
      - POSTGRES_PASSWORD=keycloak-secret
    ports:
      - 5432:5432
    volumes:
      - pg-volume:/var/lib/postgresql/data
volumes:
  pg-volume:
    driver: local

Run docker-compose up and wait for the database to have been setup. Close the instance and create a new docker-compose file with

services:
  keycloak:
    container_name: keycloak
    image: quay.io/keycloak/keycloak:17.0.0
    command: ["start", "--auto-build", "--spi-connections-jpa-default-migration-strategy=manual"]
    environment:
      - KC_DB=postgres
      - KC_DB_URL_HOST=postgres
      - KC_DB_URL_DATABASE=keycloak
      - KC_DB_USERNAME=keycloak
      - KC_DB_SCHEMA=public
      - KC_DB_PASSWORD=keycloak-secret
    ports:
      - 8080:8080
      - 8443:8443
      - 9990:9990
    depends_on:
      - postgres
  postgres:
    image: postgres:13-alpine
    environment:
      - POSTGRES_DB=keycloak
      - POSTGRES_USER=keycloak
      - POSTGRES_PASSWORD=keycloak-secret
    ports:
      - 5432:5432
    volumes:
      - pg-volume:/var/lib/postgresql/data
volumes:
  pg-volume:
    driver: local

Run docker-compose up again.

Version

17.0.0 Quarkus

Expected behavior

A sql file is generated instead of migrating the database automatically

Actual behavior

The database is migrated automatically

How to Reproduce?

No response

Anything else?

No response

[pedroigor]

@lmorocz Created https://github.com/keycloak/keycloak-documentation/pull/1647 to update docs.

[lmorocz]

Hi! According to PR#11110 I tried to start v19.0.1 with the manual strategy using parameters:

--spi-connections-jpa-quarkus-migration-strategy=manual --spi-connections-jpa-quarkus-initialize-empty=false --spi-connections-jpa-quarkus-migration-export="/tmp/keycloak_migr.sql"

but unfortunately it didn’t work. The database is migrated automatically and there is no export file in /tmp.

What is missing here?

In 19.0.0 there was a change in the provider id/name from quarkus to legacy (as well as QuarkusJpaConnectionProviderFactory -> LegacyJpaConnectionProviderFactory). What is the new provider id/name if I’m using db=postgres?

Update

Ok, I checked the “Provider info” page of the master realm and in v19.0.1 with db=postgres the SPI is ‘connectionsJpa’ and the provider id is legacy, so with this setup one should start with

--spi-connections-jpa-legacy-migration-strategy=manual --spi-connections-jpa-legacy-initialize-empty=false --spi-connections-jpa-legacy-migration-export="/tmp/keycloak_migr.sql"

but it depends on the <provider-id>. We should update the upgrading documentation and PR#11110 too.