Using VoltDB Abstract This book explains how to use VoltDB to design, build, and run high performance applicaons. V7.9 Using VoltDB V7.9 Copyright © 2008-2018 VoltDB, Inc. The text and illustrations in this document are licensed under the terms of the GNU Affero General Public License Version 3 as published by the Free Software Foundation. See the GNU Affero General Public License (http://www.gnu.org/licenses/) for more details. Many of the core VoltDB database features described herein are part of the VoltDB Community Edition, which is licensed under the GNU Affero Public License 3 as published by the Free Software Foundation. Other features are specific to the VoltDB Enterprise Edition and VoltDB Pro, which are distributed by VoltDB, Inc. under a commercial license. Your rights to access and use VoltDB features described herein are defined by the license you received when you acquired the software. VoltDB is a trademark of VoltDB, Inc. VoltDB software is protected by U.S. Patent Nos. 9,600,514 and 9,639,571. Other patents pending. This document was generated on January 02, 2018. Table of Contents About This Book .............................................................................................................. xiii 1. Overview ....................................................................................................................... 1 1.1. What is VoltDB? .................................................................................................. 1 1.2. Who Should Use VoltDB ....................................................................................... 1 1.3. How VoltDB Works .............................................................................................. 2 1.3.1. Partitioning ................................................................................................ 2 1.3.2. Serialized (Single-Threaded) Processing ......................................................... 2 1.3.3. Partitioned vs. Replicated Tables ................................................................... 3 1.3.4. Ease of Scaling to Meet Application Needs ..................................................... 4 1.4. Working with VoltDB Effectively ............................................................................ 4 2. Installing VoltDB ............................................................................................................ 5 2.1. Operating System and Software Requirements ............................................................ 5 2.2. Installing VoltDB .................................................................................................. 6 2.2.1. Upgrading From Older Versions ................................................................... 6 2.2.2. Building a New VoltDB Distribution Kit ........................................................ 7 2.3. Setting Up Your Environment ................................................................................. 7 2.4. What is Included in the VoltDB Distribution ............................................................. 7 2.5. VoltDB in Action: Running the Sample Applications .................................................. 8 3. Starting the Database ....................................................................................................... 9 3.1. Initializing and Starting a VoltDB Database ............................................................... 9 3.2. Initializing and Starting a VoltDB Database on a Cluster ............................................ 10 3.3. Stopping a VoltDB Database ................................................................................. 11 3.4. Saving the Data .................................................................................................. 12 3.5. Restarting a VoltDB Database ............................................................................... 12 3.6. Updating Nodes on the Cluster .............................................................................. 12 3.7. Defining the Cluster Configuration ......................................................................... 13 3.7.1. Determining How Many Sites per Host ......................................................... 14 3.7.2. Configuring Paths for Runtime Features ........................................................ 14 3.7.3. Verifying your Hardware Configuration ........................................................ 15 4. Designing the Database Schema ....................................................................................... 16 4.1. How to Enter DDL Statements .............................................................................. 17 4.2. Creating Tables and Primary Keys ......................................................................... 18 4.3. Analyzing Data Volume and Workload ................................................................... 19 4.4. Partitioning Database Tables ................................................................................. 20 4.4.1. Choosing a Column on which to Partition Table Rows ..................................... 20 4.4.2. Specifying Partitioned Tables ...................................................................... 21 4.4.3. Design Rules for Partitioning Tables ............................................................ 21 4.5. Replicating Database Tables .................................................................................. 21 4.5.1. Choosing Replicated Tables ........................................................................ 22 4.5.2. Specifying Replicated Tables ...................................................................... 22 4.6. Modifying the Schema ......................................................................................... 22 4.6.1. Effects of Schema Changes on Data and Clients ............................................. 23 4.6.2. Viewing the Schema .................................................................................. 24 4.6.3. Modifying Tables ...................................................................................... 24 4.6.4. Adding and Dropping Indexes ..................................................................... 26 4.6.5. Modifying Partitioning for Tables and Stored Procedures ................................. 27 5. Designing Stored Procedures to Access the Database ........................................................... 31 5.1. How Stored Procedures Work ................................................................................ 31 5.1.1. VoltDB Stored Procedures are Transactional .................................................. 31 5.1.2. VoltDB Stored Procedures are Deterministic .................................................. 31 5.2. The Anatomy of a VoltDB Stored Procedure ............................................................ 33 iii Using VoltDB 5.2.1. The Structure of the Stored Procedure .......................................................... 33 5.2.2. Passing Arguments to a Stored Procedure ...................................................... 35 5.2.3. Creating and Executing SQL Queries in Stored Procedures ............................... 36 5.2.4. Interpreting the Results of SQL Queries ........................................................ 37 5.2.5. Returning Results from a Stored Procedure .................................................... 40 5.2.6. Rolling Back a Transaction ......................................................................... 41 5.3. Installing Stored Procedures into the Database .......................................................... 41 5.3.1. Compiling, Packaging, and Loading Stored Procedures .................................... 42 5.3.2. Declaring Stored Procedures in the Schema ................................................... 42 5.3.3. Partitioning Stored Procedures in the Schema ................................................. 43 6. Designing VoltDB Client Applications .............................................................................. 47 6.1. Connecting to the VoltDB Database ....................................................................... 47 6.1.1. Connecting to Multiple Servers ................................................................... 48 6.1.2. Using the Auto-Connecting Client ............................................................... 48 6.2. Invoking Stored Procedures ................................................................................... 49 6.3. Invoking Stored Procedures Asynchronously ............................................................ 49 6.4. Closing the Connection ........................................................................................ 50 6.5. Handling Errors .................................................................................................. 51 6.5.1. Interpreting Execution Errors ...................................................................... 51 6.5.2. Handling Timeouts .................................................................................... 52 6.5.3. Writing a Status Listener to Interpret Other Errors .......................................... 54 6.6. Compiling and Running Client Applications ............................................................. 56 6.6.1. Starting the Client Application .................................................................... 56 6.6.2. Running Clients from Outside the Cluster ..................................................... 56 7. Simplifying Application