Documentation > Development > Internal Catalog Schema

The following documentation describes the implementation details of H-Store’s internal system catalog infrastructure. Unlike other existing database management systems that use internal tables to represent their catalogs, H-Store uses an in-memory Java object tree structure.

At a high-level, the internal catalog’s schema defines what information is available about the database (e.g., what tables there are, and columns/indexes those tables have). The actual catalog information is loaded in from the target project JAR file when the DBMS is deployed. The Java source code for the catalog files are in src/frontend/org/voltdb/catalog, while the C++ source code files are in src/ee/catalog. Note that the catalog is local to each HStoreSite. That is, if the system makes changes to the catalog at run time, these updates currently are not automatically transmitted to the other sites in the cluster. Simiarily, any changes to the catalog structure in Java are not automatically propagated down to the C++ catalog.

Catalog Schema

These instructions will discuss how to add new fields to the catalog schema and automatically create/install the Java/C++ class files into the H-Store system. The catalog schema is defined in src/catgen/spec.txt. In this file, there are several “catalog objects” defined, each with one or more fields.

After updating the schema specification, you can build and install the update source code files using the following commands:

$ cd src/catgen
$ python ./catalog.py
$ python ./install.py

Adding a New Catalog Object:

In this example, we will create a new object called “ConfigData” that will contain temporary configuration information about the database. We first must add the “ConfigData” schema definition to spec.txt:

begin ConfigData "Description of this object"
   int id "The unique identifier of this object"
   string name "The unique name of this object"
   bool flag "Some boolean attribute for this object"
end

The begin and end tokens define the boundary for our new object. Any field that listed inside of this block are the field attributes for the object. The syntax for a new field is the triplet <type name description>.

When you invoke catalog.py, this will create the corresponding Java and C++ files in src/catgen/out. The install.py command will then copy these files into the proper src directories.

2013-03-14 Update:
The H-Store’s build script helper (build.py) will now automatically pick up any new catalog object added to spec.txt and include it in the execution engine’s Makefile. You will need to rebuild the entire system to ensure that the proper hooks are put in place:

$ ant clean-all build

Available Field Types: