Pentaho upgrade

You can upgrade your Pentaho products from version 8.3 or later to version 11.0 with the Pentaho Upgrade Installer.

The installer checks your environment, creates a backup, then upgrades to 11.0.

The installer supports Pentaho products installed on servers or workstations.

The installer requires 22 GB of free disk space.

The Pentaho Upgrade Installer is not supported on macOS.

If any installed product is earlier than 8.3, the installer will not proceed.

Upgrade those products to 8.3 first.

See Pentaho Server Upgrade Installer.

Before you begin

Before you run the Pentaho Upgrade Installer:

• Verify your system components are current.

  • See Components Reference.

• Stop the server before backups and installation.

  • See Stop and start the Pentaho Server and repository.

• Review your customizations.

  • Archive installation: Use this to decide what to include in the post-install report.

  • Manual installation: Use this to know what you must merge back.

• If you are upgrading a manual installation, back up these items under <root installation directory>/Pentaho__Installation:

  • pentaho.war

  • pentaho-style.war

  • Content and folders inside pentaho-server/pentaho-solutions

• If you use Hadoop clusters, back up your site.xml files.

  • The upgrade does not retain Hadoop drivers.

  • Reinstall drivers after upgrading.

• If you use plugins, back up your plugins to a separate directory.

  • The upgrade does not retain plugins.

  • Re-apply plugins after upgrading.

• Verify no users are logged in.

  • Run the Pentaho Server upgrade during off-hours.

• Verify Java requirements and JAVA_HOME.

  • See Components Reference.

Download the upgrade files

You need the platform upgrade file and the installer hash files.

Download both from the Support Portal.

1. Sign in to the Support Portal.

2. In the Pentaho card, select Download.

3. Select See all <number> articles for 11.0 downloads.

4. Select Pentaho 11.0 GA Release.

5. In the file component section, go to Utilities and Tools/Pentaho Server Upgrade Installer.

6. Download the file for your platform:

   • Linux: pentaho-update-11.0<.x.y-build number>.bin

   • Windows: pentaho-update-11.0<.x.y-build number>.exe

7. Go back to the 11.0 page.

8. Select Installer Hash Files.

9. Download installer-hash-files-<release number>-<build number>.zip.

   • Do not extract it.

   • Use the latest available hash file ZIP.

10. Optional: Move the downloaded files to a temporary location.

Upgrade with the Pentaho Upgrade Installer (GUI)

You can upgrade an archive or manual installation of Pentaho products.

Use the section that matches your installation type:

• Upgrade an archive installation

• Upgrade a manual installation

• Restore an archive installation backup

Upgrade an archive installation

Use the Pentaho Upgrade Installer to guide you through the upgrade process.

If you are upgrading in an environment without a graphical interface, use console or silent mode. See Upgrade in console or silent mode.

Activate your new licenses (per Administer Pentaho Data Integration and Analytics) before you restore a repository with the import-export utility.

Upgrade workflow

Complete these sections in order:

1. Get started by checking your environment

2. Specify customized items to address after upgrading

3. Back up your existing Pentaho products and install Pentaho 11.0

Get started by checking your environment

1. Exit any running Pentaho products and stop the server.

   • See Stop and start the Pentaho Server and repository.

2. Run the update file you downloaded from the Support Portal.

3. In Introduction, select Next.

4. In License Terms, read the agreement and accept it.

5. Select Next.

6. In Welcome, select Upgrade, then select Next.

7. Optional: To restore a backup instead of upgrading, select Restore and see Restore an archive installation backup.

8. In Choose Folder, set Folder to your Pentaho root directory, then select Next.

   • Example (default Windows): C:\Pentaho

9. When prompted, update white_list.csv. See Specify customized items to address after upgrading.

10. When prompted, select the installer hash ZIP, then select Next.

The installer runs an environment check to find installed products and compatibility.

Example server check:

Enviroment check while upgrading a Pentaho Server

Example workstation check:

Environment check while upgrading Pentaho client tools

If you have Pentaho products installed under multiple root directories, run the installer once per root directory.

Specify customized items to address after upgrading

During the environment check, the installer generates:

• preInstallConfigReport.txt

• white_list.csv

Location: <root installation directory>/Pentaho__Installation

If you have customizations, update white_list.csv before you proceed.

If you do not have customizations, skip this section.

Customizations may include:

• Modified configuration files.

• Added drivers, plugins, or other custom code.

The installer uses white_list.csv to generate post-upgrade versions of the listed items.

You may need to merge changes after the upgrade.

Perform these steps:

1. Go to <root installation directory>/Pentaho__Installation.

