@UpdateApplicationCatalog

Documentation

VoltDB Home » Documentation » Using VoltDB

@UpdateApplicationCatalog

@UpdateApplicationCatalog — Reconfigures the database by replacing the configuration file.

Synopsis

@UpdateApplicationCatalog byte[] null, String configuration

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 configuration file. That is, you pass the actual contents of the configuration file as a string. The new 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 configuration 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 configuration-file)

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

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

Examples

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

$ sqlcmd
1> exec @UpdateApplicationCatalog null, myconfig.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 myconfig.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 newconfig = "project/production.xml";
try {
   client.updateApplicationCatalog(null, new File(newconfig));
}
catch (Exception e) { e.printStackTrace(); }