FMR 12.4 to FMR 12.5¶

FMR v12.4.x and earlier require a migration when upgrading to FMR 12.5.0 or later. The migration is performed automatically on launch and requires no user intervention.

When FMR 12.5.0 (or later) is launched, the application compares the currently installed version of FMR, read from the installed.version property in the settings_general database table, with the version of the new distribution, defined in the metadata.properties file under WEB-INF/classes.

If the installed version is >= 12.0.0 and < 12.5.0, and the new version is >= 12.5.0, FMR's built-in upgrade engine automatically starts the migration process.

Warning

Although the migration is performed automatically, it is recommended that a database backup is taken before upgrading to FMR 12.5.0 or later.

The Migration Process¶

The migration process starts automatically when FMR 12.5.0 (or later) is launched and forms part of the normal startup sequence. As a result, the first startup of the new FMR version may take longer than usual.

The process extracts all entries from the sdmx_xs table, aggregates the rows, and writes them to a new sdmx_xs_3 table.

The table sdmx_xs table contains the history of cross-references between structures in the system, including references to individual items such as Codes, Concepts, and Categories. For example, if a Representation Map references 100 Codes from the same Codelist, the 100 rows describing those individual references are aggregated into a single row representing the reference from the Representation Map to the Codelist.

The aggregation process ensures that the FMR continues to store cross reference information, however, if the number of cross references from one object exceeds a fixed limit, the new cross reference table stores only the maintainable to maintainable reference, with the FMR calculating the individual references on demand. The result of the migration is the sdmx_xs_3 table may contain fewer rows then the sdmx_xs. The change was introduced to improve performance with large metadata, such as Representation Maps that can map hundreds of thousands of individual Codes.

The sdmx_xs table is no longer used by FMR 12.5.0 and may be deleted once your are satisfied roll back is no longer required. FMR will not delete this table automatically.

Rolling back to FMR 12.4.x or earlier remains possible, provided that no structural changes have been made while running FMR 12.5.0 or later. Any changes to the reference graph made in FMR 12.5.0 or later are recorded only in the new sdmx_xs_3 table. If FMR is subsequently rolled back, those changes will not be present in sdmx_xs and will therefore be lost.

Check the FMR logs¶

Details of the migration can be found in FMR's logs, by default FusionRegistry.log.

Note

The messages Upgrade to version 12.4.4 and Performing Upgrade 1 of 1. Upgrade to v12.4.4 are expected and simply mean that version 12.4.4 was the notional point of transition from the old to new database schema.

The following log exerpt illustrates the principle:

