DB Schema Migration IAM 8.0

Airlock IAM 8.0 is a major release and it introduces breaking changes to the DB schema.

For all minor releases of IAM 7.x, changes to the DB schema were introduced as optional. Only customers that wanted to use new features that depended on DB schema changes were required to adopt those changes.

With IAM 8.0, all the optional changes of previous minor versions are becoming mandatory to align all customer DB schema. If IAM 8.0 is run against a database that is not fully up to date, IAM will either not start correctly or run into errors during operation.

Migration of older Releases

To migrate the IAM database to the current version of the schema, these points must be considered:

  • Running the same DB migration script multiple times is unsafe and may lead to unexpected results.
  • Running DB migration scripts out of order is unsafe and may lead to unexpected results.
  • To verify if a DB migration was successful, compare the current DB schema against the create-medusa-schema.sql script. You can find these scripts here Relational databases for IAM.

Migration of IAM 7.7 to IAM 8.0

The following list shows the most important changes that have been introduced with the migration from IAM 7.7 to IAM 8.0:

  • During migration, all timestamps in the token table are converted from a string presentation of timestamps to nanoseconds since the epoch. This conversion is necessary to make timestamps resilient against issues with timezones and with changes from and to daylight saving time.
    • Before attempting a migration, the timezone of the server running Airlock IAM must be verified. If the server is not set to "Europe/Zurich" (also called "Central European Standard Time"), the correct timezone must be set in the database migration script. To determine the correct identifier for your database, please consult the database documentation.
    • The migration duration of the timestamps in the token table depends on the number of records in the table. For large numbers of tokens and depending on the speed of the database, this may take some time.
    • Successfully migrating MariaDB or MySQL databases may require time zone information to be installed in the database. Please refer to the documentation of your database to see how time zone information can be added to the database.
  • The column value in the oauth2_session_attribute table has been renamed to content. This rename was mandatory because the H2 database now considers value as a reserved word.
  • With IAM 8.0, the user trail logs are no longer logged into a file but into a database. The migration scripts will automatically create the required tables and indices.
  • With the removal of the JSP Loginapp, the migration script will automatically remove 2 tables and 4 columns from other tables.