Skip to main content
Version Data Integration and Analytics
Hitachi Vantara Lumada and Pentaho Documentation

Pentaho upgrade

  1. Last updated
  2. Save as PDF

You can upgrade your Pentaho products from version 9.0.x to version 9.1 using the Pentaho Upgrade Installer. The upgrade installer checks your environment for version 9.0 Pentaho products, creates a backup of these products, then upgrades them to version 9.1. The Pentaho Upgrade Installer works for any Pentaho products you have installed on your server or workstations, including your Pentaho Server and your Pentaho client tools.

NoteYou can use the Pentaho Upgrade Installer to upgrade your Pentaho 9.0 client tools on macOS workstations. However, the Pentaho Server is not supported on macOS.

This upgrade documentation assumes you are an IT administor upgrading from 9.0.x to 9.1 and all your Pentaho products are 9.0.x.

ImportantIf any one of all your Pentaho products is a version earlier than 9.0, the Pentaho Upgrade Installer will not proceed with the upgrade process.

If you need to upgrade your Pentaho products from a version earlier than 9.0, such as 7.1 or higher, you must upgrade your products to version 9.0 then use the Pentaho Upgrade Installer to move from version 9.0 to 9.1. See Upgrade the Pentaho Server for instructions on upgrading from 7.1 or higher to version 9.0.

Parent Topic
Child Topics

Before you begin
Before you can run the Pentaho Upgrade Installer, you must also perform the following tasks:

Procedure

  1. Verify that your system components are current.

    Your system components, such as web browsers or repository databases, must be up-to-date. See the Components Reference to verify the system requirements.
    NoteThe Pentaho Upgrade Installer requires 22 GB of free space to perform the upgrade process.

  2. If you are upgrading an environment that includes the Pentaho Server, stop the server prior to performing backups and installation.

    For instructions, see Start and stop the Pentaho Server for configuration.

  3. Review your customizations.

    During the upgrade process, you can decide which items are not updated to ensure your customizations are not overwritten. See Specify items to include or exclude for details. Then, after upgrading your Pentaho products to 9.1, you must merge your previous customizations into 9.1 versions of the Pentaho configuration files. See the Apply customizations post-upgrade task for instructions.

  4. If you are using Hadoop clusters with your Pentaho products, review and back up your site.xml files.

    The upgrade process does not retain the drivers for your Hadoop clusters. You will need to re-install your drivers after completing the upgrade process. See the Install drivers for your Hadoop clusters post-upgrade task for details.

  5. If you are upgrading the Pentaho Server, verify that no users are logged on to the server.

    As a best practice, perform the upgrade process of the Pentaho Server during off-business hours to minimize the impact to your day-to-day operations.

Next steps

We recommend you review the following updates to understand how our products have changed since 9.0:
Parent Topic

Get the Pentaho upgrade file
The upgrade process includes the platform file that you must download from the Pentaho Customer Support Portal before running the upgrade installer.

Perform the following steps to download the file:

Procedure

  1. On the Customer Portal home page, sign in using the Pentaho support user name and password provided in your Pentaho Welcome Packet.

  2. Click Downloads, then click Pentaho 9.1 GA Release in the 9.x list.

  3. On the bottom of the Pentaho 9.1 GA Release page, browse the folders in the Box widget to find the Utilities and Tools folder.

  4. Depending on your platform, download one of the following files:

    • Linux

      pentaho-update-9.1.0.0-324.bin

    • macOS

      pentaho-update-9.1.0.0-324.zip

    • Windows

      pentaho-update-9.1.0.0-324.exe

    If needed, move the downloaded file to a temporary location on your machine.

  5. If you are upgrading on macOS, unzip the downloaded file.

Results

You are now prepared to begin your 9.0 to 9.1 upgrade.
Parent Topic

Using the Pentaho Upgrade Installer

The Pentaho Upgrade Installer is a step-by-step user interface that opens and guides you through the upgrade process. If you are upgrading in an environment that does not support the display of a graphical interface, then you may want to upgrade in silent mode from a command line. For more information, see Using the Pentaho Upgrade Installer in silent mode.

NoteVerify that the JAVA_HOME environment variable is set to the current version of Java you have installed on your machine before starting the Pentaho Upgrade Installer.

The documentation guides you through the following process:

  1. The Pentaho Upgrade Installer checks your environment to ensure your 9.0 Pentaho products are compatible for upgrade.
  2. In a separate CSV file, you specify items to include or exclude during the upgrade process.
  3. The Pentaho Upgrade Installer creates a backup of your Pentaho 9.0 products in case you prefer to restore them later, then installs the Pentaho 9.1 versions of the products found during the environment check.
Parent Topic
Child Topics

Get started by checking your environment
Perform the following steps to start the Pentaho Upgrade Installer and check your environment.

Procedure

  1. Exit out of any Pentaho products you currently have running.

    If you are upgrading your Pentaho Server, stop the server. For instructions, see Start and stop the Pentaho Server for configuration.

  2. Run the update executable file you downloaded from the Custom Portal. After processing, the Pentaho Upgrade Installer interface opens to the Introduction window.

  3. Click Next.

  4. In the License Terms window, read through the license agreement and select the check box at the bottom of the window to acknowledge the terms, as shown in the following example:

  5. Click Next.

  6. In the Welcome window, select Upgrade to upgrade your Pentaho products and click Next.

    If you would rather restore a backup of an original install before upgrading, select Restore and see Restoring a Pentaho Upgrade Installer backup for instructions.

  7. In the Choose Install Folder window, use Where Would You Like to Install?, Restore Default Folder, or Choose to specify the root directory of your Pentaho installation, then click Next.

