Using VoltDB

contents

voltdb

voltdb — Compiles or starts the VoltDB database

Synopsis

voltdb compile [args] [DDL-file ...]

voltdb create [replica] {catalog application-catalog} [host host-id] [deployment deployment-file] [license license-file]

voltdb recover [host host-id] [deployment deployment-file] [license license-file]

voltdb [live] rejoin host host-id [deployment deployment-file] [license license-file]

Description

The voltdb command either compiles the database schema or starts a database server process on the current system. The action that is performed depends on which start action you specify:

  • compile — the compile option compiles the database schema and stored procedures into an application catalog. You can specify one or more data definition language (DDL) files that describe the schema of the database, the stored procedures, and the partitioning columns. See Appendix A, Supported SQL DDL Statements for the SQL statements supported in the DDL files. The output of the compile action is an application catalog that can be used to start the VoltDB database. The default output filename is catalog.jar. However, you can use the --output argument to specify a different file name or location. See the next section for other arguments to the compile action.

  • 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 catalog by performing a save, shutdown, startup, and restore. (See Chapter 7, Updating Your VoltDB Database for information on updating your application catalog.)

  • recover — the recover option starts the database and restores a previous state from the last known snapshot or from command logs (Enterprise Edition only). 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.

  • 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. When using the Enterprise Edition, you can also request a live rejoin by including the live keyword.

Finally, when starting a new database you can include the replica keyword to create a recipient for database replication. Database replication is an Enterprise feature and requires a separate license.

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 1024.

  • 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"

Schema Compilation Arguments

The following arguments apply specifically to the compile action.

-classpath={Java-classpath}

Specifies additional classpath locations for the compilation process to search when looking for stored procedure class files. The classpath you specify with this argument is appended to any existing classpath definition.

-o, --output={application-catalog}

Specifies the file and path name to use for the application catalog that is created as a result of the compilation.

-p, --project={project-definition-file}

(Deprecated) Specifies a project definition file to use instead of a DDL file. This argument is provided for compiling old VoltDB projects. All of the features of the project definition file used in previous versions of VoltDB are now available as DDL syntax, removing the need for a separate project file and simplifying the development process.

Database Startup Arguments

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

catalog {application-catalog}

Specifies the application catalog containing the schema and stored procedures to load when starting the database. Two special notes concerning the catalog:

  • The catalog must be identical on all nodes when starting a cluster.

  • The catalog specified on the command line is only used when creating a new database.

If you recover previous data using the recover start action, the catalog saved with the snapshot or command log is loaded and any catalog you specify on the command line is ignored.

host {host-id}

Specifies the network address of the node that coordinates the start or rejoining of the database. 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 a node, you can specify any node still in the cluster as the host. The host for a 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 starting 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 rejoining a node.

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 two sites per host.

license {license-file}

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

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 VotlDB 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.

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

externalinterface {ip-address}

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

internalinterface {ip-address}

Specifies which network interface to use for internal communication, such as the internal and zookeeper ports.

internalport {port-number}

Specifies the internal port number used to communicate between cluster nodes.

port {port-number}

Specifies the client port number.

replicationport {port-number}

Specifies the first of three replication ports used for database replication. Enterprise Edition only.

zkport {port-number}

Specifies the zookeeper port number.

Examples

The first example uses the compile action to create an application catalog from two DDL files. The --classpath argument specifies the location of the stored procedure class files.

$ voltdb compile --classpath=./obj employees.sql company.sql

The next example shows the command for creating a database running the voter sample application, using a custom configuration file, 2nodedeploy.xml, and the node zeus as the host.

$ voltdb create catalog voter.jar deployment 2nodedeploy.xml \
         host zeus

The following example takes advantage of the defaults for the host and deployment arguments to start a single-node database on the current system using the voter catalog.

$ voltdb create catalog voter.jar
contents