Chapter 3. Starting the Database


VoltDB Home » Documentation » Using VoltDB

Chapter 3. Starting the Database

This chapter describes the procedures for starting and stopping a VoltDB database and includes details about configuring the database. The chapter contains the following sections:

3.1. Initializing and Starting a VoltDB Database

Before you start a VoltDB database, you must initialize the root directory where VoltDB stores its configuration data, logs, and other disk-based information. Once you initialize the root directory, you can start the database. For example, you can accept the defaults for the voltdb init and start commands to initialize and start a new, single-node database suitable for developing and testing a database and application.

$ voltdb init
$ voltdb start

This creates a VoltDB root directory as a subfolder of your current working directory and starts a database with all default options. You only need to initialize the root directory once and can then start and stop the database as often as you like.

$ voltadmin shutdown
$ voltdb start

If you are using command logging, which is enabled by default in the VoltDB Enterprise Edition, VoltDB automatically saves and recovers your database between any stoppage and a restart. If you are not using command logging, you will want to save a snapshot before shutting down. The easiest way to do this is by adding the --save argument to the shutdown command.

The snapshot is automatically restored when the database restarts:

$ voltadmin shutdown --save
$ voltdb start

If you want to create a new database, you can reinitialize the root directory. However, you must use the --force flag if the database has already been used; VoltDB will not clear the root directory of existing data unless you explicitly "force" it to.

$ voltdb init --force
$ voltdb start

Also, you can specify an alternate location for the root directory using the --dir or -D flag. Of course, you must specify the same location for the root directory when both initializing and starting the database. You cannot start a database in a directory that has not been initialized.

$ voltdb init  --dir=~/mydb
$ voltdb start --dir=~/mydb

In most cases, you will want to use additional arguments to configure the server and database options. But the preceding commands are sufficient to get you started in a test environment. The rest of this chapter explains how to use other arguments and how to start, stop, and recover a database when using a cluster.

Finally, when using the VoltDB Enterprise Edition, you must provide a license file when initializing the database. VoltDB looks for the license as a file named license.xml in three possible locations, in the following order:

  1. The current working directory

  2. The directory where the VoltDB image files are installed (usually in the /voltdb subfolder of the installation directory)

  3. The current user's home directory

If the license file is not in any of these locations, you must explicitly identify it when you issue the voltdb init command using the --license or -l flag. For example, the command might be:

$ voltdb init -l /usr/share/voltdb-license.xml

The examples in this manual assume that the license file is in one of the default locations and therefore do not show the --license flag for simplicity's sake.