Versions Compared

Old Version 54

changes.mady.by.user Chris Welford

Saved on

compared with

New Version Current

changes.mady.by.user Junaid Javed

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This page is for system administrators who are upgrading an existing PhixFlow instance from one release to another. This page explains the standard steps that you should always follow.

Warning

Some releases contain special instructions.

When planning an upgrade, please check the special instructions for each intermediate release and follow the additional steps as indicated.

Planning your Upgrade
Anchor
preparation
preparation

Check Supported Versions and Special Instructions

Please read the System Requirements and Compatibility page. Check for any special upgrade instructions between your current and target versions of PhixFlow.

Ensure that your versions of:

  • the database
  • Tomcat
  • Java

are supported in the planned upgrade.


Panel
borderColor#7da054
titleColorwhite
titleBGColor#7da054
borderStylesolid
titleSections on this page

Table of Contents
maxLevel3
indent12px
stylenone



Note

If any of these items need updating, please contact your IT team several weeks in advance of the planned upgrade.

Check Java and Database Connectors

If Java needs upgrading, you must verify that any JDBC connectors you have installed to non-standard databases are still supported. The standard databases supported by PhixFlow are Oracle, MS SQL Server and MySQL/ MariaDBMySQL. The drivers needed to connect to these databases are shipped with PhixFlow, and connections to external databases through PhixFlow data sources are supported by these drivers; see Datasource.

However, if you have connections to external databases other than these - for example, Netezza, Teradata, DB2 - then you will have installed JDBC drivers for these in the folder [tomcat home]/lib. You must check that your current version of each installed driver is compatible with the new version of Java, and if not, obtain a new version of the JDBC driver from the supplier.


How to Upgrade

Step 1  Backup your Database

Ensure that you have a recent, full backup of your PhixFlow database. If you need to rollback (see "Rollback Upgrade" below), your PhixFlow configuration and data will revert to this point.

Tip

We also recommend that you:

  • Review your installation for any remaining uses of the discontinued features mentioned in the release notes. All data related to the use of these features will be removed when PhixFlow is migrated to the new version.

  • Backup all tables except those whose names begin with a 'Zzz'. This backs up the data tables that do not contain stream table data.

Step 2  Review Special Upgrade Instructions

Review the Special Upgrade Instructions for all the intermediate releases between your current version and the version to which you are upgrading. make a note of any that will need to be performed during the upgrade.

Step 3  Stop Tomcat and Delete the Work Directory

  1. Stop the Tomcat service.

    Note

    PhixFlow will not be available to users until the upgrade is complete and you restart Tomcat.


  2. Delete the Tomcat <tomcat base>/work directory. For example in a Linux installation, enter:

    Code Block
    rm -r /opt/tomcat/work


Step

3 

4  Upgrade the Environment

If necessary, upgrade to supported versions of Java, Tomcat and your database: Oracle, SQL Server or MySQL / MariaDBMySQL. See Planning your Upgrade, above.

Remember, if you are Upgrading Tomcat, to restore any JDBC drivers needed for any data sources that use database technologies or versions not supported for PhixFlow's own connections. Make sure that any additional JDBC drivers you use are placed in:

Code Block
[tomcat home]/lib

See also:

Step

4 

5  Unzip the PhixFlow Release

Unzip the PhixFlow release package into a temporary directory.

We will refer to the new PhixFlow release directory as $RELEASE and its corresponding Tomcat directory as $TOMCAT.

Step

5 

6  Install the New Webapp into Tomcat

Move the live PhixFlow installation directory, $TOMCAT/webapps/phixflow, to an archive location.

For example, on Linux: mv $TOMCAT/webapps/phixflow $ARCHIVE/phixflow-<current date>

Copy $RELEASE/webapp/phixflow to $TOMCAT/webapps.

For example, on Linux: cp -r $RELEASE/webapp/phixflow $TOMCAT/webapps/phixflow

Tip

From PhixFlow version 11.0.1, the database schema updates are recorded in the System Console → Audit Summary Tab, with the Action Description starting with “Executing db\upgrade”.


Step 7 Configure the Webapp

The webapp configuration step depends on which version you are upgrading from and to. Please follow the appropriate section below


Expand
titleUpgrading an existing Version 11 or latest system

Upgrading an existing Version 11 or latest system

Automated upgrading of the database schema is now supported. 

In the archive of the live installation, go to the  $TOMCAT/webapps/phixflow/WEB-INF/classes/ directory. Copy the following files into the corresponding directory in the new PhixFlow webapp if they exist: 

  • phixflow.properties
  • local.properties
  • logback.phixflow.xml

Review the Special Upgrade Instructions if there are any recommendations for additional settings. 

Company Logo

