H2 Migration Tool

Version 9.3.3

In the 9.3.3 version of XEServer product line, all H2 databases distributed with products were upgraded to version 2.2.224. This was done to address the vulnerability reported in CVE-2022-45868.

Versions 9.2.4 to 9.3.2

In the 9.2.4 version of XEServer product line, all H2 databases distributed with products were upgraded to version 2.1.210. This was done to address the vulnerabilities reported in CVE-2021-42392, CVE-2022-23221, CVE-2021-23463.

If you are upgrading to any of the versions starting with 9.2.4, you have to migrate all the H2 databases created by previous versions of the XEServer line products. Below are some examples of such H2 databases:

  • Databases under {ECRootPath}\XESManager\workspace\,
  • FHIR Server database {ECRootPath}\XESModuleForFHIR\db\fhir_bridge.mv.db,
  • OAuth clients database {ECRootPath}\XEConnect\config\oauth\sample_fhir.mv.db,
  • Balance Counters configuration database {ECRootPath}\XESModuleForFHIR\db\bc_etl.mv.db.

For easy and smooth migration of H2 databases, use H2 Migration Tool that was specially designed for this task. The tool allows you to locate outdated H2 databases on your file system and upgrade their version from 1.4 and 2.2.224 including database content migration.

Tool Usage

You can download the tool from the following locations:

After unzipping the tool package, the directory Edifecs H2 Migration Tool contains several .bat(.sh) scripts:

  • run.bat(.sh): The main script to run the tool. Other scripts in the directory are variations of calling run.bat(.sh) with parameters.
  • scan.bat(.sh): Use to locate outdated databases and list them in the scan report. No migration.
  • migrate-folder.bat(.sh): Use to migrate all databases within a specific directory.
  • migrate-several-dbs.bat(.sh): Use to migrate several databases.
  • migrate-single-db.bat(.sh): Use to migrate a single database.
  • migrate-ecl.bat(.sh): Use to migrate H2 ECL databases.

To use the tool, you should run any of the scripts above and the tool will prompt you to enter database credentials and optional additional parameters (if any). Additional parameters are H2-specific parameters typically specified in the H2 connection URL, for example FILE_LOCK={FILE|SOCKET|FS|NO}.

Below you can view script usage examples that show how to locate and migrate outdated H2 databases.

Copy 
run.bat -mode scan -scan-report scan-report.csv -scan-folder "X:\h2_migrate_test"
:: or
scan.bat "X:\h2_migrate_test"
Copy 
run.bat -mode migrate -migrate-report migrate-report.csv -scan-folder "X:\h2_migrate_test"
:: or
migrate-folder.bat "X:\h2_migrate_test"
Copy 
run.bat -mode migrate -migration-report migration-report.csv -db "X:\h2_migrate_test\m_test.h2.db"
:: or
migrate-single-db.bat "X:\h2_migrate_test\m_test.h2.db"
Copy 
 run.bat -mode migrate -scan-report scan_report.csv
Copy 
run.bat -mode ecl -migration-report migration-report.csv -scan-folder "%ECRootPath%\Common\UserECLDB\jECL"
:: or
migrate-folder.bat "%ECRootPath%\Common\UserECLDB\jECL\" 

Database Credentials

To access an H2 database, the tool needs a username and a password. When you run a tool script, the tool prompts you to enter credentials. By default, most of the H2 databases distributed with XEServer product line have the following credentials:

  • username: "sa"
  • password: empty or "password"

Tip You do not have to specify credentials when migrating ECL databases using -mode ecl.

Tool CLI Parameters

Below you can view parameters accepted by run.bat(.sh).

Parameter Description Is Mandatory
-mode <scan|migrate|ecl>

Defines the mode to use:

  • scan: use to find outdated H2 databases. The scan report lists found databases.
  • migrate: use to migrate outdated H2 databases.
  • ecl: use to migrate ECL H2 databases.
 Yes
-version-to <target db driver version>

Defines to which version the migration must be performed, for example, 2.2.222. Select one of the versions supported by the application. If the parameter is not specified, the maximum supported version will be used. The version must be greater than the version of the current database version.

Note This parameter is only supported when upgrading to 9.3.3 product version.

 No
-scan-folder <path> Defines a directory to recursively scan for H2 databases.

For migrate mode, you must provide either a directory to scan (-scan-folder <path>) or an explicit database file (-db <path>) if -scan-report is not specified.
-db <path> Defines a specific .mv.db file to scan/migrate.
-scan-report <path> Defines a path to store a scan report. Also, you can use this parameter to feed scan report files to the tool when you run the tool in the migration mode.

Mandatory only for scan mode. For migrate mode, this parameter is required if -scan-folder or -db is not specified.
-migration-report <path> Defines a path to store a migration report. No
-stop-after-first-failure Indicates whether to stop the migration process after the first failure. No
-silent Setting this flag ignores errors during the migration. No
-retcodes Displays the description of all the possible return codes. If this flag is set, other flags are ignored. No
-h Displays the description of all the supported command line parameters. If this flag is set, other flags are ignored. No

Logs and Reports

The tool generates two types of reports: scan reports and migrate reports. A scan report lists all database files detected by the tool and indicates whether the database requires an upgrade.

Copy

scanReportSample.csv

Path,Status
"X:\test\H2-migrate-test\sample_db_uptodate.mv.db","UPTODATE"
"X:\test\H2-migrate-test\sample_db_old.mv.db","OUTDATED"

Tip You can feed a scan report to the tool as well - in this case the tool migrates the databases specified in the report.

A migration report reflects the migration operation outcome.

Copy

migrationReportSample.csv

Path,Status
"D:\test\H2-migrate-test\sample_db_uptodate.mv.db","UPTODATE"
"D:\test\H2-migrate-test\sample_db_corrupted.mv.db","FAILED"
"D:\test\H2-migrate-test\sample_db_encoded.mv.db","POTENTIALLY_OUTDATED"

Where

  • FAILED: Indicates that the migration tool was unable to sync data between the databases. In this case, you have to handle database content migration manually.
  • POTENTIALLY_OUTDATED: Indicates that the tool was unable to recognize the database version due to the database being encoded, corrupted, etc. Requires manual investigation.