voltadmin

Documentation

VoltDB Home » Documentation » Using VoltDB

voltadmin

voltadmin — Performs administrative functions on a VoltDB database.

Synopsis

voltadmin [args...] {command}

Description

The voltadmin command allows you to perform administrative tasks on a VoltDB database. You specify the database server to access and, optionally, authentication credentials using arguments to the voltadmin command. Individual administrative commands may have they own unique arguments as well.

Arguments

The following global arguments are available for all voltadmin commands.

-h, --help

Displays information about how to use a command. The --help flag and the help command perform the same function.

-H, --host=server-id[:port]

Specifies which database server to connect to. You can specify the server as a network address or hostname. By default, voltadmin attempts to connect to a database on localhost. You can optionally specify the port number. If you do not specify a port, voltadmin uses the default admin port.

-p, --password=password

Specifies the password to use for authenticating to the database. The password is required if the database has security enabled..

-u, --user=user-id

Specifies the username to use for authenticating to the database. The username is required if the database has security enabled.

-v, -verbose

Displays additional information about the specific commands being executed.

Commands

The following are the administrative functions that you can invoke using voltadmin.

help [command]

Displays information about the usage of individual commands or, if you do not specify a command, summarizes usage information for all commands. The help command and --help qualifier are synonymous.

pause

Pauses the database, stopping any additional activity on the client port.

promote

Promotes a replica database, stopping replication and enabling read/write queries on the client port.

resume

Resumes normal database operation after a pause.

save {directory} {unique-ID}

Creates a snapshot containing the current database contents. The contents are saved to disk on the server(s) using the unique ID as a file prefix and the directory specification as the file path. Additional arguments for the save command are:

--format={ csv | native }

Specifies the format of the snapshot files. The allowable formats are CSV (comma-separated value) and native formats. Native format snapshots can be used for restoring the database. CSV files can be used by other utilities (such as spreadsheets or the VoltDB CSV loader) but cannot be restored using the voltadmin restore command.

--blocking

Specifies that the snapshot will block all other transactions until the snapshot is complete. The advantage of blocking snapshots is that once the command completes you know the snapshot is finished. The disadvantage is that the snapshot blocks ongoing use of the database.

By default, voltadmin performs non-blocking snapshots so as not to interfere with ongoing database operation. However, note that the non-blocking save command only starts the snapshot. You must use show snapshots to determine when the snapshot process is finished if you want to know when it is safe, for example, to shutdown the database.

restore {directory} {unique-ID}

Restores the data from a snapshot to the database. The data is read from a snapshot using the same unique ID and directory path that were used when the snapshot was created.

show snapshots

Displays information about up to ten previous snapshots. This command is useful for determining the success or failure of snapshots started with the save command.

update {catalog} {deployment}

Updates the catalog and deployment configuration on a running database. There are some limitations on what changes can be made on a live update. For example, you cannot rename a table or change its partitioning column. See the description of the @UpdateApplicationCatalog stored procedure for details.

shutdown

Stops the database.

Example

The following example illustrates one way to perform an orderly shutdown of a VoltDB cluster, including pausing and saving the database contents.

$ voltadmin pause
$ voltadmin save --blocking ./ mydb 
$ voltadmin shutdown
>