Migration of H2 databases and Mapping Table Containers

With XDM version 3.25.33, the H2 database has been updated to version 2.3.232. This update may lead to incompatibilities with existing Mapping Table Containers and H2 databases created with previous versions of XDM.

Three different workflows are available for migrating Mapping Table Containers and H2 databases to version 2.3.232. The selection of the correct workflow depends on how the Mapping Table Containers and H2 database are accessed using MappingTableUtils or ModificationUtils. The migrators can be downloaded from the Configuration Object repository, see Mapping table container and H2 database migrators.

Before migrating, back up the H2 databases and mapping table containers. These containers can still be downloaded after updating to version 3.25.33. To back up the H2 databases, save the corresponding files.

H2 databases created by task execution do not require backing up, since no migration is necessary. The database is created at runtime using the latest version (2.3.232).
Migration of Mapping Table Containers and H2 databases
1. Migration of Mapping Table Containers and H2 databases
Migration Details
2. Migration Details

Migration of Mapping Table Containers defined via Web UI

If the constructor public ModificationUtils(Connection connection) throws SQLException {} is used, the Mapping Table Containers are located in the /xdm/mapping directory. The object that must be passed to the specified constructor is actually the mapping table container object which is passed as the connection object. For migrating these containers, use the workflow Migrate Mapping Table Container. Read and write permissions on the relevant Mapping Table Containers are required before executing this workflow.

Workflow:

  • Migrate Mapping Table Container

If a custom connection has been created (for example with a self-configured JDBC Connection), the Mapping Table Containers are stored at the location defined by the connection’s URL.

  • If the URL points to /xdm/mapping, use the Migrate H2 DBs in /xdm/mapping workflow.

  • If the URL points to /xdm/data, use the Migrate H2 DBs in /xdm/data workflow.

  • For any other path, copy the respective workflow and adapt it to the specific location.

Migration of H2 databases in /xdm/data

If the deprecated constructors

  • public ModificationUtils() {}

  • public ModificationUtils(String databaseName) {}

are used, the Mapping Table Containers can be found in the /xdm/data directory. Use the Migrate H2 DBs in /xdm/data workflow for migration.

Workflow:

  • Migrate H2 DBs in /xdm/data

Migration for Custom Url Path

If the constructor public ModificationUtils(String url, String user, String password) {} is used, the location for the Mapping Table Containers is defined by the given URL.

  • If the URL points to /xdm/data, use the Migrate H2 DBs in /xdm/data workflow.

  • If the URL points to /xdm/mapping, use the Migrate H2 DBs in /xdm/mapping workflow.

  • If the URL points to any other directory, no predefined workflow is available. In this case, copy the Migrate H2 DBs in /xdm/data workflow and adapt it to the specific case.

Workflows:

  • For /xdm/data use the Workflow Template Migrate H2 DBs in /xdm/data.

  • For /xdm/mapping use the Workflow Template Migrate H2 DBs in /xdm/mapping.

  • For other paths: Copy and adapt workflow as needed.

Both migration workflow templates Migrate H2 DBs in /xdm/data and Migrate H2 DBs in /xdm/mapping use the standard credentials sa with an empty password. If these don’t apply to the H2 databases in /xdm/data or /xdm/mapping, adjust the credentials in the respective workflow template.

Migrating Mapping Table Containers or H2 databases for upload

After updating XDM to version 3.25.33, some H2 databases may no longer be uploadable as mapping table containers due to incompatibilities between the old and new H2 driver versions. These containers can still be downloaded after updating to XDM. A migration tool is available to resolve this issue. Download the tool from: https://manticore-projects.com/H2MigrationTool/index.html Use the graphical interface of the migration tool by running the following command:

java -jar H2MigrationTool-all.jar

After migrating the incompatible H2 version, uploading the mapping table container is possible again.

Memory Requirements and Troubleshooting

Should the workflow execution abort without exception message, this could be due to insufficient Java heap space. This issue may arise during the download process of the mapping table container in the Migrate Mapping Table Container workflow. To resolve this, add the following parameter to the Core Server environment variables:

- spring.cloud.deployer.xdm-runner.local.javaOpts=-Xmx6G

This example sets the maximum Java heap size to 6 GB. Adjust the value according to available hardware resources. In addition, ensure the Dataflow Server has sufficient memory to enable smooth migration.

Before starting the migration, carefully select the appropriate workflow and ensure the correct permissions and sufficient system resources are in place.

Migrating H2 files in /xdm/backups

This migration is only necessary for icebox generations created between 3.24.21 and 3.24.29.

For some icebox generations, there may be a lobs.mv.db file inside the icebox generation which contains LOB (Large object) data. If such a file exists and contains lob data, it also needs to be migrated. Otherwise, the corresponding icebox generation cannot be used with H2 version 2.3.232.

The following workflow migrates these lobs.mv.db files if they are present in the icebox generation directories within /xdm/backups.

The migrator can be downloaded here