Using VoltDB

contents

7.2. Updating the Stored Procedures

Stored procedures, including the security permissions for accessing them, can be updated on the fly for a running VoltDB database. This is done by creating an updated application catalog and deployment file and telling the database process to use the new catalog. You can do this with the @UpdateApplicationCatalog system procedure, or from the shell prompt using the voltadmin update command.

Specifically, the process for updating stored procedures is as follows:

  1. Make the necessary changes to the source code for the stored procedures and the schema.

  2. Recompile the class files and the application catalog as described in Chapter 5, Building Your VoltDB Application.

  3. Use the @UpdateApplicationCatalog system procedure or voltadmin update command to pass the new catalog and deployment file to the cluster.

For example:

$ voltdb compile -o mycatalog.jar  myschema.sql
$ voltadmin update mycatalog.jar mydeployment.xml

7.2.1. Validating the Updated Catalog

When you submit a catalog update, the database nodes do a comparison of the new catalog and deployment configuration with the currently running catalog to ensure that only supported changes are included. If unsupported changes are included, the command returns an error.

Changes that are not currently allowed to a running database include modifying columns within the database schema or changing the configuration of export. To make these more complex changes, you need to save and shutdown the database to change the catalog, as described in Section 7.3, “Updating the Database Schema”.

7.2.2. Managing the Update Process

For most simple changes, updating the application catalog lets you modify the database and its stored procedures without disrupting the normal operations. However, for certain changes, you should be aware of the impact on any client applications that use those procedures. For example, if you remove a stored procedure or change its parameters or permissions while client applications are still actively calling it, you are likely to create an error condition for the calling applications.

In general, the catalog update operates like a transaction. Before the update, the original stored procedure attributes, including permissions, are in effect. After the update completes, the new attributes and permissions are in effect. In either case, any individual call to the stored procedure will run to completion under a consistent set of rules.

For example, if a call to stored procedure A is submitted at approximately the same time as a catalog update that removes the stored procedure, the call to stored procedure A will either complete successfully or return an error indicating that the stored procedure no longer exists. If the stored procedure starts, it will not be interrupted by the catalog update.

In those cases where you need to make changes to a stored procedure that might negatively impact client applications, the following process is recommended:

  1. Perform a catalog update that introduces a new stored procedure (with a new name) that implements the new function. Assuming the original stored procedure is A, let's call its replacement procedure B.

  2. Update all client applications, replacing calls to procedure A with calls to procedure B, making the necessary code changes to accommodate any changed behavior or permissions.

  3. Put the updated client applications into production.

  4. Perform a second catalog update removing stored procedure A, now that all client application calls to the original procedure have been removed.

contents