/
H2 Database Migration

H2 Database Migration

Not following these steps will result in data loss!

These steps are only required when a H2 database is used. No Migration is required when other databases are configured.

When do I need to update?

The table below shows which H2 database version is included in each product version. A migration is only required when you upgrade to a newer product version that includes a higher H2 database version.

Example: If you are currently running tia® Migration version 4.1.7, your product includes H2 version 2.2.220. As long as you stay on this version, no migration is needed. However, when you upgrade to an higher version (which includes H2 version 2.4.240), you must migrate your H2 database from version 2.2.220 to 2.4.240 before starting the new version.

Product

Your current version

H2 From Version

H2 To Version

Product

Your current version

H2 From Version

H2 To Version

tia® Migration

 

<= 3.2.8

1.4.199

2.4.240

<= 3.2.17

2.1.214

2.4.240

<= 4.1.7

2.2.220

2.4.240

tia® Proxy

 

<= 1.1.10

1.4.199

2.4.240

<= 1.2.3

2.1.214

2.4.240

<= 2.0.4

2.2.220

2.4.240

tia® Document Router

 

<= 4.1.5

1.4.199

2.4.240

<= 4.2.11

2.1.214

2.4.240

<= 5.2.0

2.2.220

2.4.240

tia® ReadCache

 

<= 1.2.0

1.4.199

2.4.240

<= 1.4.2

2.1.214

2.4.240

<= 2.0.4

2.2.220

2.4.240

tia® WriteCache

 

<= 1.2.10

1.4.199

2.4.240

<= 1.4.2

2.1.214

2.4.240

<= 2.0.8

2.2.220

2.4.240

tia® Scan Server

 

<= 2.1.14

1.4.199

2.4.240

<= 2.2.1

2.1.214

2.4.240

<= 3.0.3

2.2.220

2.4.240

tia® Content Server (classic)

 

<= 5.3.12

1.4.199

2.4.240

<= 5.3.17

2.1.214

2.4.240

<= 6.0.6

2.2.220

2.4.240

tia® Viewer (classic)

 

<= 2.5.6

1.4.199

2.4.240

<= 2.7.2

2.1.214

2.4.240

<= 3.0.2

2.2.220

2.4.240

tia® Web Service (classic)

 

<= 2.1.29

1.4.199

2.4.240

<= 2.2.2

2.1.214

2.4.240

<= 3.0.10

2.2.220

2.4.240

tia® fetch (ILM-Migration)

 

<= 1.0.12

1.4.200

2.2.222

Product independent bundles

Please also note that if your product includes one of the following bundles:

  • KGS Protocol Writer Plugin

  • KGS SecurityProvider

  • KGS LockService

In that case, the databases for those bundles must also be migrated!

Where can I find the database files?

Name

Path (with filename H2 1.3.175)

Name

Path (with filename H2 1.3.175)

tia® Migration

<work>/migration/store/KGSMigration.h2.db

tia® Proxy

<work>/proxy/store/KGSProxy.h2.db

tia® Document Router

<work>/documentrouter/store/KGSDocRouter.h2.db

tia® ReadCache

<work>/readcache/store/KGSReadCache.h2.db

tia® WriteCache

<work>/writecache/store/KGSWriteCache.h2.db

tia® Scan Server

<work>/scanserver/store/scan.h2.db

KGS Protocol Writer Plugin (Bundle)

<work>/protocol/store/KGSProtocol.h2.db

KGS SecurityProvider (Bundle)

<work>/secprovider/store/secprovider.h2.db

KGS LockService (Bundle)

<work>/lockservice/store/KGSLockService.h2.db

How to migrate?

To download the necessary drivers for the migration, go to https://h2database.com/html/download.html. You need to download both versions.

Either it's the latest version, which is displayed at the top, or the version can be found under Archive Downloads.

The platform-independent ZIP file should be downloaded from there.

image-20260414-134229.png

 

  1. Identify path to H2 database file (https://kgs-software.atlassian.net/wiki/spaces/DOCUEN/pages/edit-v2/4733173813#Where-can-I-find-the-database-files%3F)

    <webapp>/<kgsPRoduct>/work/<product>/store/<product>.h2.db or <webapp>/<kgsPRoduct>/work/<product>/store/<product>.mv.db

  2. Stop the application server (make sure that *.lock.db files aren't in the folder anymore)

  3. Backup H2 files by copying all files in the folder to a different directory

  4. Execute export script

    java -cp h2-<from-version>.jar org.h2.tools.Script -url "jdbc:h2:file:<path to DB file>;MODE=MySQL;AUTO_SERVER=true;cipher=AES" -user "kgs" -password "<password>" -script export.sql

Do not use a file extension in <path to DB file>

E.g. the name of your db is “KGSMigration.h2.db” then only enter the path with the name of the database, here /webapp/migration/work/store/KGSMigration

  1. Check the export file, it should not be empty and contains values from the tables

  2. Delete the exported database (<product>.h2.db, don’t forget the backup!)

  3. Create the new database

    java -cp h2-<to-version>.jar org.h2.tools.RunScript -url "jdbc:h2:file:<path to DB file>;MODE=MySQL;AUTO_SERVER=true;cipher=AES" -user "kgs" -password "<password>" -script export.sql -options FROM_1X

Do not use a file extension in <path to DB file>

In general the name of the database stays the same. Therefore the path ist the same as above, e.g. /webapp/migration/work/store/KGSMigration

The file extension may changed after the migration → *.h2.db or *.mv.db

  1. Start the application server and check database entries

  2. Delete both H2 driver and export.sql file

The databaseconsole is no longer part of the build and must be installed manually when required.