@UpdateApplicationCatalog

Documentation

VoltDB Home » Documentation » Using VoltDB

@UpdateApplicationCatalog

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

Synopsis

@UpdateApplicationCatalog byte[] null, String deployment

Description

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

Note

The @UpdateApplicationCatalog system procedure originally supported updating a precompiled schema called an application catalog. Application catalogs are no longer supported in favor of interactive DDL statements. However, the first argument is still required and should be sent as a null value. See the voltadmin update command for an easier way to update the configuration from the command line.

The arguments to the system procedure are a null value and a string containing the contents of the deployment file. That is, you pass the actual contents of the deployment file as a string. The new deployment settings must not contain any changes other than the allowed modifications listed in the description of the voltadmin update command. If there are any other changes, the procedure returns an error indicating that an incompatible change has been found.

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

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

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

Similarly, the sqlcmd utility interprets the deployment argument as a filename.

Examples

The following example uses sqlcmd to update the configuration using the deployment file mydeploy.xml:

$ sqlcmd
1> exec @UpdateApplicationCatalog null, 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 mydeploy.xml

The following program example uses the @UpdateApplicationCatalog procedure to update the current database catalog, using the configuration file at project/production.xml with the synchronous helper method.

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