The Keycloak Upgrade Ledger

Every upgrade we have rehearsed, with the environment stated and the clock running.

2026-08-26 · run 2026-08-26-mariadb-s4-and-toolchain

MariaDB: toolchain port + S4 confirmed identical to MySQL

Upgrade
26.0.0 → 26.7.1
Scale
200 users, 2 realms
Database
MariaDB 11.4.13, single node, container mariadb:11.4
Host
laptop (Docker 29)
Condition
Engines other than Postgres · DB user without DDL rights

Summary

MariaDB 11.4 (LTS) is the second non-Postgres engine. Three results:

  1. The toolchain needed one more port. MariaDB renames the MySQL client tools — mariadb / mariadb-dump instead of mysql / mysqldump, with no compat symlinks in the image. snapshot.sh / restore.sh / index-audit.sh now pick the binary from the engine; the dump flag set also differs (MariaDB has no --set-gtid-purged / --no-tablespaces).

  2. The migration is clean. 26.0.0 → 26.7.1 reaches ready, migration_model 26.7.1, and the index audit (engine mariadb) reports 121 correct / 0 missing / 0 wrong shape.

  3. S4 carries over byte-for-byte from MySQL. A DML-only account fails the migration at Liquibase's own setup — ALTER command denied to user 'kc_dml' for table DATABASECHANGELOG [Failed SQL: (1142) ALTER TABLE keycloak.DATABASECHANGELOG ADD PRIMARY KEY (ID, AUTHOR, FILENAME)] — and granting the DDL set (CREATE, ALTER, DROP, INDEX, REFERENCES, CREATE VIEW, SHOW VIEW) makes it succeed. No ownership concept, same as MySQL.

Environment

FieldValue
Keycloak from → to26.0.0 → 26.7.1
DatabaseMariaDB 11.4.13, single node, container mariadb:11.4
DB flagsutf8mb4 / utf8mb4_unicode_ci (no invisible-PK flag — that is MySQL-only)
Cachelocal (single node)
Dataset scale200 users, 2 realms
Seeding methodpartialImport (seed-realm.sh --profile typical)
Hostlaptop (Docker 29)

Results

RunAccount's rightsOutcome
smokekeycloak (all on keycloak.*)READY, audit 121/121
Akc_dml DML onlyexit 1ALTER command denied ... DATABASECHANGELOG ADD PRIMARY KEY (error 1142)
Bkc_dml DML + DDLREADY, audit 121/121

Verification

ClaimEvidence
Migration clean on MariaDBmigration_model 26.7.1, audit 121/121 ☑
DML-only fails, DDL suffices (no ownership)run A 1142 vs run B READY ☑
Snapshot/restore round-trips on MariaDBrestore "no re-migration", users 200 ☑

← All runs