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.<\/p>\n
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<\/a>, while the C++ source code files are in src\/ee\/catalog<\/a>. Note that the catalog is local to each HStoreSite<\/tt>. 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.<\/p>\n 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<\/a>. In this file, there are several “catalog objects” defined, each with one or more fields. <\/p>\n After updating the schema specification, you can build and install the update source code files using the following commands:<\/p>\n 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<\/a>:<\/p>\n The begin<\/b><\/tt> and end<\/b><\/tt> 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<\/a><\/b> name<\/b> description<\/b>><\/tt>.<\/p>\n When you invoke catalog.py<\/tt><\/a>, this will create the corresponding Java and C++ files in src\/catgen\/out<\/tt>. The install.py<\/tt><\/a> command will then copy these files into the proper src<\/tt> directories. <\/p>\n 2013-03-14 Update:<\/B>Catalog Schema<\/h2>\n
\r\n$ cd src\/catgen\r\n$ python .\/catalog.py\r\n$ python .\/install.py<\/pre>\n
Adding a New Catalog Object:<\/h3>\n
\r\nbegin<\/b> ConfigData \"Description of this object\"\r\n int<\/b> id \"The unique identifier of this object\"\r\n string<\/b> name \"The unique name of this object\"\r\n bool<\/b> flag \"Some boolean attribute for this object\"\r\nend<\/b><\/pre>\n
\nThe H-Store’s build script helper (build.py<\/tt><\/a>) will now automatically pick up any new catalog object added to spec.txt<\/a> 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:<\/p>\n$ ant clean-all build<\/tt><\/pre>\n
\n
\n Type<\/th>\n Syntax<\/th>\n Description<\/th>\n<\/tr>\n \n Integer<\/th>\n int<\/tt><\/td>\n Primitive integer field. Default value is -1.<\/td>\n<\/tr>\n \n String<\/th>\n string<\/tt><\/td>\n Primitive String field. Default value is null.<\/td>\n<\/tr>\n \n Boolean<\/th>\n boolean<\/tt><\/td>\n Primitive boolean field. Default value is false.<\/td>\n<\/tr>\n \n List<\/th>\n <CatalogType>*<\/tt><\/td>\n This generates an unordered CatalogMap<\/tt> where each CatalogType<\/tt> element is uniquely identifiable by their name. The map is empty by default.<\/td>\n<\/tr>\n \n Reference<\/th>\n <CatalogType>?<\/tt><\/td>\n This generates a pointer to another CatalogType<\/tt> in the catalog. The reference is null by default.<\/td>\n<\/tr>\n<\/table>\n