Running the VoltDB Example Applications

TL;DR In the download tarball, look at the apps in /examples. Each example has a run.sh script. Calling ./run.sh server will start the VoltDB database. In a separate terminal, ./run.sh client will run the example application against the server.

VoltDB comes with four example applications that demonstrate the capabilities and performance of VoltDB:

Voltcache — demonstrates how to use VoltDB as an in-memory cache. Caches, such as memcached, are a popular technique to provide rapid access to the most frequently used content from a larger, slower database. They improve performance on read access to popular content. However, caches do little to improve write performance. Using VoltDB as a cache provides improvement to both read and write performance, while adding transactional consistency and durability.

Voltkv — demonstrates how to create a Key-Value Store using VoltDB. Key-Value Stores are popular for web applications because of their simplicity, performance, and scalability. Using VoltDB to create a Key-Value Store adds transactions, durability, and automatic partitioning without sacrificing the other characteristics.

Voter — simulates a telephone voting application, similar to what you might find associated with a TV talent show or other popularity contest. The Voter application comes with client applications written to several alternate VoltDB interfaces, including JDBC and JSON.

JSON Sessions — demonstrates how to create a flexible schema through use of JSON-encoded VARCHAR columns and the JSON FIELD() function. The JSON sessions application simulates user tracking, where logins from multiple sites are tracked in a single user session table. All sessions have common fields such as username and global session id. At the same time, session-specific data is stored in a single VARCHAR column as JSON data.

The example applications are packaged with the software. After installing VoltDB, you can find the examples in the examples folder. For instance, if you install VoltDB in the folder /opt/voltdb, the examples are in the folder /opt/voltdb/examples. If you install VoltDB locally in your account’s $HOME directory, the examples are in the folder $HOME/voltdb-n.n.nn/examples where n.n.nn is the version number of VoltDB.

All examples include a shell script (run.sh) for building and running the server and a client in the default configuration. Additionally, each example folder contains a README that provides specifics about the application, configuration options, and how to run that application.

Building and Running the Example Applications

The examples come with a shell script to automate the building and running of the application. To build an example, set default to the subdirectory for that example and execute the run.sh script using the argument catalog. For example, the following commands build the voter example, assuming you start from the examples folder:

$ cd voter
$ ./run.sh catalog

Once you build the example, you can run it using the script argument server and client. Note that there are two separate processes that you need to run. Start the server process first, using the ./run.sh server command, then open a new terminal window and use the ./run.sh client command to start the client application.

The server, as its name implies, acts as the database server. The client performs the application logic and displays any messages appropriate to the application. (Note that using the shell script without an argument both compiles the application catalog and starts the server.)

Running the Example Applications on a Cluster

Often the next step after seeing that you can run the sample applications on your local machine is to move to a cluster to fully experience the scalable nature of VoltDB performance. This is also easy to do.

To run a VoltDB database on a cluster, you run the server process on all nodes of the cluster making only three changes to the startup procedure:

  1. Specify the number of nodes in the cluster deployment.xml file by changing the hostcount attribute from “1″ to the number of servers you plan to use. For example, assuming you plan on using three nodes (ServerA, ServerB, and ServerC), change the deployment file:

  2. Select one of the nodes as the “host” and specify its address on the command line when starting each of the server processes. Note that all nodes specify the same host. So, if we select ServerA as the host from our previous example, you include host ServerA in the command line when starting all three nodes. You can do this by editing the run.sh script that comes with the sample application and changing the definition of the environment variable LEADER at the beginning of the file, like so:
    VOLTDB="../../bin/voltdb"
    VOLTCOMPILER="../../bin/voltcompiler"
    LICENSE="../../voltdb/license.xml"
    LEADER="ServerA"
    
  3. Finally, change the run.sh so the client application makes connections to all of the nodes in the cluster rather than just one. This helps maximize the throughput by avoiding any network bottlenecks. You specify the nodes to connect to as an argument to the client application. Edit the run.sh, then find and replace all references to the –servers argument with a list of server nodes. For example:
    --display-interval=5 \
    --duration=120 \
    --servers=ServerA,ServerB,ServerC \
    --port=21212 \
    --pool-size=100000 \
    

Using the Example Applications to Learn VoltDB

The examples can be very helpful in learning how to develop applications in VoltDB. In particular:

  • Performance — The primary focus of VoltDB is on best-in-class throughput performance. All of the samples in the examples folder are designed to demonstrate outstanding performance. These samples use convenience classes and methods to produce an application that integrates benchmarking and automated throttling, which helps optimize throughput and latency. See the README file for each application for additional information on running the application in different configurations.
  • Build Process — The run.sh file for each example shows how the application is constructed from its various parts. If you plan on using shell scripts to build your applications, you can use the examples as a template for writing your own script file.
  • Sample Code — Each example comes complete with source code for the stored procedures, client application, database schema, and project definition file. In addition to the example applications, the doc/tutorials folder contains source code for other examples (Hello World and Auction) that demonstrate use of the basic VoltDB Java API.