Upgrade Release from 7.0.x through 7.2.x to 7.5.x
This topic describes the prerequisites, process and considerations for upgrading from version 7.0.x through 7.2.x to version 7.5.x of Release.
Beginning with version 7.5.0, Release uses a new SQL-based relational database backend which replaces the JackRabbit-based (JCR) repository used in previous releases. To upgrade to version 7.5.x, you will need to run a SQL Migrator Tool to migrate JCR data to SQL.
Prerequisites
This procedure assumes you are starting from a version between 7.0.x and 7.2.x. If you are starting from an earlier version, follow the upgrade instructions in Upgrade to Release 7.0.x through 7.2.x and then return to this procedure.
To prepare for the upgrade:
- Establish external database servers for the storage of Release data. For a list of supported databases and versions, see Supported databases.
- Create a backup of your repository before beginning the upgrade. For more information, see backup Release.
- Carefully read the release manual for your destination version and note any changes that may apply to your situation.
- Check if there are any hotfixes installed in the
hotfix
directory. If hotfixes are installed, contact the Digital.ai Support team before upgrading.
Upgrade procedure
To upgrade from Release version 7.0.x through 7.2.x to Release version 7.5.x:
- Go to the Deploy/Release Software distribution site and obtain a new version of the Release software and, if necessary, a new license. Customer log in is required to access this URL.
-
Ensure that there are no active tasks, then shut down Release:
Operating system Shortcut Microsoft Windows Ctrl + c Unix-based systems Ctrl + c Note: In a hot-standby configuration, all nodes must be stopped.
- Create an
xlrelease
database and anxlrelease
user in your SQL database and grant thexlrelease
user access to create tables. Note: Tables are only created during the upgrade process, not during operation. - Go to the Deploy/Release Software distribution site and download the version of the Release SQL Migrator Tool that corresponds to the 7.5.x version to which you are upgrading.
- Extract the SQL Migrator Tool ZIP file in a directory on the same host computer as the source Release server. For information on the supported database drivers, see Database drivers.
-
Configure the
conf/xl-release-sql-migrator.conf
in the SQL Migrator Tool directory to identify thexlrelease
database that the target Release server will use. For example, a MySQL configuration would be:xl { database { db-driver-classname = "com.mysql.jdbc.Driver" db-url = "jdbc:mysql://mysql-server-host/xlrelease" db-username = "xlrelease" db-password = "xlrelease" max-pool-size = 30 } archive { db-driver-classname = "org.h2.Driver" db-url = "jdbc:h2:mem:test" db-username = "sa" db-password = "" max-pool-size = 30 } }
Important: Setting the page size is recommended when you have large releases that contain a large number of comments.
-
Set the page size used to fetch releases from the JCR repository by adding the following configuration snippet to
conf/xl-release-sql-migrator.conf
:xl { database { ... } migrator { pageSize = 100 # page size when fetching JCR or archived releases } }
Note: The SQL Migrator Tool uses a 4 GB JVM heap. If you see an
OutOfMemoryError
during migration, decrease the page size. -
If you modified the
xlr-wrapper-*.conf
file in your source Release installation, add your custom classpath tobin/xl-release-sql-migrator
in the SQL Migrator Tool directory. For example:CLASSPATH=$APP_HOME/conf:$APP_HOME/lib/*:./conf:./ext:./hotfix/*:./plugins/*
-
Run the SQL Migrator Tool from the
XL_RELEASE_SERVER_HOME
folder of the source server. The SQL Migrator Tool will load your Releaseconf
,ext
, andplugins
folder to load extra synthetic types. For example, if the source Release installation is located at/opt/xl-release-7.0.0-server
and the SQL Migrator Tool is located at/opt/xl-release-sql-migrator-7.5.7
:- Go to
/opt/xl-release-7.0.0-server
. - Execute:
/opt/xl-release-sql-migrator-7.5.7/bin/xl-release-sql-migrator
Notes:
- The source server does not need to be running. The SQL Migrator Tool does not modify the repository of the source server.
- You do not need to specify the installation directory of the target server. Configuring the database location is sufficient.
- The SQL Migrator Tool supports incremental migration. If you stop it in the middle of the process and restart it later, it will skip the releases that were already migrated.
- For more information on the tool’s running options, see SQL Migrator Tool running options.
- Go to
- If you have implemented any custom plugins, copy them from the
plugins
directory of the source Release installation to theplugins
directory of the target installation. Important: When upgrading Release, do not overwrite thescript.policy
file. You must use the new version of the file. - Copy the content of the
ext
directory from the source installation to theext
directory of the target installation. - Copy the content of the
conf
directory from the source installation to theconf
directory of the target installation. - If you changed the Release server startup script(s) in the
bin
directory of the source installation, do not copy the changed script(s) to the target installation. Manually reapply the changes to the files that were provided in the new version of Release. - Depending on your database, select a driver from the Database drivers section, and install the driver (JAR) file in the
lib
folder of the target installation. - Open
conf/xl-release-sql-migrator.conf
and copy the contents of the file. - Open
XL_RELEASE_SERVER_HOME/conf/xl-release.conf
and paste the content. -
Change the word
archive
toreporting
.Important: Database configuration in
xl-release.conf
must matchxl-release-sql-migrator.conf
.For example, a PostgreSQL configuration would be:
xl { cluster.mode = default database { db-driver-classname="org.postgresql.Driver" db-url="jdbc:postgresql://localhost:5432/xlrelease" db-username=xlrelease db-password="xlrelease" } }
If the reporting archive is configured to use an external database (recommended), you must also configure the connection settings in
XL_RELEASE_SERVER_HOME/conf/xl-release.conf
. If you are using the embedded archive database, you do not need to configure it.xl { cluster.mode = default database { db-driver-classname="org.postgresql.Driver" db-url="jdbc:postgresql://localhost:5432/xlrelease" db-username=xlrelease db-password="xlrelease" } reporting { db-driver-classname="org.postgresql.Driver" db-url="jdbc:postgresql://localhost:5432/xlarchive" db-username=xlarchive db-password="xlarchive" } }
Note: Release will encrypt the passwords in the
xl-release.conf
file upon startup. -
Start the new version of Release interactively so that automatic upgraders can run: Open a command prompt or terminal, point to the
XL_RELEASE_SERVER_HOME/bin
directory, and depending on your system, execute on of the following commands:Operating system Command Microsoft Windows run.cmd
Unix-based systems run.sh
-
Shut down Release:
Operating system Shortcut Microsoft Windows Ctrl + c Unix-based systems Ctrl + c -
Start Release by opening a command prompt or terminal, pointing to the
XL_RELEASE_SERVER_HOME/bin
directory, and executing the appropriate command:Operating system Command Microsoft Windows run.cmd
Unix-based systems run.sh
Database drivers
The SQL Migrator Tool only contains JDBC drivers for the Derby and H2 embedded databases. If you migrate to another database, you must download the appropriate JDBC driver JAR file and place it in the lib
folder of the SQL Migrator Tool.
Database | JDBC drivers | Notes |
---|---|---|
Oracle | JDBC driver downloads | For Oracle 12c, use either the 12.1.0.1 driver (ojdbc7.jar ) or the 12.2.x driver (ojdbc8.jar ). We recommend using only the thin drivers. Refer to the Oracle JDBC driver FAQ for more information. |
PostgreSQL | PostgreSQL JDBC driver | Use the JDBC42 version, because Release 4.8.0 and later requires Java 1.8. |
MySQL | Connector\J 5.1.30 driver download | |
Microsoft SQL Server | Microsoft JDBC Driver | Also available on GitHub: Microsoft/mssql-jdbc. |
DB2 | DB2 JDBC driver | Download the JDBC 4.0 driver that matches your DB2 version. |
SQL Migrator Tool running options
You can run the migrator with the following environment variables:
Option | Description | Default value |
---|---|---|
ACCEPT_MIGRATION=true |
The confirmation screen is not displayed. | false |
MIGRATE_REPOSITORY=true |
The JCR repository will be migrated. | true |
MIGRATE_ARCHIVE=true |
The archive database will be migrated. | false |
SKIP_ERRORS=true |
Errors on writing configuration items will be skipped and logged in the error log. | false |
Troubleshooting
- Ensure that the configuration file to set up the database in Release (
conf/xl-release.conf
) exactly matches the database configuration in the SQL Migrator Tool. - If you need to adjust the configuration in Release, you can rerun the SQL Migrator Tool and it will create the new tables and migrate the existing data with the new settings.