phixflow-login.xml 

If you have configured PhixFlow to show your company logo, also copy $ARCHIVE/phixflow-<current date>/gui/images/customerLogo.svg from the archive to the corresponding directory in the new PhixFlow webapp.

Soft Links

If you have configured soft links (also called symlinks or datalinks) between PhixFlow and Tomcat, recreate them. Example scripts are provided below, these examples assume your application is called phixflow. For more details see Configuring Soft Links.

Windows

Code Block
mklink /D C:\app\tomcat\webapps\phixflow\datalink C:\app\phixflow\data\phixflow\datalink

Linux

Code Block
sudo ln -sf /opt/phixflow/data/phixflow/datalink /opt/tomcat/webapps/phixflow/datalink



Expand
titleUpgrading to version 11 or later from pre version 11

Upgrading to version 11 or later from pre version 11

Direct upgrading from version 8.3.18 onwards to version 11.0.1 or later is supported with automatic database schema upgrade. (8.3.24 for 11.0.0).

This process requires migrating the configuration settings from the modified xml settings into the local.properties file. It is assumed a keystore was previously configured.

Review the files in the archive at the following location $ARCHIVE/phixflow-<current date>/WEB-INF/classes/

PropertyPrevious FilePrevious locationNotes

db.url

phixflow-datasource.xml

<property name="url">
    <value>CONNECTION-STRING</value>
</property>

db.usernameKey

phixflow-

secret

datasource.xml

<property name="usernameKey">
    <value>ALIAS-USERNAME</value>
</property>
phixflow-instance.xml 

db.passwordKey

phixflow-datasource.xml

<property name="passwordKey">
    <value>ALIAS-PASSWORD</value>
</property>

logging.file.phixflow.base

logback.xml
  • phixflow-logging.xml 
    • For example on Linux:cp $CV_ARCHIVE/phixflow-<current date>/WEB-INF/classes, to $TOMCAT/webapps/phixflow/WEB-INF/classes
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>logs/${logging.file.phixflow.base}.log</file>
    		Just the base filename (phixflow_webappName) should be populated

    keystore.type

    phixflow-secret.xml

    <property name="keystoreType">
         <value>${keystore.type}</value>
    </property>


    keystore.filephixflow-secret.xml<property name="keystoreFile">
         <value>${keystore.file}</value>
    </property>
    keystore.passwordKeyphixflow-secret.xml

    <property name="keystorePassEnvironmentVariable">
          <value>${keystore.passwordKey}</value>
    </property>

    		If an environment variable was used to store the keystore password

    phixflow-keystore-password

    		phixflow-secret.xml<property name="keystorePass">
          <value>${phixflow-keystore-password}</value>
    </property>    		If the password was stored in the config file.

    If Active Directory was previously used the following configuration settings may need to be configured. Refer to phixflow-secret.xml for existing values.

    Insert excerpt
    Server Configuration Properties
    Server Configuration Properties
    nameLoginActiveDirectory
    nopaneltrue

    If SAML was previously used the following configuration settings may need to be configured. Refer to phixflow-secret.xml for existing values.

    Insert excerpt
    Server Configuration Properties
    Server Configuration Properties
    nameLoginSaml
    nopaneltrue


    Company Logo

    If you have configured PhixFlow to show your company logo, also copy 

    $TOMCAT

    $ARCHIVE/

    webapps/

    phixflow-<current date>/gui/images/customerLogo.svg

    . from

     from the archive to the corresponding directory in the new PhixFlow webapp.

    As part of the recommended PhixFlow installation, soft links are created from $TOMCAT/webapps/phixflow/datalink → [PhixFlow file system]/phixflow/datalink. For further details go to Install the PhixFlow Webapp, but if you have followed the recommended installation, you can use one of the following commands to re-create the link ($WEBAPP is the name of the installed PhixFlow, in most cases just "phixflow")

    Soft Links

    If you have configured soft links (also called symlinks or datalinks) between PhixFlow and Tomcat, recreate them. Example scripts are provided below, these examples assume your application is called phixflow. For more details see Configuring Soft Links.

    Windows

    Code Block
    mklink /D C:\app\tomcat\webapps\phixflow\datalink C:\app\phixflow\data\phixflow\datalink

    Linux

    Code Block
    sudo ln -sf /opt/phixflow/data/phixflow/datalink /opt/tomcat/webapps/phixflow/datalink



    Expand
    titleUpgrading to a version 10 release

    Upgrading to a version 10 release

    In the archive of the live installation, go to the  $TOMCAT/webapps/phixflow/WEB-INF/classes/ directory. Copy the following files into the corresponding directory in the new PhixFlow webapp: 

    • logback.xml
    • phixflow-datasource.xml
    • phixflow-logging.xml
    • phixflow-login.xml
    • phixflow-secret.xml

    For example, on Linux: cp $ARCHIVE/phixflow-<current date>/WEB-INF/classes/phixflow-datasource.xml $TOMCAT/webapps/phixflow/WEB-INF/classes

    Company Logo

    If you have configured PhixFlow to show your company logo, also copy $ARCHIVE/phixflow-<current date>/gui/images/customerLogo.svg from the archive to the corresponding directory in the new PhixFlow webapp.

    Soft Links

    If you have configured soft links (also called symlinks or datalinks) between PhixFlow and Tomcat, recreate them. Example scripts are provided below, these examples assume your application is called phixflow. For more details see Configuring Soft Links.

    Windows

    Code Block
    mklink /D C:\app\tomcat\webapps\
    $WEBAPP
    phixflow\datalink C:\app\phixflow\data\
    $WEBAPP
    phixflow\datalink

    Linux

    Code Block
    sudo ln -sf /opt/phixflow/data/
    $WEBAPP
    phixflow/datalink /opt/tomcat/webapps/
    $WEBAPP
    phixflow/datalink
    Step 6 

    Configure a Keystore

    If you have not already done so, Configure a Keystore and Aliases. Use phixflow-secret.xml to specify the keystore details.

    Step 7  Upgrade

     Upgrade the Database

    Run all migration scripts in sequence from the starting version to this version.


    Note
    titleAbout Migration Warnings

    Some of the scripts can generate warning messages, such as Caution: Changing any part of an object name could break scripts and stored procedures. Generally, warning messages do not indicate a problem. However, if you see any error messages, please contact your PhixFlow support team.

    Example for migrating Oracle

    Code Block
    cd $RELEASE/install/schema/oracle/migration/X.Y
