SUSE Manager/migration notes

From MicroFocusInternationalWiki
Jump to: navigation, search

Notes about schema migrations


Incorrect manual interventions in the /etc/sysconfig/rhn/schema-upgrade directory have the potential of unrecoverable data loss and unsupportable scenarios.

Please read and understand carefully this page before altering any file or directory in the path above.


SUSE Manager’s database schema changes between product versions - tables are added, dropped, restructured to accommodate for new features, optimizations, bug fixes etc.

We do not upgrade the database schema automatically as part of RPM upgrades - rather we rely on users running a specific command, spacewalk-schema-upgrade, after RPMs are installed, to carry out the so-called “schema upgrade”.

This command does the following:

  • it reads the current schema version from the database
  • it looks for a directory in /etc/sysconfig/rhn/schema-upgrade named susemanager-schema-<CURRENT_VERSION>-to-susemanager-schema-<NEWER_VERSION>
  • if one is found, SQL scripts in that directory are executed in lexicographic order
  • CURRENT_VERSION is set to NEWER_VERSION and a new search in /etc/sysconfig/rhn/schema-upgrade is made, possibly leading to a chain of upgrades

Major version upgrade problem

When dealing with major version upgrades, directories in /etc/sysconfig/rhn/schema-upgrade have to cover all possible pairs of versions. For example, users should be able to migrate from any 3.0 version to the latest 3.1 version at any point in time (this example is followed from now on, but the reasoning is general).

This is unfortunately not always possible, particularly in cases when a 3.1 minor version is released before a 3.0 minor version. In that case packages in 3.1 might not contain schema migrations from the very latest 3.0 version, simply because they were published before the exact 3.0 version number was attributed.

In those rare cases where users have to migrate the very latest 3.0 version to 3.1 and the 3.1 version does not yet contain a valid schema upgrade script for that version, a workaround described below is recommended.


The workaround consists in creating an empty directory in /etc/sysconfig/rhn/schema-upgrade, specifically from the version of 3.0 the user is upgrading from to the very first 3.1 version: 3.1.0.

This results in spacewalk-schema-upgrade applying any pending 3.0 upgrade first, then to start applying all 3.1 schema upgrades from the first to the last.

Incorrectly-applied workaround

Applying an incorrect workaround, ie. creating the wrong directory, can have disastrous results.

There was a case where the user was migrating from 3.0.22 to 3.1.12, and an empty directory was created with this name:


Later on the user tried to migrate to 3.1.15 and that failed because changes introduced from 3.1.0 had not been applied.


If at all possible, avoid any manual intervention in /etc/sysconfig/rhn/schema-upgrade. If you think you really need to do so, please ask for a confirmation to the development team before proceeding.