C.5. Converting Existing Catalogs for Use with Interactive DDL

Documentation

VoltDB Home » Documentation » Administrator's Guide
< previoustable of contentsnext >

C.5. Converting Existing Catalogs for Use with Interactive DDL

Although application catalogs are still supported in VoltDB V5.0, use of catalogs is deprecated and support will be removed in a future release. Therefore, we encourage customers to migrate their development and production processes towards use of interactive DDL.

C.5.1. Updating the Database Startup Process

Changing from application catalogs to interactive DDL is a relatively simple process. No changes are needed to the Java stored procedures and more often than not, no changes are needed to the DDL either. There are actually only two changes to your existing procedures:

  • Package stored procedures as a JAR file rather than compile them into an application catalog

    Stored procedures still needed to be packaged into one or more JAR files before you can load them into the database. However, they do not need to be compiled with the schema anymore.

    Note that application catalogs are JAR files. So, if you have an existing application catalog, you can temporarily use that as the stored procedure JAR file — any extraneous content in the catalog will be ignored. However, in the long run it is better to update your processes to use the jar command to create your JAR files when migrating to interactive DDL.

  • Load the stored procedures and schema after the database starts rather than using a catalog when starting

    When using interactive DDL, you create an empty database instance first then, once the database has started, load the stored procedures and schema. The easiest way to do this is using the sqlcmd load classes and file directives, as described in Section 3.3, “Loading the Database Definition”.

C.5.2. When to Modify the Schema DDL

In most cases, your existing schema files are valid input to the sqlcmd utility as is. There are only a few exceptions where you may need to edit the DDL:

  • Replace IMPORT CLASSES with sqlcmd LOAD CLASSES

    If your application catalog contains additional Java helper classes beyond just stored procedures, you must use IMPORT CLASSES statements to tell the VoltDB compiler to add them to the catalog. When using interactive DDL, this is no longer necessary. Simply include the helper classes in the stored procedure JAR file and they will automatically be included when you load the classes using sqlcmd.

  • Merge CREATE PROCEDURE and PARTITION PROCEDURE for single-partitioned procedures with complex queries

    In earlier versions of VoltDB, the statements to define a stored procedure and partition it, CREATE PROCEDURE and PARTITION PROCEDURE, were separate. These two statements are still supported and in most cases work perfectly well. However, there are some cases, with complex SQL queries, where the procedure is not valid as a multi-partition procedure. For example, joining two partitioned tables is not allowed in a multi-partition procedure. However, if the tables are joined on the partition column, they can be in a single-partitioned procedure.

    So, using two statements, the initial CREATE PROCEDURE command may fail to compile interactively. In this case, you can combine the two statements into a single CREATE PROCEDURE using the PARTITION clause. For example, the following statements may fail if the procedure joins two or more partitioned tables:

    CREATE PROCEDURE FROM CLASS acme.procs.GetStoreByRegion;
PARTITION PROCEDURE GetStoreByRegion ON TABLE store COLUMN region;

    Instead, you can combine the two statements into a single CREATE PROCEDURE statement including the partitioning information in a PARTITION ON clause:

    CREATE PROCEDURE PARTITION ON TABLE store COLUMN region
       FROM CLASS acme.procs.GetStoreByRegion;

    The PARTITION ON clause can be used in both the CREATE PROCEDURE AS and CREATE PROCEDURE FROM CLASS statements.

< previoustable of contentsnext >