Results

The upgrade installer performs an environment check to determine what Pentaho 9.0 products are installed in the root directory you specified and whether your environment is compatible for upgrading to Pentaho 9.1.

For example, if you are upgrading a server, the Environment Check may appear similar to the following sample:

If you are upgrading a workstation, the Environment Check may appear similar to the following sample:

NoteThe Pentaho Upgrade Installer is designed to work for the Pentaho 9.0 products you have installed in a specified root directory and all the related subdirectories. If you have 9.0 installed products in a root directory separate from the one specified, you will also need to apply the Pentaho Upgrade installer to that separate root directory to upgrade those other products. The Pentaho Upgrade Installer is also designed to upgrade any Pentaho product of version 9.0 and above. If you apply the Pentaho Upgrade Installer to a 9.1 installation, the installer still performs the upgrade process on the installed products.
Parent Topic

Specify items to include or exclude
While checking your environment for Pentaho 9.0 products and compatibility, the Pentaho Upgrade Installer generates a CSV file in the <root installation directory>/Pentaho__Installation directory. You must use this file to specify which items in your Pentaho 9.0 distribution to include or exclude from upgrading to version 9.1. Alternatively, you can also use the CSV file to retain 9.0 versions of items that contain customizations you have applied to the default Pentaho setup. After the Pentaho Upgrade Installer has completed the upgrade process, you can download a ZIP file containing 9.1 versions of the items listed in the CSV file and merge your customizations into those 9.1 versions. See Apply customizations for instructions.
NoteCustom directories within the <root installation directory> level of your 9.0 Pentaho distributions are ignored by the Pentaho Upgrade Installer. Custom directories are subdirectories that you created and do not include those subdirectories created by the Pentaho installation)

Perform the following steps to verify the actions specified in the CSV file and adjust as needed:

Procedure

  1. Navigate to the <root installation directory>/Pentaho__Installation directory.

  2. Open the white_list.csv file in an editor application that supports the CSV file type.

  3. Verify the actions specified in the CSV file and adjust as needed for your setup. The CSV file contains the following three comma-separated columns:

    • Item type

      The item can be a script, configuration file, JDBC driver, directory, KTR file, KJB file, or a license file.

    • Update strategy

      One of the following actions to include or exclude the item during the upgrade process:

      • overwrite

        The 9.1 version of the item listed in the CSV file is replaced by the 9.0 version from the backup of the existing Pentaho 9.0 products created during the upgrade process.

      • create

        The 9.1 version of the item listed in the CSV file is created and installed during the upgrade process.

    • File or directory path

      The location and file name (if the item is a file) within your Pentaho distribution where you want to overwrite or create the 9.1 version of the item.

      NoteIf the item you want to include is a directory, specify the directory name without appending a directory separator at the end. For example: directory,data-integration/your-directory-name

  4. Save the CSV file.

Results

The items listed in the CSV file will be included or excluded during the upgrade process depending on any updates you made to the file.
Parent Topic

Back up of your 9.0 Pentaho products and install Pentaho 9.1
Perform the following steps in the Pentaho Upgrade Installer to back up your current installations and apply the new installations:

Procedure

  1. After you verify the items and actions in the CSV file, return to the Pentaho Upgrade installer and click Next to back up your Pentaho 9.0 installation.

    NoteContact Support if your expected Pentaho products do not appear in the list. The Pentaho Upgrade Installer backs up your original version of the Pentaho products if you decide to restore version 9.0 after upgrading to version 9.1. If you decide to restore the backup, see Restoring a Pentaho Upgrade Installer backup for instructions.

  2. After the backup completes to 100% in the Backup window, click Next.

    The Pre-Installation Summary window appears, as shown in the following example:
    NoteIf you cancel the upgrade process after the backup of your environment is created but before the 9.1 installation, this backup will not be used by the Pentaho Upgrade Installer in any future upgrade process. To remove this backup ZIP file, navigate to the ~/.pentaho/backup directory and delete the ZIP file related to the date when the backup was performed.

  3. Verify the information in the pre-installation summary, then click Install.

    If the summary information is not what you expected, use Previous to modify any previous settings.

  4. After the installation and configuration updates complete in the Installing Pentaho window, click Next.

    If errors occur, examine the log files for details on how to resolve the error. Depending on the error, you may need to contact Support for help. The default location of the log file is <root installation directory>/Pentaho__Installation/logs.

  5. In the Install Complete window, click Done to exit the Pentaho Upgrade Installer.

  6. Apply the version 9.1 licenses to your upgraded Pentaho products.

    See Manage Pentaho licenses for instructions.

  7. If you are upgrading your Pentaho Server, restart the Pentaho Server.

Next steps

After you upgrade your Pentaho products, complete these Post-upgrade tasks to verify that your Pentaho configuration is ready to use.
Parent Topic