Special Considerations for Existing 4.x Customers Upgrading to VoltDB 5.x


VoltDB Home » Documentation » Special Considerations for Existing 4.x Customers Upgrading to VoltDB 5.x

Special Considerations for Existing 4.x Customers Upgrading to VoltDB 5.x





To accommodate new features and focus on improved performance and ease of use, a number of changes have been made to the VoltDB product in versions 5.0 and 5.1. Existing customers using previous versions should be aware of the following changes in behavior that will impact their applications.

What's New for VoltDB 5.0

VoltDB 5.0 is a major release. It consolidates many new features including additional SQL and SQL functions support, integration with Hadoop through the HTTP export connector, as well as JDBC and Apache Kafka import utilities. But the major change in 5.0 is that you no longer need to compile an application catalog before starting the database.

Creating a VoltDB database is now as easy as A, B, C:

  1. Start a database cluster.

  2. Load the classes for any Java stored procedures from a standard Jar file.

  3. Enter your schema DDL using VoltDB's sqlcmd command line utility.

VoltDB supports standard SQL data definition language (DDL) statements for adding, removing, and modifying schema objects on the fly, including CREATE, ALTER, and DROP. You can also declare and partition stored procedures interactively.

Use of interactive DDL makes creating and modifying a VoltDB database as easy as possible without sacrificing any of its leading edge performance and scalability or enterprise-level durability and availability features.

What's New for VoltDB 5.1

VoltDB 5.1 continued the improvements in 5.0. In particular, two features underwent major upgrades to add new capabilities. These upgrades included changes to how the features are configured and operate at runtime.


Database Replication (DR)

Database Replication (DR) has been rewritten to remove any single point of failure, improve performance, and allow new capabilities in the future. New features include:

  • Significantly better performance — rather than a single replication stream, DR now occurs between multiple partitions simultaneously. Also, the new DR uses binary logs of transaction results saving the replica from having to replay the transaction.

  • No single point of failure — By eliminating the DR agent the new DR not only removes a single point of failure, it simplifies DR from an operational perspective.

  • More flexibility — You can now specify which tables you want to replicate rather than having to replicate the entire database. Of course, you can always choose to replicate all of the tables if you like.


Multiple Export Streams

VoltDB now allows you to export data to more than one target at a time. By assigning export tables to individual streams and then configuring each stream separately in the deployment file, you can export data to multiple targets simultaneously.

Special Considerations for Existing 4.x and 3.x Customers

The following sections describe actions you need to perform to take advantage of the new features in 5.0 and 5.1.

Catalogs vs. Interactive DDL

The elimination of the application catalog is a significant change — and simplification — in the database design and deployment process. Support for existing customers is and always will be a key goal for VoltDB. Therefore, use of application catalogs, although deprecated, will continue to be supported for several releases to allow existing customers to adjust their development and production processes.

That being said, migrating from the use of application catalogs to using interactive DDL is a very simple process. With only a few exceptions, existing schema files used to compile application catalogs in previous versions work as-is as input to sqlcmd in version 5.0. Also, existing application catalogs can be used as Jar files for loading stored procedures in VoltDB 5.0. So in many cases, it is possible to use existing resources in the new system without any modifications to source code or configuration files.

If you wish to continue using application catalogs, all you need to do is add the attribute schema="catalog" to the <cluster> tag in the deployment file. That's it.

If existing customers want to migrate to using interactive DDL, in most cases it is simply a case of packaging the Java stored procedure class files into a Jar file using the standard jar command rather than compiling them into an application catalog. The only caveats you should be aware of are the following:



The IMPORT CLASSES statement, which allowed the inclusion of supplemental class files (invoked by stored procedures) into the application catalog, is not supported in interactive mode. So remove any IMPORT CLASSES statements in your schema.

Instead, simply include the supplemental class files in the Jar file with the stored procedures. They are automatically included in the database and made accessible to stored procedures when the Jar file is loaded.


Combine CREATE PROCEDURE and PARTITION PROCEDURE into a single statement for complex procedures

In certain cases, stored procedures must be single-partitioned because the queries the procedure contains are too complex. For example, if a query joins two or more partitioned tables, the procedure itself must be partitioned and the tables must be joined on their partitioning columns. As a consequence, you cannot issue a plain CREATE PROCEDURE statement for that procedure interactively, because procedures are, by default multi-partitioned.

Instead, combine the CREATE PROCEDURE and PARTITION PROCEDURE statements into a single CREATE PROCEDURE statement using the PARTITION ON clause. For example, the following two statements:

CREATE PROCEDURE FROM CLASS acme.procs.GetStoreByRegion;

Can be combined into a single CREATE PROCEDURE statement:

       FROM CLASS acme.procs.GetStoreByRegion;

Database Replication (DR)

For existing DR customers, the new capabilities and the elimination of the DR agent do necessitate some operational changes. Specifically, you must now:

  • Identify the tables participating in DR using the DR TABLE statement in the schema.

  • Configure DR in the deployment files for both the master and the replica clusters.

See the chapter on "Database Replication" in the Using VoltDB manual for details.

Multiple Export Streams

Use of multiple streams does require additional information in the schema and the deployment file. For example, the EXPORT TABLE statement now requires a TO STREAM clause so you can specify the stream to which each export table is directed. However, for backwards compatibility, the old syntax is still supported temporarily to allow customers time to migrate existing applications at their convenience. See the chapter on "Exporting Live Data" in the Using VoltDB manual for details.