voltdb

Documentation

VoltDB Home » Documentation » Using VoltDB

voltdb

voltdb — Performs management tasks on the current server, such as starting and recovering the database.

Synopsis

voltdb collect [args] voltdbroot-directory

voltdb mask [args] source-deployment-file [new-deployment-file]

voltdb create [args]

voltdb recover [args]

voltdb add [args]

voltdb rejoin [args]

Description

The voltdb command performs local management functions on the current system, including:

  • Starting the database process

  • Adding or rejoining a node to a running database cluster

  • Collecting log files into a single compressed file

  • Hiding passwords in the deployment file

The action that is performed depends on which start action you specify to the voltdb command:

  • collect — the collect option collects system and process logs related to the VoltDB database process on the current system and compresses them into a single file. This command is helpful when reporting problems to VoltDB support. The only required argument to the collect command is the path to the voltdbroot directory where the database was run. By default, the root directory is a subfolder, voltdbroot, in the current working directory where the database was started.

  • mask — the mask option disguises the passwords associated with user accounts in the security section of the deployment file by hashing them using a SHA-1 hash. The output of the voltdb mask command is either a new deployment file with hashed passwords or, if you do not specify an output file, the original input file is modified in place.

  • create — the create option starts a new, empty database. This option is useful when starting a database for the first time or if you are updating the cluster configuration by performing a save, shutdown, startup, and restore. (See Chapter 9, Using VoltDB in a Cluster for information on updating the cluster.)

  • recover — the recover option starts the database and restores a previous state from the last known snapshot or from command logs. VoltDB uses the snapshot and command log paths specified in the deployment file when looking for content to restore. If you specify recover as the startup action and no snapshots or command logs can be found, startup will fail.

  • add — the add option adds the current node to an existing cluster. See Section 9.2, “Updating the Cluster Configuration” for details on elastic scaling.

  • rejoin — If a node on a K-safe cluster fails, you can use the rejoin start action to have the node (or a replacement node) rejoin the cluster. The host-id you specify with the host argument can be any node still present in the database cluster; it does not have to be the host node specified when the cluster was started. You can also request a blocking rejoin by including the --blocking flag.

Finally, when creating a new database (create) or recovering an existing database (recover) you can include the --replica flag to create a recipient for database replication.

When starting the database, the voltdb command uses Java to instantiate the process. It is possible to customize the Java environment, if necessary, by passing command line arguments to Java through the following environment variables:

  • LOG4J_CONFIG_PATH — Specifies an alternate Log4J configuration file.

  • VOLTDB_HEAPMAX — Specifies the maximum heap size for the Java process. Specify the value as an integer number of megabytes. By default, the maximum heap size is set to 2048.

  • VOLTDB_OPTS — Specifies all other Java command line arguments. You must include both the command line flag and argument. For example, this environment variable can be used to specify system properties using the -D flag:

    export VOLTDB_OPTS="-DmyApp.DebugFlag=true"

Log Collection Arguments

The following arguments apply specifically to the collect action.

--days={integer}

Specifies the number of days of log files to collect. For example, using --days=1 will collect data from the last 24 hours. By default, VoltDB collects 14 days (2 weeks) worth of logs.

--dry-run

Lists the actions that will be taken, including the files that will be collected, but does not actually perform the collection or upload.

--no-prompt

Specifies that the process will not prompt for input, such as whether to delete the output file after uploading is complete. This argument is useful when starting the collect action from within a script.

--prefix={file-prefix}

Specifies the prefix for the resulting output file. The default prefix is "voltdb_logs".

--skip-heap-dump

Specifies that the heap dump not be included in the collection. The heap dump is usually significantly larger than the other log files and can be excluded to save space.

--upload={host}

Specifies a host server to which the output file will uploaded using SFTP.

--username={account-name}

Specifies the SFTP account to use when using the --upload option. If you specify --upload but not --username, you will be prompted for the account name.

--password={password}

