If your guest operating system is Red Hat Enterprise Linux (RHEL) and you have
installed a previous version of the product using yum or the Pivotal HD ICM
utility, use the RPM distribution to upgrade GemFire XD. You complete the upgrade procedure
on every virtual and physical machine that runs GemFire XD.
Note: Thoroughly test your development systems with the new version
before moving into production.
When you upgrade GemFire XD from RPM, the new software is installed by default into
where XX corresponds to the version of GemFire XD (for example,
GemFireXD_131) that you have installed. No files are
overwritten during the upgrade process.
- 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:
- RHEL 6:
- If your system uses any stored procedures, listeners, or functions that reference the
SQLFire package names (either com.vmware.sqlfire or
com.pivotal.sqlfire), then you must stop and remove these
objects from the system before you begin the upgrade process. For example, if
you are upgrading from SQLFire and you configured DBSynchronizer using the
implementation, then you must remove this listener implementation before
Perform the following steps for any database objects that use
older SQLFire package names:
- Ensure that you have the DDL commands necessary to recreate the
procedure or listener. Typically these commands are stored in a SQL
script used to create your database schema. For example, an existing
DBSynchronizer might have been created using the
gfxd> create asynceventlistener testlistener
> listenerclass 'com.vmware.sqlfire.callbacks.DBSynchronizer'
> server groups (dbsync);
you do not have the DDL commands readily available, use the
sqlf write-schema-to-sql command to write
the existing schema's DDL commands to a SQL file, and verify
that the necessary commands are present.
- Use SYS.STOP_ASYNC_EVENT_LISTENER to stop any
listener or DBSynchronizer implementation that uses the older API.
gfxd> call sys.stop_async_event_listener('TESTLISTENER');
- Alter any tables that use a stopped listener or DBSynchronizer to
remove the listener from the table. For
gfxd> alter table mytable set asynceventlistener ();
- Use the appropriate DROP command (DROP
PROCEDURE, DROP ASYNCEVENTLISTENER,
DROP FUNCTION) or system procedure
SYS.REMOVE_WRITER) to remove procedure and
listener configurations that use the older API. For
gfxd> drop asynceventlistener testlistener;
- Upgrade your procedure or listener code to use the newer
com.pivotal.gemfirexd package prefixes, and
recompile as necessary. If you are using the built-in DBSynchronizer
implementation, you need only modify the DDL SQL script to specify
the newer implementation in the CREATE
ASYNCEVENTLISTENER command. For
-- Upgraded DBSynchronizer DDL
create asynceventlistener testlistener
server groups (dbsync);
- Continue with the distributed system upgrade before you attempt to
recreate updated procedure or listener implementations.
Note: If you fail to remove a procedure, listener, or function that
uses the older SQLFire API, you will receive a
ClassNotFoundException when you start the upgraded
GemFire XD member. The exception will reference the
com.pivotal.sqlfire package, which is not available in
- Use the shut-down-all
and locator commands to stop all members. For example:
$ sqlf shut-down-all -locators=localhost
$ sqlf locator stop -dir=$HOME/locator
In the sample command, substitute the address, port, and working directory of a
locator for your SQLFire distributed system. Ensure that you stop all locators
as well as data stores.
- Make backups of all disk store files.
- 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:
sudo rpm -Uvh pivotal-gemfirexd-1.3.1-49833.el5.noarch.rpm
sudo rpm -Uvh pivotal-gemfirexd-1.3.1-49833.el6.noarch.rpm
The rpm command begins the install process, resolves
dependencies, and displays the packages it plans to install.
- If you use a startup script or a sqlfire.properties file to
configure the local member at startup, note that the product prefix that is
included in certain member boot properties has changed from
sqlfire. to gemfirexd. Update your script
or properties file to use the gemfirexd. prefix as necessary.
You may also consider renaming sqlfire.properties to
gemfirexd.properties. See Configuration Properties.
- Modify any member startup scripts to use the single -heap-size property
instead of -initial-heap and/or -max-heap.
GemFire XD no longer support thes -initial-heap and
-max-heap properties. See gfxd Launcher Commands.
Note: Although GemFire XD introduces the gfxd utility to
replace the earlier sqlf utility, "sqlf" is still provided
and supported as an optional syntax in this release for convenience.
- 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:
If you installed GemFire XD on a machine that does not have a Pivotal HD
installation, then you can use the
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:
- Copy the create_hdfsclient_dist.sh script to a
machine that has a Pivotal HD installation. The script is installed
with GemFire XD as
- Execute the create_hdfsclient_dist.sh on the
script packages the necessary library files into a ZIP file
named gfxd_hdfsclient_dist.zip in the
directory where you executed the script.
- Copy the gfxd_hdfsclient_dist.zip back to the
machine where you installed GemFire XD.
- Unzip the gfxd_hdfsclient_dist.zip file's
contents into the
GemFire XD will now automatically load the necessary Pivotal HD
libraries when you start the local member.
- 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.
- Repeat these steps as necessary to upgrade other members running on other machines or VMs
(locators first, followed by data stores and accessors).
- 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
gfxd> create asynceventlistener testlistener
> listenerclass 'com.pivotal.gemfirexd.callbacks.DBSynchronizer'
> server groups (dbsync);
gfxd> alter table mytable set asynceventlistener (testlistener);
gfxd> call sys.start_async_event_listener('TESTLISTENER');
After you upgrade the individual GemFire XD members, perform these steps if you
upgraded from SQLFire 1.1.1 or 1.1.2:
- 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.pivotal.sqlfire were changed to
com.pivotal.gemfirexd (see the Javadocs).
- ADO.NET application interfaces were changed to begin with
Pivotal.Data.GemFireXD (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
- The ADO.NET client DLL is now installed using an MSI file. See Installing GemFire XD ADO.NET Components.
- 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
- 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.
- 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).
- 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