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 files, 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.
You specify the cluster configuration and what features to use in in one or more configuration files. Configuration files are YAML files that you can create and edit manually, where each property is entered on a separate line followed by a colon and the hierarchy of properties is represented by indentation of subproperties. For example, a simple configuration file specifying how many partitions to create on each server and what level of availability (K-safety) to use looks like this:
Documentationdeployment:
cluster:
sitesperhost: 12
kfactor: 1The sitesperhost property 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 property 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.
You will sometimes see YAML properties represented in dot notation. Dot notation presents the
YAML hierarchy with the successive property names separated by periods. For example, kfactor can be more
fully described in dot notation as deployment.cluster.kfactor. Dot notation is used in the
voltadmin get and set commands for operating on individual property values. You will
also see it occasionally in the text of the documentation as a convenient shorthand for deeply nested subproperties.
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.
Table 3.1. Selecting Database Features in the Configuration File
| Feature | Example |
|---|---|
| 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). | deployment:
commandlog:
enabled: true
synchronous: false
frequency:
time: 300
transactions: 1000 |
| 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. | deployment:
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". | deployment:
export:
configuration:
- target: dblog
type: file
property:
- name type
value: csv
- name: nonce
value: dblog |
| 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. | deployment:
security:
enabled: true
users:
user:
- name: admin
password: superman
roles: administrator
- name: mitty
password: thurber
roles: user |
| 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. | deployment:
paths:
exportoverflow:
path: /tmp/overflow
snapshots:
path: opt/archive
|