2. Verify that white_list.csv includes all changed items that must be carried forward.

3. Review the two columns in white_list.csv:

   • Item type: script, configuration file, JDBC driver, directory, KTR file, or KJB file.

   • File or directory path: path within the distribution. It can include regular expressions.

4. Select Next to continue.

5. Review <root installation directory>/Pentaho__Installation/preInstallConfigReport.txt.

6. If you update white_list.csv, select Previous, then Next to re-run the environment check.

7. Re-open preInstallConfigReport.txt and confirm the results match your expected customizations.

Custom directories you created at the <root installation directory> level are ignored by the installer.

Back up your existing Pentaho products and install Pentaho 11.0

1. Select Next to start the backup.

2. In Backup, wait for completion, then select Next.

3. In Pre-Installation Summary, review the information, then select Install.

4. After installation completes, select Next.

   • Default log location: <root installation directory>/Pentaho__Installation/logs

5. In Install Complete, select Done.

6. Apply 11.0 licenses.

   • See Administer Pentaho Data Integration and Analytics.

7. Optional: Merge customizations.

   • See Post-upgrade tasks.

8. Restart the Pentaho Server.

   • See Stop and start the Pentaho Server and repository.

After upgrading, complete the Post-upgrade tasks.

Upgrade a manual installation

Use the installer to create upgrade files in an empty folder.

Then copy those files into your manual installation.

If you cannot use a graphical interface, use console or silent mode. See Upgrade in console or silent mode.

Activate your new licenses (per Administer Pentaho Data Integration and Analytics) before you restore a repository using the import-export utility.

1

Install upgrade files into an empty folder

1. Go to a location separate from your current Pentaho installation.

2. Create an empty folder named pentaho-upgrade-files.

3. Run the installer update executable you downloaded from the Support Portal.

4. In Introduction, select Next.

5. In License Terms, accept the agreement.

6. Select Next.

7. In Welcome, select Upgrade, then select Next.

8. In Choose Folder, select pentaho-upgrade-files, then select Next.

9. When prompted, select the installer hash ZIP, then select Next.

Upgrade files are now in pentaho-upgrade-files.

2

Update files in a manual installation

1. In your manual installation, go to <root installation folder>/Pentaho__Installation.

2. Delete:

   • pentaho.war

   • pentaho-style.war

   • All files and folders in pentaho-server/pentaho-solutions

