Documentation > Deployment > Executing H-Store

Since the H-Store database is used for research purposes, it comes with several OLTP benchmarks built in and ready for execution.

Creating Benchmark Project Jar

The hstore-prepare command will create a project jar file for the target benchmark in H-Store’s base directory. This project file contains the compiled stored procedures and system catalog for the benchmark, as well as the list of nodes in your cluster. For example, the following command will create the project file tpcc.jar:

ant hstore-prepare -Dproject=tpcc

You can use H-Store’s Catalog Viewer Tool to examine the contents of the JAR file, including viewing the query plans that get generated for each of the stored procedures.

By default, hstore-prepare creates a catalog with a cluster of only one host (global.defaulthost) two sites, each with two partitions. You can use a custom specification file that defines the host/site/partition layout of the target cluster and use the hosts option to pass that file when building the catalog:

ant hstore-prepare -Dproject=tpcc -Dhosts=/path/to/cluster.txt

Alternatively, you can specify the cluster configuration directly from the command-line. The hosts option also accepts a semi-colon separated list of triplets. Each triplet is formatted as HOSTNAME:SITE#:PARTITION#. The PARTITION# may be either a single partition number, a comma-separate listed of partition numbers, or a range of partition numbers. For example, the following command will create a cluster where host0.csail.mit.edu will execute with HStoreSite #0 that manages partitions #0, #1, #2, and #3, while host1.csail.mit.edu will execute HStoreSite #1 that manages partitions #4, #5, #6, and #7:

ant hstore-prepare -Dproject=tpcc -Dhosts="host0.csail.mit.edu:0:0-3;host1.csail.mit.edu:1:4,5,6,7"

You can use the catalog-info command to view the cluster configuration for the target benchmark jar file:

ant catalog-info -Dproject=tpcc
 Catalog File:    tpcc.jar
 # of Hosts:      2
 # of Sites:      2
 # of Partitions: 8
 ----------------------------------------------------------------------
 Cluster Information:
 
 [00] HOST host0.csail.mit.edu ┃ [01] HOST host1.csail.mit.edu
      └ SITE H00: [0, 1, 2, 3] ┃      └ SITE H01: [4, 5, 6, 7]

Executing Benchmark

ant hstore-benchmark -Dproject=$BENCHMARK

Executing Single Transactions

To execute transactions by one-by-one (rather than using the built-in BenchmarkController), you can use the hstore-invoke command. In this example, we first start an H-Store cluster using the hstore-benchmark but pass the noexecute option to prevent it from executing the full benchmark workload and the noshutdown option to keep the system online after the loading phase is complete:

ant hstore-benchmark -Dproject=$BENCHMARK -Dnoexecute=true -Dnoshutdown=true

You will get a message at the end that says that the H-Store database cluster will remain online until it receives a kill signal (SIGINT or higher). You can now execute hstore-invoke to execute transactions individually. This command will connect to a random HStoreSite in the cluster and execute a new transaction. The proc option is the name of the procedure that you want to invoke and the params are a comma-separated list of parameters used for that transaction request. These parameters will be cast according to the benchmark’s catalog information for that procedure.

For example, to execute the GetAccessData procedure from the TM1 benchmark, we can execute the following command. Note that the string parameters should be enclosed in quotation marks:

ant hstore-invoke -Dproject=tm1 -Dproc=GetAccessData -Dparam0=100 -Dparam1=1

The raw output from H-Store node will be printed out:

GetAccessData Txn #1027476228166123520 - Status OK
 [00]:  header size: 43
        status code: -128 column count: 4
        cols (DATA1:SMALLINT), (DATA2:SMALLINT), (DATA3:STRING), (DATA4:STRING), 
        rows -
          147, 161, UHJ, JUETN,

Command-line Options

Name Default Value Description
noexecute false Do not start the clients and execute the workload portion of a benchmark.
noshutdown false Do not stop the H-Store database cluster. The BenchmarkController will wait until it is interrupted before stopping all the HStoreSites. You will want to disable the site.status_kill_if_hung configuration option to ensure that the database stays online even there is no work to execute.
nodataload false Disable loading testing data. Only execute benchmark workload
trace null To enable transaction traces, provide a file path with this parameter to specify where H-Store will write out trace logs.