Upgrade XL 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 XL Release.

Beginning with version 7.5.0, XL 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 XL 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 XL 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 XL 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 XebiaLabs support team before upgrading.

Upgrade procedure

To upgrade from XL Release version 7.0.x through 7.2.x to XL Release version 7.5.x:

  1. Go to the XebiaLabs software distribution site and obtain a new version of the XL Release software and, if necessary, a new license. Customer log in is required to access this URL.

  2. Ensure that there are no active tasks, then shut down XL Release:

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

    Note: In a hot-standby configuration, all nodes must be stopped.

  3. 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.

  4. Go to the XebiaLabs software distribution site and download the version of the XL Release SQL Migrator Tool that corresponds to the 7.5.x version to which you are upgrading.

  5. Extract the SQL Migrator Tool ZIP file in a directory on the same host computer as the source XL Release server. For information on the supported database drivers, see Database drivers.

  6. Configure the conf/xl-release-sql-migrator.conf in the SQL Migrator Tool directory to identify the xlrelease database that the target XL 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.

  7. 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.

  8. If you modified the xlr-wrapper-*.conf file in your source XL 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/*
  9. Run the SQL Migrator Tool from the XL_RELEASE_SERVER_HOME folder of the source server. The SQL Migrator Tool will load your XL Release conf, ext, and plugins folder to load extra synthetic types. For example, if the source XL 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.
  10. If you have implemented any custom plugins, copy them from the plugins directory of the source XL Release installation to the plugins directory of the target installation. Important: When upgrading XL Release, do not overwrite the script.policy file. You must use the new version of the file.

  11. Copy the content of the ext directory from the source installation to the ext directory of the target installation.

  12. Copy the content of the conf directory from the source installation to the conf directory of the target installation.

  13. If you changed the XL 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 XL Release.

  14. 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.

  15. Open conf/xl-release-sql-migrator.conf and copy the contents of the file.

  16. Open XL_RELEASE_SERVER_HOME/conf/xl-release.conf and paste the content.

  17. 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: XL Release will encrypt the passwords in the xl-release.conf file upon startup.

  18. Start the new version of XL 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
  19. Shut down XL Release:

    Operating system Shortcut
    Microsoft Windows Ctrl + c
    Unix-based systems Ctrl + c
  20. Start XL 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). XebiaLabs recommends using only the thin drivers. Refer to the Oracle JDBC driver FAQ for more information.
PostgreSQL PostgreSQL JDBC driver Use the JDBC42 version, because XL 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 XL Release (conf/xl-release.conf) exactly matches the database configuration in the SQL Migrator Tool.
  • If you need to adjust the configuration in XL Release, you can rerun the SQL Migrator Tool and it will create the new tables and migrate the existing data with the new settings.