3. Copy pentaho-upgrade-files/server/pentaho-server/pentaho-solutions/* into your manual installation’s pentaho-server/pentaho-solutions.

4. Create pentaho.war:

   1. Go to pentaho-upgrade-files/server/pentaho-server/tomcat/webapps/pentaho.

   2. Compress the contents of the pentaho folder into a ZIP named pentaho.war.

   3. Copy pentaho.war to <root installation folder>/Pentaho__Installation.

5. Create pentaho-style.war:

   1. Go to pentaho-upgrade-files/server/pentaho-server/tomcat/webapps/pentaho-style.

   2. Compress the contents of the pentaho-style folder into a ZIP named pentaho-style.war.

   3. Copy pentaho-style.war to <root installation folder>/Pentaho__Installation.

Next:

• Review Post-upgrade tasks.

• If you use a Quartz database, review Mandatory Quartz upgrade (10.2.0.1 and later).

Restore an archive installation backup

When you upgrade an archive installation, the installer creates a backup ZIP.

Use that backup to restore the earlier version.

Before you begin

1. Exit any Pentaho products that are running.

2. If you are restoring Pentaho Server, stop the server.

   • See Stop and start the Pentaho Server and repository.

Verify that JAVA_HOME points to your current Java installation.

Restore an archive installation backup

1. Run the installer update executable you downloaded from the Support Portal.

2. In Introduction, select Next.

3. In License Terms, accept the agreement.

4. Select Next.

5. In Welcome, select Restore, then select Next.

6. In Environment Check, select the archive backup you want to restore.

   

   Using Pentaho Upgrade Installer to restore a selected environment
7. Select Next, then confirm the replacement.

8. After the restore completes:

   • If the installer reports errors, review the log.

   • If you cannot resolve the error, contact support.

   • Default log location: <root installation directory>/Pentaho__Installation/logs

9. Select Done to exit the installer.

10. Restart the Pentaho Server.

    • See Stop and start the Pentaho Server and repository.

Upgrade in console or silent mode

Use console mode or silent mode when you cannot use a GUI.

The Pentaho Upgrade Installer does not support console mode or silent mode on macOS.

Command-line parameters

• -help or --help: Show usage help.

• -i <gui|silent|console>: Select the installer interface.

  • gui is the default.

  • silent runs with no prompts.

  • console is interactive text mode.

• -DEULA=<true|false>: Accept or reject the EULA. Required for silent mode.

• -DHASH_FILE_ZIP=<path>: Path to installer-hash-files-<version>.zip.

  • For 9.3.0.3, 9.4.0.1, or later, the installer requires this file.

• -DUSER_INSTALL_DIR=<dir>: Pentaho root installation directory. Required for silent mode.

• -DRESTORE=<true|false>: Restore a backup before upgrading. Default: false.

• -DBACKUP_ZIP=<file>: Backup ZIP path. Required when restoring.

Using silent mode to upgrade Pentaho products

Silent mode runs without prompts.

Provide all values on the command line.

Upgrade an archive installation

1. Exit any Pentaho products you are running.

2. If you are upgrading Pentaho Server, stop the server.

   • See Stop and start the Pentaho Server and repository.

3. Run the installer:

   • Linux: ./pentaho-update-<version>.bin -i silent -DEULA=true -DUSER_INSTALL_DIR=<dir> -DHASH_FILE_ZIP=installer-hash-files-<version>.zip

   • Windows: pentaho-update-<version>.exe -i silent -DEULA=true -DUSER_INSTALL_DIR=<dir> -DHASH_FILE_ZIP=installer-hash-files-<version>.zip

4. If errors occur, review the installer log.

   • Default log location: <root installation directory>/Pentaho__Installation/logs

5. If you are upgrading Pentaho Server, restart the server.

   • See Stop and start the Pentaho Server and repository.

Upgrade a manual installation

Use silent mode to install upgrade files into an empty folder.

Then copy the files into your existing installation.

1. Exit any Pentaho products you are running.

2. If you are upgrading Pentaho Server, stop the server.

   • See Stop and start the Pentaho Server and repository.

3. Install upgrade files into an empty folder:

   • Linux: ./pentaho-update-<version>.bin -i silent -DEULA=true -DUSER_INSTALL_DIR=/<filepath>/pentaho-upgrade-files/ -DHASH_FILE_ZIP=/<filepath>/installer-hash-files-<version>.zip -DFRESH_INSTALL=true

   • Windows: pentaho-update-<version>.exe -i silent -DEULA=true -DUSER_INSTALL_DIR=/<filepath>/pentaho-upgrade-files/ -DHASH_FILE_ZIP=/<filepath>/installer-hash-files-<version>.zip -DFRESH_INSTALL=true

4. Copy upgrade files into your existing manual installation:

   1. In <root installation folder>/Pentaho__Installation, delete:

      • pentaho.war

      • pentaho-style.war

      • All files and folders in pentaho-server/pentaho-solutions

   2. Copy everything from pentaho-upgrade-files/server/pentaho-server/pentaho-solutions into pentaho-server/pentaho-solutions.

   3. Compress the contents of pentaho-upgrade-files/server/pentaho-server/tomcat/webapps/pentaho into pentaho.war.

   4. Copy pentaho.war into <root installation folder>/Pentaho__Installation.

   5. Compress the contents of pentaho-upgrade-files/server/pentaho-server/tomcat/webapps/pentaho-style into pentaho-style.war.

   6. Copy pentaho-style.war into <root installation folder>/Pentaho__Installation.

5. Start Pentaho Server.

   • See Stop and start the Pentaho Server and repository.

If you plan to test Pentaho Server in a browser, clear the browser cache first.

Exit codes

• 0: Success.

• 1: Success with warnings or non-fatal errors.

• -1: Fatal error.

• 1000: Canceled by the user.

• 1001: Invalid command-line option.

Exit code -1 common causes

• Missing required parameters such as -i, -DUSER_INSTALL_DIR, or -DEULA.

• Silent mode started while a Pentaho product is still running.

• An exception occurred while backing up files.

For more exit codes, see InstallAnywhere exit codes.

Mandatory Quartz upgrade (10.2.0.1 and later)

When upgrading from 10.2.0.0 GA to 10.2.0.1 (or later), initialize the new Quartz database.

Always back up your data first.

If you want to keep your existing Quartz schedules, migrate your current tables.

Pentaho 10.2.0.0 and earlier use Quartz 1.x tables with a QRTZ5_ prefix.

Pentaho 10.2.0.1 and later use Quartz 2.x tables with a QRTZ6_ prefix.

Create the QRTZ6_ tables.

You can optionally migrate existing schedules using the migration script.

If you do not complete the Quartz upgrade, Pentaho Server can fail at startup.

You may see this message in catalina.log:

Missing Quartz library database error

Choose your repository database

• Initialize Quartz for PostgreSQL

• Initialize Quartz for MySQL or MariaDB

• Initialize Quartz for Oracle

• Initialize Quartz for MS SQL Server

Initialize Quartz for PostgreSQL

1. Back up your repository database.

2. If Pentaho Server is running, stop it.

   • See Stop and start the Pentaho Server and repository.

3. Confirm PostgreSQL is running.

4. Open <your pentaho directory>/pentaho-server/data/postgresql/create_quartz_postgresql.sql.

5. Update the script for your user, password, and database.

6. Run the script using psql or pgAdmin.

7. Optional: To migrate existing schedules, run <your pentaho directory>/pentaho-server/data/postgresql/migrate_old_quartz_data_postgresql.sql.

8. Restart Pentaho Server.

Initialize Quartz for MySQL or MariaDB

1. Back up your repository database.

2. If Pentaho Server is running, stop it.

   • See Stop and start the Pentaho Server and repository.

3. Confirm MySQL or MariaDB is running.

4. Open <your pentaho directory>/pentaho-server/data/mysql/create_quartz_mysql.sql.

5. Update the script for your user, password, and database.

6. Run the script using MySQL Workbench or a MySQL/MariaDB CLI.

7. Optional: To migrate existing schedules, run <your pentaho directory>/pentaho-server/data/mysql/migrate_old_quartz_data_mysql.sql.

8. Restart Pentaho Server.

Initialize Quartz for Oracle

1. Back up your repository database.

2. If Pentaho Server is running, stop it.

   • See Stop and start the Pentaho Server and repository.

3. Confirm Oracle is running.

4. Open <your pentaho directory>/pentaho-server/data/oracle/create_quartz_ora.sql.

5. Update the script for your user, password, and database.

6. Run the script using SQL*Plus.

7. Optional: To migrate existing schedules, run <your pentaho directory>/pentaho-server/data/oracle/migrate_old_quartz_data_oracle.sql.

8. Restart Pentaho Server.

Initialize Quartz for MS SQL Server

1. Back up your repository database.

2. If Pentaho Server is running, stop it.

   • See Stop and start the Pentaho Server and repository.

3. Confirm SQL Server is running.

4. Open <your pentaho directory>/pentaho-server/data/sqlserver/create_quartz_sqlServer.sql.

5. Update the script for your user, password, and database.

6. Run the script using sqlcmd or SQL Server Management Studio.

7. Optional: To migrate existing schedules, run <your pentaho directory>/pentaho-server/data/sqlserver/migrate_old_quartz_data_sqlserver.sql.

8. Restart Pentaho Server.

Post-upgrade tasks

After you upgrade to 11.0, you may need to perform optional tasks.

Optional tasks

• Apply customizations

• Update the default documentation version link

• Install Ops Mart

• Install drivers for your Hadoop clusters

• Apply your plugins

• Set up password encryption after upgrading

Apply customizations

If you customized items from the default Pentaho setup, merge your customizations into the 11.0 versions.

Use the steps for your installation type:

• Archive installation

• Manual installation

Address customizations to upgraded archive installation

The installer generates postInstallConfigReport.txt.

Location: <root installation directory>/Pentaho__Installation

1. Open postInstallConfigReport.txt.

2. For each item listed in These config files need merged, open both versions:

   • Existing version.

   • .merge.post_upgrade version.

3. Compare the files.

4. Do one of the following:

   1. Keep the existing version and delete the post-upgrade version.

   2. Merge changes into one file and keep the existing filename.

   3. Replace the existing file with the post-upgrade version.

Address customizations to upgraded manual installation

1. Locate the files you backed up before upgrading.

2. Compare your backup files to the current files in pentaho-server/pentaho-solutions.

3. Merge your changes into the current files.

Update the default documentation version link

1. Go to pentaho/server/pentaho-server/pentaho-solutions/system.

2. Open pentaho.xml in a text editor.

3. Update <documentation-url> to the current version.

Example:

<documentation-url>https://help.hitachivantara.com/Documentation/Pentaho/Data_Integration_and_Analytics/11.0</documentation-url>

Install Ops Mart

If you installed Ops Mart as part of a previous 7.x or 8.x upgrade, you do not need to reinstall it.

To install and use DI Ops Mart, see Administer Pentaho Data Integration and Analytics.

Install drivers for your Hadoop clusters

If you use Hadoop clusters, install the drivers for the clusters you want to access.

Drivers are not automatically installed after upgrading.

See Set up Pentaho to connect to a Hadoop cluster.

Apply your plugins

After upgrading, you must re-apply plugins.

For CTools plugins, see Pentaho CTools.

For PDI plugins, see Install Pentaho plugins.

Set up password encryption after upgrading

Encrypt passwords stored as plain text in configuration files.

Do this before you enable password encryption on the upgraded server.

Process summary

1. Modify the Tomcat context.xml file.

2. Update the Jackrabbit repository.xml file.

3. Verify your Quartz properties.

4. Update your Hibernate configuration.

Modify the Tomcat context.xml file

1. If you changed context.xml before upgrading, merge those changes into the 11.0 file.

2. Stop Pentaho Server.

   • See Stop and start the Pentaho Server and repository.

3. Go to pentaho/server/pentaho-server/tomcat/webapps/pentaho/META-INF.

4. Open context.xml.

5. Replace:

   factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"

   With:

   factory="org.pentaho.di.core.database.util.DecryptingDataSourceFactory"

Password encryption requires the 9.1 (or later) version of context.xml.

1. Add a Jackrabbit Resource entry for your database type:

   • PostgreSQL

     <Resource name="jdbc/jackrabbit" auth="Container" type="javax.sql.DataSource" factory="org.pentaho.di.core.database.util.DecryptingDataSourceFactory" maxActive="20" minIdle="0" maxIdle="5" initialSize="0" maxWait="10000" username="jcr_user" password="password" driverClassName="org.postgresql.Driver" url="jdbc:postgresql://localhost:5432/jackrabbit" validationQuery="select 1"/>

   • MySQL

     <Resource name="jdbc/jackrabbit" auth="Container" type="javax.sql.DataSource" factory="org.pentaho.di.core.database.util.DecryptingDataSourceFactory" maxActive="20" minIdle="0" maxIdle="5" initialSize="0" maxWait="10000" username="jcr_user" password="password" driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost:3306/jackrabbit" validationQuery="select 1"/>

   • Oracle

     Replace XE in the URL with your schema name.

     <Resource name="jdbc/jackrabbit" auth="Container" type="javax.sql.DataSource" factory="org.pentaho.di.core.database.util.DecryptingDataSourceFactory" maxActive="20" minIdle="0" maxIdle="5" initialSize="0" maxWait="10000" username="jcr_user" password="password" driverClassName="oracle.jdbc.OracleDriver" url="jdbc:oracle:thin:@localhost:1521/XE" validationQuery="select 1 from dual"/>

   • SQL Server

     <Resource name="jdbc/jackrabbit" auth="Container" type="javax.sql.DataSource" factory="org.pentaho.di.core.database.util.DecryptingDataSourceFactory" maxActive="20" minIdle="0" maxIdle="5" initialSize="0" maxWait="10000" username="jcr_user" password="password" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver" url="jdbc:sqlserver://localhost:1433;DatabaseName=jackrabbit" validationQuery="select 1"/>

2. Save context.xml.

3. Restart the server and confirm there are no errors.

Update the Jackrabbit repository.xml file

1. If you use a repository database other than PostgreSQL:

   1. Go to pentaho/server/pentaho-server/pentaho-solutions/system/jackrabbit.

   2. Open repository.xml.

   3. Comment out database configurations you do not use.

   4. Uncomment the sections for your database.

2. If you customized repository.xml before upgrading, merge your changes into the 11.0 file.

3. Restart the server and confirm there are no errors.

   • See Stop and start the Pentaho Server and repository.

Verify your Quartz properties

1. Stop Pentaho Server.

2. Go to server/pentaho-server/pentaho-solutions/scheduler-plugin/quartz.

3. Open quartz.properties.

4. Verify this line exists:

   org.quartz.dataSource.myDS.jndiURL = Quartz

5. If the line is missing:

   • If you have not customized quartz.properties, add the line.

   • If you customized it, merge your changes into the 11.0 file.

6. Save quartz.properties.

7. Restart the server and confirm there are no errors.

Update your Hibernate configuration

1. Stop Pentaho Server.

2. Go to pentaho/server/pentaho-server/pentaho-solutions/system/hibernate.

3. Update hibernate.cfg.xml:

   • If you have not customized it, replace it with hibernate.cfg.xml.merge.post-upgrade.

   • If you customized it, merge your changes into the 11.0 file.

4. Restart the server and confirm there are no errors.

After these updates, you can use encrypted passwords with Pentaho 11.0.

See Use password encryption with Pentaho.

Service pack information

To find the list of issues resolved in a service pack:

1. Sign in to the Support Portal.

2. In the Pentaho card, select Download.

3. Select your service pack in Downloads.

4. Scroll to the bottom of the page.

5. Locate the <SP version #>-fixes.txt file. Example: SP-9.3.0.4-739-Fixes.txt.

6. Select the file name to view it.