2026-11-02 15:23:20.370 INFO main io.sdmx.core.fmr.restore.diagnostics - [install] applicationStarted() entered, cached installed flag is false
2026-11-02 15:23:20.370 INFO main io.sdmx.core.fmr.manager.core.impl.RegistryInstallManagerImpl - RegistryInstallManagerImpl - applicationStarted
2026-11-02 15:23:20.370 WARN main io.sdmx.core.fmr.restore.diagnostics - [install] applicationStarted() reset the cached installed flag to false; any concurrent thread calling isInstalled() from now until this method resolves will re-read 'installed.version' from the database
2026-11-02 15:23:20.371 INFO main io.sdmx.core.fmr.restore.diagnostics - [install] isInstalled() entered with the cached flag false; reading 'installed.version' from the database
2026-11-02 15:23:20.373 INFO main io.sdmx.core.fmr.restore.diagnostics - [install] isInstalled() read 'installed.version' = 12.4.2
2026-11-02 15:23:20.374 INFO main io.sdmx.core.fmr.manager.core.impl.RegistryInstallManagerImpl - Product Version: 12.5.0
2026-11-02 15:23:20.374 INFO main io.sdmx.core.fmr.manager.core.impl.RegistryInstallManagerImpl - Installed Version: 12.4.2
2026-11-02 15:23:20.375 INFO main io.sdmx.core.fmr.manager.core.impl.FusionUpgradeManagerImpl - Check for Upgrades from Version '12.4.2' to version '12.5.0'
2026-11-02 15:23:20.375 INFO main io.sdmx.core.fmr.manager.core.impl.FusionUpgradeManagerImpl - 1 upgrades required
2026-11-02 15:23:20.375 INFO main io.sdmx.core.fmr.manager.core.impl.FusionUpgradeManagerImpl - Upgrade to version 12.4.4
2026-11-02 15:23:20.377 INFO main io.sdmx.core.fmr.manager.core.impl.FusionUpgradeManagerImpl - Performing Upgrade 1 of 1.  Upgrade to v12.4.4
2026-11-02 15:23:20.378 INFO main io.sdmx.core.fmr.engine.upgrade.FMR12_5_UpgradeEngine - Updating cross-reference information
2026-11-02 15:23:21.128 INFO main io.sdmx.core.dao.base.CrossReferenceV3Migration - Seeded 16028 rows (6631 precise) from 48133 v1 rows, boundary 1791369278970
2026-11-02 15:23:21.293 INFO main io.sdmx.core.dao.base.CrossReferenceV3Migration - Replayed 15258 v2 rows: 0 closures, 0 copies
2026-11-02 15:23:21.294 INFO main io.sdmx.utils.hibernate.dao.HibernateDao - Bulk Insert: 16028
2026-11-02 15:23:21.295 INFO main io.sdmx.utils.hibernate.dao.HibernateDao - JDBC batch size: 500
2026-11-02 15:23:22.145 INFO main io.sdmx.utils.hibernate.dao.HibernateDao - Bulk Insert Complete: 16028
2026-11-02 15:23:22.184 INFO main io.sdmx.core.dao.base.CrossReferenceV3Migration - Reconcile 0 sources (0 saved after the boundary, 0 with live rows written after it)
2026-11-02 15:23:22.266 INFO main io.sdmx.core.dao.base.CrossReferenceV3Migration - Verified 14833 live relationships
2026-11-02 15:23:22.268 INFO main io.sdmx.core.dao.base.CrossReferenceV3Migration - Cross reference store v3 migrated: boundary=1791369278970 v1Rows=48133 v2Rows=15258 seeded=16028 (precise 6631) closures=0 copies=0 sourcesReconciled=0 replaced=0 staleFixed=0 rowsWritten=16028 warnings=0
2026-11-02 15:23:22.268 INFO main io.sdmx.core.fmr.engine.upgrade.FMR12_5_UpgradeEngine - Re-Create deferred beans for reference metadata
2026-11-02 15:23:22.268 INFO main io.sdmx.core.dao.base.metadata.AbstractDeferrableObjectStoreDao - Rebuild Deferred Definitions: urn:sdmx:org.sdmx.infomodel.metadatastructure.MetadataSet
2026-11-02 15:23:22.290 INFO main io.sdmx.core.dao.base.metadata.AbstractDeferrableObjectStoreDao - Rebuild Deferred Definitions Count:1
2026-11-02 15:23:22.417 INFO main io.sdmx.core.dao.base.metadata.AbstractDeferrableObjectStoreDao - Rebuild Deferred Definitions Complete: urn:sdmx:org.sdmx.infomodel.metadatastructure.MetadataSet
2026-11-02 15:23:22.418 INFO main io.sdmx.core.fmr.manager.core.impl.FusionUpgradeManagerImpl - Upgrade for Version 12.4.4 Complete
2026-11-02 15:23:22.418 INFO main io.sdmx.core.fmr.restore.diagnostics - [install] isInstalled() writing 'installed.version' = '12.5.0' (was '12.4.2')
2026-11-02 15:23:22.419 INFO main io.sdmx.core.dao.model.settings.AbstractProductSettingsDao - Save setting: installed.version=12.5.0
2026-11-02 15:23:22.427 INFO main io.sdmx.core.fmr.restore.diagnostics - [install] isInstalled() wrote 'installed.version'
2026-11-02 15:23:22.427 INFO main io.sdmx.core.fmr.restore.diagnostics - [install] applicationStarted() resolved installed=true
2026-11-02 15:23:22.457 INFO main io.sdmx.core.fmr.restore.diagnostics - [install] applicationStarted() exited

After Upgrading¶

No further action is required following a successful migration. The original sdmx_xs table is retained to support rollback and may be deleted once you are satisfied that rollback to FMR 12.4.x or earlier is no longer required.