Description

The @UpdateApplicationCatalog system procedure lets you make modifications to a running database without having to shutdown and restart. @UpdateApplicationCatalog supports the following changes:

When modifying indexes, you can add, remove, or rename non-unique indexes, you can add or remove columns from a non-unique index, and you can rename, add columns to, or remove in its entirety a unique index. The only limitations are that you cannot add a unique index or remove a column from an existing unique index.

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:

Similarly, the sqlcmd utility interprets both arguments as filenames.

Examples

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()];
   fin.read(catalog);
   fin.close();
   file  = new File(newdeploy);
   fin = new FileInputStream(file);
   byte[] deploybytes = new byte[(int)file.length()];
   fin.read(deploybytes);
   fin.close();
   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(); }