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. But before you start the database, you need to decide what database features you want to enable and how they should work. These features include attributes such as the 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 and other settings are defined in the configuration file, which you specify on the command line when you initialize the root directory for the database on each server.

This chapter explains how to configure the cluster's physical structure and features in the configuration file and how to initialize the root directory and start and stop the database.

3.1. Configuring the Cluster and Database

You specify the cluster configuration and what features to use in the configuration file, which is an XML file that you can create and edit manually. In the simplest case, the configuration file specifies 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 sitesperhost="12"
           kfactor="1"
  />
</deployment>
  • The sitesperhost attribute specifies the number of partitions (or "sites") to create on each server. Set to eight by default, it is possible to optimize the number of sites per host in relation to the number of processors per machine. The optimal number 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 sites per host and K-safety, you can use the configuration 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 configuration file.

Table 3.1. Selecting Database Features in the Configuration 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 one or more external targets, which can be files, another database, or another service. VoltDB provides different export connectors for each protocol. You can configure the type of export for each stream as well as other properties, which are specific to the connector type. For example, the file connector requires a specific type (or format) for the files and a unique identifier called a "nonce".
<export>
  <configuration enabled="true" type="file">
    <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 database schema.
<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 specific paths for each type of service, such as snapshots, command logs, export overflow, etc.
<paths>
   <exportoverflow path="/tmp/overflow" />
   <snapshots path="/opt/archive" />
</paths>