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 an xlrelease user in your SQL database and grant the xlrelease 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.

Operating system	Shortcut
Microsoft Windows	Ctrl + c
Unix-based systems	Ctrl + c

Configure the conf/xl-release-sql-migrator.conf in the SQL Migrator Tool directory to identify the xlrelease 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 to bin/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 Release conf, ext, and plugins 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:
1. Go to /opt/xl-release-7.0.0-server.
2. 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.
If you have implemented any custom plugins, copy them from the plugins directory of the source Release installation to the plugins directory of the target installation. Important: When upgrading Release, do not overwrite the script.policy file. You must use the new version of the file.
Copy the content of the ext directory from the source installation to the ext directory of the target installation.
Copy the content of the conf directory from the source installation to the conf 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 to reporting.

Important: Database configuration in xl-release.conf must match xl-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

Operating system	Command
Microsoft Windows	`run.cmd`
Unix-based systems	`run.sh`

Operating system	Shortcut
Microsoft Windows	Ctrl + c
Unix-based systems	Ctrl + c

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.