Performing a Manual Upgrade Using the RPM Distribution

If your operating system is Red Hat Enterprise Linux (RHEL) or CentOS and you installed a previous version of the GemFire XD using the standalone RPM distribution, follow these instructions to perform a manual upgrade to GemFire XD 1.4.

Note: These upgrade instructions require you to shut down the entire distributed system before upgrading individual GemFire XD members. If you want to want to upgrade individual members without shutting down the entire distributed system, follow the instructions in Performing a Rolling Upgrade instead.

When you upgrade GemFire XD from RPM, the new software is installed by default into /opt/pivotal/gemfirexd/GemFireXD_XX where XX corresponds to the version of GemFire XD (for example, GemFireXD_140) that you have installed. No files are overwritten during the upgrade process.

Prerequisites

  • Thoroughly test your development systems with the new version before moving into production.
  • Confirm that your system meets the hardware and software requirements described in Supported Configurations and System Requirements.
  • Review the items listed in Before You Upgrade to understand restrictions or special steps that you might need to take in order to upgrade your system.
  • From the Pivotal GemFire XD download page, select Pivotal GemFire XD. Download the Pivotal GemFire XD RPM appropriate for your RHEL operating system:
    • RHEL 5: pivotal-gemfirexd-1.4.0-50226.el5.noarch.rpm
    • RHEL 6: pivotal-gemfirexd-1.4.0-50226.el6.noarch.rpm

Procedure

  1. Use the shut-down-all and locator commands to stop all GemFire XD 1.3.x members. For example:
    $ gfxd shut-down-all -locators=localhost[10101]
    $ gfxd locator stop -dir=$HOME/locator
    In the sample command, substitute the address, port, and working directory of a locator for your GemFire XD 1.3.x distributed system. Ensure that you stop all locators as well as data stores.
  2. Make backups of all disk store files.
  3. Beginning with machines that host locator members, execute the following rpm command to install the new version of the GemFire XD software. If necessary, use sudo to run the command if you are not logged in as root:
    RHEL 5:
    sudo rpm -Uvh pivotal-gemfirexd-1.4.0-50226.el5.noarch.rpm
    RHEL 6:
    sudo rpm -Uvh pivotal-gemfirexd-1.4.0-50226.el6.noarch.rpm

    The rpm command begins the install process, resolves dependencies, and displays the packages it plans to install.

  4. GemFire XD requires libraries from Pivotal HD Enterprise in order to create HDFS tables or use the MapReduce API. If you installed GemFire XD on the same machine as Pivotal HD, then GemFire XD will automatically locate the required libraries in the default locations:
    • /usr/lib/gphd/hadoop
    • /usr/lib/gphd/hadoop-mapreduce
    • /usr/lib/gphd/hadoop-hdfs/
    If you installed GemFire XD on a machine that does not have a Pivotal HD installation, then you can use the create_hdfsclient_dist.sh script to create a ZIP file of the necessary libraries, which you can then add to the local GemFire XD installation. Follow these steps to use the script:
    1. Copy the create_hdfsclient_dist.sh script to a machine that has a Pivotal HD installation. The script is installed with GemFire XD as /opt/pivotal/gemfirexd/bin/create_hdfsclient_dist.sh.
    2. Execute the create_hdfsclient_dist.sh on the Pivotal HD machine:
      $ ./create_hdfsclient_dist.sh

      The script packages the necessary library files into a ZIP file named gfxd_hdfsclient_dist.zip in the directory where you executed the script.

    3. Copy the gfxd_hdfsclient_dist.zip back to the machine where you installed GemFire XD.
    4. Unzip the gfxd_hdfsclient_dist.zip file's contents into the /opt/pivotal/gemfirexd/ext-lib directory. GemFire XD will now automatically load the necessary Pivotal HD libraries when you start the local member.
  5. Start the GemFire XD member process on the local machine or VM using the new GemFire XD software. This process automatically upgrades the disk store files as necessary.
  6. Repeat these steps as necessary to upgrade other members running on other machines or VMs (locators first, followed by data stores and accessors).
  7. After the distributed system is running, use your modified DDL SQL scripts to recreate stored procedure and listener implementations, using the new com.pivotal.gemfirexd package names. (See Step 1 above.) For example, to srestore the sample DBSynchronizer configuration described in Step 1:
    gfxd> create asynceventlistener testlistener
    > (
    > listenerclass 'com.pivotal.gemfirexd.callbacks.DBSynchronizer' 
    > initparams 
    >   'com.mysql.jdbc.Driver,jdbc:mysql://localhost:3306/gfxddb,SkipIdentityColumns=true,user=gfxduser,secret=25325ffc3345be8888eda8156bd1c313' 
    > )
    > server groups (dbsync);
    gfxd> alter table mytable set asynceventlistener (testlistener);
    gfxd> call sys.start_async_event_listener('TESTLISTENER');

Post-Upgrade Instructions

After you upgrade the individual GemFire XD members, perform these steps if you upgraded from SQLFire 1.1.1 or 1.1.2:
  1. Update all client applications to use the new GemFire XD package names and libraries, then recompile and redeploy those applications:
    • Java package names beginning with com.vmware.sqlfire or com.pivotal.sqlfire were changed to com.pivotal.gemfirexd (see the Javadocs).
    • The ADO.NET Client and application interfaces have changed. The new ADO.NET client installer is provided as part of the GemFire XD ODBC distribution. See ADO.NET API.
    • JDBC thin client and peer client applications must use the new JAR file names, gemfirexd-client.jar and gemfirexd.jar, to access an upgraded distributed system.
  2. The JDBC connection string prefix has changed from jdbc:sqlfire to jdbc:gemfirexd. Update any custom or third-party JDBC clients to use the correct connection string format.
  3. Modify any member startup scripts to use the single -heap-size property instead of -initial-heap and/or -max-heap. The gfxd member startup script no longer support thes -initial-heap and -max-heap properties. See gfxd Launcher Commands.
  4. GemFire XD now uses a JMX Manager node to provide access to a federated MBean architecture. Update your GemFire XD member configuration to use the new architecture, and modify JMX clients as necessary to access the new GemFire XD MBeans. See Using Java Management Extensions (JMX).
  5. The --SQLFIRE-PROPERTIES query hint has changed to --GEMFIREXD-PROPERTIES. Modify any scripts that use the older hint.

What to Do Next

  • Run the product tutorial and examples. See QuickStart Tutorials.
  • Test your development systems with the new version.