Archive
Archive
As new versions of VoltDB become available, you will want to upgrade the VoltDB software on your database cluster. The simplest approach for upgrading recent versions of VoltDB — V6.8 or later — is to perform an orderly shutdown saving a final snapshot, upgrade the software on all servers, then re-start the database. (If you are upgrading from earlier versions of the software, you can still upgrade using a snapshot. But you will need to perform the save and restore operations manually.)
However, upgrading using snapshots involves downtime while the software is being updated. Two alternatives for upgrading VoltDB without downtime are in-service upgrades — upgrading nodes of the cluster one at a time — and using cross data center replication (XDCR) to upgrade clusters.
An in-service upgrade (a separately licensable feature of VoltDB) lets you upgrade a single running cluster by removing individual nodes, upgrading the VoltDB software, then rejoining the node to the cluster. The cluster continues to process transactions throughout the upgrade process, During the upgrade, the cluster operates as the older version software. Once all of the nodes are upgraded, the cluster transitions to the new version.
Using cross data center replication (XDCR), it is possible to use two or more clusters to perform an online upgrade, where there is no downtime and the database is accessible throughout the upgrade operation. If two or more clusters are already active participants in an XDCR environment, you can shutdown and upgrade the clusters, one at a time, to perform the upgrade leaving at least one cluster available at all times.
The following sections describe four approaches to upgrading existing VoltDB installations, starting with how to replace the software itself:
Updating the VoltDB software is very simple. However, you must make sure you perform this step at the right stage in the upgrade process, as described in the following sections. The product comes as a .tar.gz file. When the time comes to upgrade the software, you unpack the tar file and move the resulting folder to replace your current installation. For example, if you have the VoltDB software installed as /var/voltdb, the software installation looks like the following, where you delete the previous version and replace it with the new one:
$ tar -zxvf voltdb-ent-n.n.n-xxxx.tar.gz -C /var $ cd /var $ rm -vr voltdb $ mv voltdb-ent-n.n.n-xxxx voltdb
Remember, when upgrading an existing installation with a running database, you need to upgrade both the software and the database itself. Which means you must make sure you perform the update steps in the correct order. The following sections explain the different options for updating existing installations, including at what stage in the process you should replace the software.
Upgrading the VoltDB software on a single database cluster is easy. All you need to do is perform an orderly shutdown saving a final snapshot, upgrade the VoltDB software on all servers in the cluster, then restart the database. The steps to perform this procedure are:
Shutdown the database and save a final snapshot (voltadmin shutdown --save).
Upgrade the VoltDB software on all cluster nodes (instructions).
Restart the database (voltdb start).
This process works for any recent (V6.8 or later) release of VoltDB.
To upgrade older versions of VoltDB software (prior to V6.8), you must perform the save and restore operations manually. The steps when upgrading from older versions of VoltDB are:
Place the database in admin mode (voltadmin pause).
Perform a manual snapshot of the database (voltadmin save --blocking).
Shutdown the database (voltadmin shutdown).
Upgrade the VoltDB software on all cluster nodes (instructions).
Re-initialize the root directory on all nodes (voltdb init --force).
Start a new database in admin mode (voltdb start --pause).
Restore the snapshot created in Step #2 (voltadmin restore).
Return the database to normal operations (voltadmin resume).
Normally, when upgrading the VoltDB software, you must shutdown the cluster (for example, with the voltadmin shutdown --save command) and restart the entire cluster using the new software. Downtime can be avoided by performing an in-service upgrade. An in-service upgrade allows a K-safe cluster to be upgraded one node at a time, rather than the entire cluster all at once. This means the cluster, and the business processes it supports, remain available throughout the upgrade procedure.
The requirements for performing an in-service upgrade are:
The cluster has the appropriate license for VoltDB that includes the In-Service Upgrade feature.
The cluster must be K-safe. That is, the cluster has a K-safety factor of one or more. This is required so individual nodes can be stopped without crashing the cluster.
The cluster must be running VoltDB V13.1.0 or later.
The new version falls within the parameters allowed by in-service upgrades, as described in Section 4.4.4.1, “The Scope of In-Service Upgrades”.
To perform an in-service upgrade on bare metal servers, you upgrade the VoltDB software on each node consecutively. Specifically:
Stop one of the cluster nodes, using the voltadmin stop node command
Once the server process stops, replace the VoltDB software with the new version.
Restart the node using the voltdb start command, specifying one or more of the other nodes in the cluster as hosts.
Once the rejoin process is finished and the cluster is complete, repeat the process for the next node until all nodes are upgraded.
During the upgrade process, you can determine which nodes have been updated using the @SystemInformation system procedure with the OVERVIEW selector and looking for the VERSION keyword. For example, in the following command output, the first column is the host ID and the last column is the currently installed software version for that host. Once all hosts report using the upgraded software version, the upgrade is complete.
V13.x Documentation$ echo "exec @SystemInformation overview" | sqlcmd | grep VERSION
2 VERSION 13.1.2
1 VERSION 13.1.2
0 VERSION 13.1.3 Until the upgrade process is complete, all nodes in the cluster maintain the functionality of the lower version, even for those nodes that have already upgraded to the higher version software. Once the upgrade is complete and all nodes are running on the newer version, the cluster switches to operating with the higher version functionality. In other words, if the new software contains any new function or behavior, that feature will not be accessible until the entire in-service upgrade process is complete.
If the upgrade fails for any reason, or you choose to stop the upgrade midway, you can revert to the original version by reversing the process: removing a node that has been upgraded, replace the VoltDB software with the original version, rejoin the node and repeat for all nodes that were upgraded. Once the upgrade process is complete, the in-service upgrade is over. At which point, you can longer return to the previous version through an in-service upgrade and must perform a full cluster restart to downgrade.
There are limits to which software versions can use in-service upgrades. The following table describes the rules for which releases can be upgraded with an in-service upgrade and which releases cannot.
You can upgrade between any two patch releases. That is, any two releases where only the third and final number of the version identifier changes. For example, upgrading from 13.1.1 to 13.1.4.
You can also use in-service upgrades to upgrade between two consecutive minor releases. That is where the second number in the version identifier differ. For example, you can upgrade from V13.2.0 to V13.3.0. You can also upgrade between any patch releases within those minor releases. For example, upgrading from V13.2.3 to V13.3.0.
You cannot use in-service upgrades to upgrade more than one minor version at a time. In other words, you can upgrade from V13.2.0 to V13.3.0 but you cannot perform an in-service upgrade from V13.2.0 to V13.4.0. To transition across multiple minor releases your options are to perform consecutive in-service upgrades (for example, from V13.2.0 to V13.3.0, then from V13.3.0 to V13.4.0) or to perform a regular upgrade where all cluster nodes are upgrading at one time.
You cannot use in-service upgrades between major versions of VoltDB. That is, where the first number in the version identifier is different. For example, you must perform a full cluster upgrade when migrating from V13.x.x to V14.0.0 or later.
It is also possible to upgrade the VoltDB software using cross data center replication (XDCR), by simply shutting down, upgrading, and then re-initalizing each cluster, one at a time. This process requires no downtime, assuming your client applications are already designed to switch between the active clusters.
Use of XDCR for upgrading the VoltDB software is easiest if you are already using XDCR because it does not require any additional hardware or reconfiguration. The following instructions assume that is the case. Of course, you could also create a new cluster and establish XDCR replication between the old and new clusters just for the purpose of upgrading VoltDB. The steps for the upgrade outlined in the following sections are the same. But first you must establish the cross data center replication between the two (or more) clusters. See the chapter on Database Replication in the Using VoltDB manual for instructions on completing this initial step.
Once you have two clusters actively replicating data with XCDCR (let's call them clusters A and B), the steps for upgrading the VoltDB software on the clusters is as follows:
Pause and shutdown cluster A (voltadmin pause --wait and shutdown).
Clear the DR state on cluster B (voltadmin dr reset).
Update the VoltDB software on cluster A.
Start a new database instance on A, making sure to use the old deployment file so the XDCR connections are configured properly (voltdb init --force and voltdb start).
Load the schema on Cluster A so replication starts.
Once the two clusters are synchronized, repeat steps 1 through 4 for cluster B.
Note that since you are upgrading the software, you must create a new instance after the upgrade (step #3). When upgrading the software, you cannot recover the database using just the voltdb start command; you must use voltdb init --force first to create a new instance and then reload the existing data from the running cluster B.
Also, be sure all data has been copied to the upgraded cluster A after step #4 and before
proceeding to upgrade the second cluster. You can do this by checking the @Statistics system procedure selector DRCONSUMER
on cluster A. Once the DRCONSUMER statistics State column changes to "RECEIVE", you know the two
clusters are properly synchronized and you can proceed to step #5.
In extreme cases, you may decide after performing the upgrade that you do not want to use the latest version of VoltDB. If this happens, it is possible to fall back to the previous version of VoltDB.
To "downgrade" from a new version back to the previous version, follow the steps outlined in Section 4.4.5, “Performing an Online Upgrade Using Multiple XDCR Clusters” except rather than upgrading to the new version in Step #2, reinstall the older version of VoltDB. This process is valid as long as you have not modified the schema or deployment to use any new or changed features introduced in the new version.
The section describing the upgrade process for active XDCR explains how to fall back to the previous version of VoltDB in case of emergency. This section explains how to fall back, or downgrade, when using the standard save and restore process described in Section 4.4.2, “Upgrading VoltDB Using Save and Restore”.
The following process works if you are reverting between two recent versions of VoltDB and you do not use any new features between the upgrade and the downgrade. There are no guarantees an attempt to downgrade will succeed if the two software versions are more than one major version apart or if you utilize a new feature from the higher version software prior to downgrading.
With those caveats, the most reliable way to fall back to a previous VoltDB version is:
Extract the database schema and stored procedure classes
Pause the database, save a snapshot, and shutdown
Re-install the previous version of VoltDB
Initialize a new database root directory, using the extracted schema and classes
Start the new database instance (in pause mode) using the older version of VoltDB
Manually restore the data from the snapshot created in Step #2
Resume normal operations
This process ensures that only the schema, stored procedures, and data are returned to the older version of the software, and new software features will not impact your restore process. For example:
$ voltdb get schema -D ~/db/new --output=/tmp/mydb.sql $ voltdb get classes -D ~/db/new --output=/tmp/mydb.jar $ voltadmin pause $ voltadmin save /tmp mydata $ voltadmin shutdown [ downgrade VoltDB software . . . ] $ voltdb init -f -D ~/db/old --schema=/tmp/mydb.sql --classes=/top/mydb.jar $ voltdb start -D ~/db/old --pause & $ voltadmin restore /tmp mydata $ voltadmin resume