Chapter 3. Starting and Stopping the Database

Documentation

VoltDB Home » Documentation » Administrator's Guide

Chapter 3. Starting and Stopping the Database

The fundamental operations for database administration are starting and stopping the database. The one significant difference between VoltDB and other database systems is that you do not start the database management system, or DBMS, separate from the database itself. When you start VoltDB, you start it with a specific database schema, as defined in the application catalog.

You also need to decide what database features you want to configure before starting the database. This includes the size of the cluster, what amount of replication you want to use to increase availability in case of server failure, and what level of durability is required for those cases where the database itself stops. These settings are defined in the deployment file.

This chapter explains how to configure the cluster physical structure and database features in the deployment file and how to start and stop the database.

3.1. Configuring the Cluster and Database

You specify the cluster configuration and what features to use in the deployment file, which is an XML file that you can create and edit manually. In the simplest case, the deployment file specifies how many servers the cluster has initially, how many partitions to create on each server, and what level of availability (K-safety) to use. For example:

<?xml version="1.0"?>
<deployment>
  <cluster hostcount="5"
           sitesperhost="4"
           kfactor="1"
  />
</deployment>
  • The hostcount attribute specifies the number of servers the cluster will start with.

  • The sitesperhost attribute specifies the number of partitions (or "sites") to create on each server. The optimal number of sites per host is affected by the number of processors per machine and is best determined by performance testing against the expected workload. See the chapter on "Benchmarking" in the VoltDB Planning Guide for details.

  • The kfactor attribute specifies the K-safety value to use. The higher the K-safety value, the more node failures the cluster can withstand without affecting database availability. However, increasing the K-safety value increases the number of copies of each unique partition. High availability is a tradeoff between replication to protect against node failure and the number of unique partitions, therefore throughput performance. See the chapter on availability in the Using VoltDB manual for more information on determining an optimal K-safety value.

In addition to the cluster configuration, you can use the deployment file to enable and configure specific database features such as export, command logging, and so on. The following table summarizes some of the key features that are settable in the deployment file.

Table 3.1. Configuring Database Features in the Deployment File

FeatureExample
Command Logging — Command logging provides durability by logging transactions to disk so they can be replayed during a recovery. You can configure the type of command logging (synchronous or asynchronous), the log file size, and the frequency of the logs (in terms of milliseconds or number of transactions).
<commandlog enabled="true"
            synchronous="false">
  <frequency time="300" 
             transactions="1000"/>
</commandlog>
Snapshots — Automatic snapshot provide another form of durability by creating snapshots of the database contents, that can be restored later. You can configure the frequency of the snapshots, the unique file prefix, and how many snapshots are kept at any given time.
<snapshot enabled="true"
          frequency="30m"
          prefix="mydb"
          retain="3" />
Export — Export allows you to write selected records from the database to an external target, which can be files, another database (through JDBC) or a custom export connector. You can configure the type of export as well as other properties, which are specific to each target type. For example, the file target requires a specific type (or format) for the files and a unique identifier called a "nonce".
<export  enabled="true" 
         target="file">
  <configuration>
    <property name="type">csv</property>
    <property name="nonce">mydb</property>
  </configuration>
</export>
Security & Accounts — Security lets you protect your database against unwanted access by requiring all connections authenticate against known usernames and passwords. In the deployment file you can define the user accounts and passwords and what role or roles each user fulfills. Roles define what permissions the account has. Roles are defined in the application catalog.
<security enabled="true"/>
<users>
  <user name="admin" 
        password="superman" 
        roles="dev,ops"/>
  <user name="mitty" 
        password="thurber" 
        roles="user"/>
</users>
File Paths — Paths define where VoltDB writes any files or other disc-based content. You can configure the default root for all files as well as specific paths for each type of service, such as snapshots, command logs, export overflow, etc.
<paths>
   <voltdbroot path="/tmp/vroot" />
   <snapshots path="/opt/archive" />
</paths>

>