VoltDB Home » Documentation » Using VoltDB


voltadmin — Performs administrative functions on a VoltDB database.


voltadmin {command} [args...]


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.


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={text}

Specifies the password to use when connecting to the database. You must specify a username and password if security is enabled for the database. If you specify a username with the --user argument but not the --password argument, VoltDB prompts for the password. This is useful when writing shell scripts because it avoids having to hardcode passwords as plain text in the script.

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


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.

dr reset

Resets the database replication (DR) connection on a master database. Performing a reset breaks the existing DR connection, deletes pending binary logs and stops the queuing of DR data. This command is useful for eliminating unnecessary resource usage on a master database after the replica stops or is promoted. Note, however, after a reset DR must start over from scratch; it cannot be restarted where it left off.

pause [--wait]

Pauses the database, stopping any additional activity on the client port. Normally, pause returns immediately. However, you can use the --wait flag to have the command wait until all pending transactions are processed and all database replication (DR) and export queues are flushed. Use of --wait is recommended if you are shutting down the database and do not intend to restart with recover, since --wait ensures all associated DR or export data is delivered prior to shutdown.


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


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.


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.

--skiptables={ table-name [,...] }

Specifies one or more tables to leave out of the snapshot. Separate multiple table names with commas.

--tables={ table-name [,...] }

Specifies what table(s) to include in the snapshot. Only the specified tables will be included. Separate multiple table names with commas.

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. If no tables exist in the database (that is, no schema has been defined) the restore command will also restore the original schema, including stored procedure classes, before restoring the data.

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 {deployment}

Updates the deployment configuration on a running database. There are limitations on what changes can be made to the configuration of a running database cluster. Allowable changes include the following:

  • Security settings, including user accounts

  • Import and export settings

  • Database replication settings (except the DR cluster ID)

  • Automated snapshots

  • System settings:

    Heartbeat timeout
    Query Timeout
    Resource Limit — Disk Limit
    Resource Limit — Memory Limit

You cannot use the update command to change paths, ports, command logging, or <cluster> attributes (such as K safety or sites per host).

stop {server-id}

Stops an individual node in the cluster. The voltadmin stop command can only be used on a K-safe cluster and will not intentionally shutdown the database. That is, the command will only stop a node if there are enough nodes left for the cluster to remain viable.


Stops the database.


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