sqlplus myUsername/myPassword @migrate_schema_from_x_y_z_to_X_Y_Z.sql

    Example for migrating SQL Server

    Code Block
    cd $RELEASE/install/schema/sqlserver/migration/X.Y
sqlcmd -S myServer\myInstance -U myUsername -P myPassword -d myDatabase -i migrate_schema_from_x_y_z_to_X_Y_Z.sql

    Example for migrating

    MariaDB (

    MySQL

    ) MariaDB MariaDB

    Code Block
    titleE.g. for

    MySQL users
    cd $RELEASE/install/schema/
    sqlserver
    my_sql/migration/X.Y
mysql -h myServer -u myUsername -p -D myDatabase
source migrate_schema_from_x_y_z_to_X_Y_Z.sql


    Warning
    title
    MySQL Privileges

    Some

    MariaDB

    MySQL PhixFlow migration scripts create or use privileged functions and/or procedures

    , and must have privileges not required by the regular PhixFlow user.

    You can permanently allow functions like this to run by updating a setting in your my.cnf file. See Running non-deterministic functions in MariaDB for details. If you do not make this change, then you must make sure that either:

    Your session has the log_bin_trust_function_creators setting switched on. You can do this

    . If you have followed PhixFlow's recommended installation, running non-deterministic functions will be permanently allowed by a setting (global log_bin_trust_function_creators) in my.cnf (see Install MySQL).

    If you have not permanently set this in my.cnf, you will need to turn this on in the session you are using to perform the upgrade with the command:

    Code Block
    set global log_bin_trust_function_creators = 1;
    Or

    Alternatively, ensure that that the

    migration

    database user performing the upgrade has SUPER privilege.


    Step 8 

    Complete any Special Upgrade Instructions

    Complete the Special Upgrade Instructions for all the intermediate releases between your current version and the version to which you are upgrading.

    Step 9  Restore Soft Links and

    Re-start Tomcat

    If you have configured soft links (also called symlinks or datalinks) between PhixFlow and Tomcat, recreate them; see Configuring Soft Links.

    Restart the Tomcat service .

    Step 10  Republish PhixFlow Stream Data

    After upgrading, PhixFlow may need to republish data to its database. If you have very large streams this can cause slow initial performance. To ensure users are not affected, we recommend that you publish stream data immediately after upgrading.

  • Log on to PhixFlow.
    • Select  Insert excerpt_administration_administrationnopaneltrue → Other Options → Publish Streams.
  • Wait for the pop-up notification that publishing is complete.
    • Note

    If you do not republish altered stream tables, PhixFlow will automatically start publishing data when the first user attempts to use a stream. This may cause slow performance until publishing is complete.

    Your PhixFlow upgrade is now complete and users can access the new version of PhixFlow.

    For details about configuring PhixFlow once it is installed, see Administrationand verify you can login successfully.

    Step 9  Special Upgrade Instructions

    Review all special upgrade instructions have been implemented.