VoltDB Home » Documentation » Using VoltDB


@UpdateApplicationCatalog — Reconfigures the database by replacing the application catalog and/or deployment configuration.


@UpdateApplicationCatalog byte[] catalog, String deployment


The @UpdateApplicationCatalog system procedure lets you modify the configuration of a running database without having to shutdown and restart.


The @UpdateApplicationCatalog system procedure is primarily for updating the deployment configuration. Updating an application catalog is only supported for databases that were started from a catalog and with the deployment setting schema="catalog". In general, updating the database schema interactively is recommended and use of application catalogs is being phased out.

@UpdateApplicationCatalog supports the following changes to the database:

  • Add, remove, or modify stored procedures

  • Add, remove, or modify database tables and columns

  • Add, remove, or modify indexes (except where new constraints are introduced)

  • Add or remove views and export-only tables

  • Modify the security permissions in the database schema

@UpdateApplicationCatalog supports the following changes to the deployment file:

  • Modify the security settings in the database configuration

  • Modify the settings for automated snapshots (whether they are enabled or not, their frequency, location, prefix, and number retained)

  • Modify the export settings

In general, you can make any changes to the database schema as long as there is no data in the tables. However, if there is data in a table, the following changes are not allowed:

  • Changing the partitioning of the table

  • Changing columns to NOT NULL

  • Reducing the datatype size of a column (for example, from INTEGER to SMALLINT) or changing to an incompatible datatype (for example, from VARCHAR to INTEGER)

  • Adding or broadening constraints, such as indexes and primary keys, that could conflict with existing data in the table

The arguments to the system procedure are a byte array containing the contents of the new catalog jar and a string containing the contents of the deployment file. That is, you pass the actual contents of the catalog and deployment files, using a byte array for the binary catalog and a string for the text deployment file. You can use null for either argument to change just the catalog or the deployment.

The new catalog and the deployment file must not contain any changes other than the allowed modifications listed above. Currently, if there are any other changes from the original catalog and deployment file (such as changes to the export configuration or to the configuration of the cluster), the procedure returns an error indicating that an incompatible change has been found.

If you call @UpdateApplicationCatalog on a master database while database replication (DR) is active, the DR process automatically communicates any changes to the application catalog to the replica database to keep the two databases in sync. However, any changes to the deployment file apply to the master database only. To change the deployment settings on a replica database, you must stop and restart the replica (and database replication) using an updated deployment file.

To simplify the process of encoding the catalog contents, the Java client interface includes two helper methods (one synchronous and one asynchronous) to encode the files and issue the stored procedure request:

ClientResponse client.updateApplicationCatalog( File catalog-file, File deployment-file)

ClientResponse client.updateApplicationCatalog( clientCallback callback, File catalog-file, File deployment-file)

Similarly, the sqlcmd utility interprets both arguments as filenames.


The following example uses sqlcmd to update the application catalog using the files mycatalog.jar and mydeploy.xml:

$ sqlcmd
1> exec @UpdateApplicationCatalog mycatalog.jar, mydeploy.xml;

An alternative is to use the voltadmin update command. In which case, the following command performs the same function as the preceding sqlcmd example:

$ voltadmin update mycatalog.jar mydeploy.xml

The following program example uses the @UpdateApplicationCatalog procedure to update the current database catalog, using the catalog at project/newcatalog.jar and configuration file at project/production.xml.

String newcat = "project/newcatalog.jar";
String newdeploy = "project/production.xml";

try {
   File file = new File(newcat);
   FileInputStream fin = new FileInputStream(file);
   byte[] catalog = new byte[(int)file.length()];
   file  = new File(newdeploy);
   fin = new FileInputStream(file);
   byte[] deploybytes = new byte[(int)file.length()];
   String deployment = new String(deploybytes, "UTF-8");
   client.callProcedure("@UpdateApplicationCatalog",catalog, deployment);
catch (Exception e) { e.printStackTrace(); }

The following example uses the synchronous helper method to perform the same operation.

String newcat = "project/newcatalog.jar";
String newdeploy = "project/production.xml";
try {
   client.updateApplicationCatalog(new File(newcat), new File(newdeploy));
catch (Exception e) { e.printStackTrace(); }