Using VoltDB Abstract This book explains how to use VoltDB to design, build, and run high performance appli- cations. V4.3 Using VoltDB V4.3 Copyright © 2008-2014 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, which is 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. This document was generated on May 11, 2014. Table of Contents Preface ............................................................................................................................ xi 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 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. Installing Standard System Packages ............................................................. 6 2.2.3. Building a New VoltDB Distribution Kit ........................................................ 7 2.3. Setting Up Your Environment ................................................................................ 8 2.4. What is Included in the VoltDB Distribution ............................................................. 8 2.5. VoltDB in Action: Running the Sample Applications .................................................. 9 3. Designing Your VoltDB Application ................................................................................ 10 3.1. Designing the Database ........................................................................................ 10 3.1.1. Partitioning Database Tables ...................................................................... 12 3.1.2. Replicating Tables .................................................................................... 13 3.2. Designing the Data Access (Stored Procedures) ........................................................ 13 3.2.1. Writing VoltDB Stored Procedures .............................................................. 14 3.2.2. VoltDB Stored Procedures and Determinism ................................................. 14 3.2.3. The Anatomy of a VoltDB Stored Procedure ................................................. 15 3.2.4. Partitioning Stored Procedures .................................................................... 22 3.3. Designing the Application Logic ........................................................................... 24 3.3.1. Connecting to the VoltDB Database ............................................................. 24 3.3.2. Invoking Stored Procedures ........................................................................ 25 3.3.3. Invoking Stored Procedures Asynchronously ................................................. 26 3.3.4. Closing the Connection ............................................................................. 27 3.4. Handling Errors .................................................................................................. 27 3.4.1. Interpreting Execution Errors ...................................................................... 27 3.4.2. Handling Timeouts ................................................................................... 29 3.4.3. Interpreting Other Errors ............................................................................ 30 4. Simplifying Application Development ............................................................................... 33 4.1. Default Procedures for Partitioned Tables ................................................................ 33 4.2. Shortcut for Defining Simple Stored Procedures ....................................................... 34 4.3. Writing Stored Procedures Inline Using Groovy ....................................................... 35 4.4. Verifying Expected Query Results ......................................................................... 36 5. Building Your VoltDB Application .................................................................................. 38 5.1. Compiling the Client Application and Stored Procedures ............................................ 38 5.2. Declaring the Stored Procedures ............................................................................ 38 5.3. Building the Application Catalog ........................................................................... 39 6. Running Your VoltDB Application .................................................................................. 40 6.1. Defining the Cluster Configuration ........................................................................ 40 6.1.1. Determining How Many Partitions to Use ..................................................... 41 6.1.2. Configuring Paths for Runtime Features ....................................................... 41 6.1.3. Verifying your Hardware Configuration ........................................................ 42 6.2. Starting a VoltDB Database for the First Time ......................................................... 42 iii Using VoltDB 6.2.1. Simplifying Startup on a Cluster ................................................................. 43 6.2.2. How VoltDB Database Startup Works .......................................................... 43 6.3. Starting VoltDB Client Applications ...................................................................... 44 6.4. Shutting Down a VoltDB Database ........................................................................ 44 6.5. Stopping and Restarting a VoltDB Database ............................................................ 45 6.5.1. Save and Restore ..................................................................................... 45 6.5.2. Command Logging and Recovery ................................................................ 45 6.6. Modes of Operation ............................................................................................ 46 6.6.1. Admin Mode ........................................................................................... 46 6.6.2. Starting the Database in Admin Mode .......................................................... 46 7. Updating Your VoltDB Database ..................................................................................... 48 7.1. Planning Your Application Updates ....................................................................... 48 7.2. Updating the Database Schema on a Running Database .............................................. 48 7.2.1. Validating the Updated Catalog .................................................................. 49 7.2.2. Managing the Update Process ..................................................................... 49 7.3. Updating the Database Using Save and Restore ........................................................ 50 7.4. Updating the Hardware Configuration .................................................................... 50 7.4.1. Adding Nodes with Elastic Scaling .............................................................. 51 7.4.2. Configuring How VoltDB Rebalances New Nodes .......................................... 52 8. Security ....................................................................................................................... 53 8.1. How Security Works in VoltDB ............................................................................ 53 8.2. Enabling Authentication and Authorization .............................................................. 53 8.3. Defining Users and Roles ..................................................................................... 53 8.4. Assigning Access to Stored Procedures ................................................................... 54 8.5. Allowing Access to System Procedures, Ad Hoc Queries, and Default Procedures ........... 55 9. Saving & Restoring a VoltDB Database ...........................................................................