Specifies the password to use when using the --upload option. If you specify --upload but not --password, you will be prompted for the password.

Database Startup Arguments

The following arguments apply to the add, create, recover, and rejoin start actions.

-H, --host={host-id}

Specifies the network address of the node that coordinates the starting of the database or the adding or rejoining of a node. When starting a database, all nodes must specify the same host address. Note that once the database starts and the cluster is complete, the role of the host node is complete and all nodes become peers.

When rejoining or adding a node, you can specify any node still in the cluster as the host. The host for an add or rejoin operation does not have to be the same node as the host specified when the database started.

The default if you do not specify a host when creating or recovering the database is localhost. In other words, a single node cluster running on the current system. You must specify a host on the command line when adding or rejoining a node.

If the host node is using an internal port other than the default (3021), you must specify the port as part of the host string, in the format host:port.

-d, --deployment={deployment-file}

Specifies the location of the database configuration file. The configuration file is an XML file that defines the database configuration, including the initial size of the cluster and which options are enabled when the database is started. See Appendix E, Deployment File (deployment.xml) for a complete description of the syntax of the configuration file.

The default, if you do not specify a deployment file, is a single node cluster without K-safety and with eight sites per host.

-l, --license={license-file}

Specifies the location of the license file, which is required when using the VoltDB Enterprise Edition. The argument is ignored when using the community edition.

-B, --background

Starts the server process in the background (as a daemon process).

--blocking

For the rejoin operation only, specifies that the database should block client transactions for the affected partitions until the rejoin is complete.

--replica

For the create and recover operations only, specifies that the database starts in read-only mode as a replica for database replication (DR). To create or recover a replica database, the deployment file must configure DR appropriately, including a <connection> tag identifying the source, or master database, for replication. See Chapter 11, Database Replication for more information.

Network Configuration Arguments

In addition to the arguments listed above, there are additional arguments that specify the network configuration for server ports and interfaces when starting a VoltDB database. In most cases, the default values can and should be accepted for these settings. The exceptions are the external and internal interfaces that should be specified whenever there are multiple network interfaces on a single machine.

You can also, optionally, specify a unique network interface for individual ports by preceding the port number with the interface's IP address (or hostname) followed by a colon. Specifying the network interface as part of an individual port setting overrides the default interface for that port set by --externalinterface or --internalinterface.

The network configuration arguments to the voltdb command are listed below. See the appendix on server configuration options in the VoltDB Administrator's Guide for more information about network configuration options.

--externalinterface={ip-address}

Specifies the default network interface to use for external ports, such as the admin and client ports.

--internalinterface ={ip-address}

Specifies the default network interface to use for internal communication, such as the internal port.

--publicinterface={ip-address}

Specifies the public network interface. This argument is useful for hosted systems where the internal and external interfaces may not be generally reachable from the Internet. In which case, specifying the public interface helps the VoltDB Management Center provide publicly accessible links for the cluster nodes.

--admin=[ip-address:]{port-number}

Specifies the admin port. The --admin flag overrides the admin port setting in the deployment file.

--client=[ip-address:]{port-number}

Specifies the client port.

--http=[ip-address:]{port-number}

Specifies the http port. The --http flag both sets the port number (and optionally the interface) and enables the http port, overriding the http setting, if any, in the deployment file.

--internal=[ip-address:]{port-number}

Specifies the internal port used to communicate between cluster nodes.

--replication=[ip-address:]{port-number}

Specifies the replication port used for database replication. The --replication flag overrides the replication port setting in the deployment file.

--zookeeper=[ip-address:]{port-number}

Specifies the zookeeper port. By default, the zookeeper port is bound to the server's internal interface (127.0.0.1).

Examples

The first example shows the command for creating a database using a custom configuration file, 2nodedeploy.xml, and the node zeus as the host.

$ voltdb create --deployment=2nodedeploy.xml \
                --host=zeus

The second example takes advantage of the defaults for the host and deployment arguments to start a single-node database.

$ voltdb create