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


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 [catalog] [deployment]

Updates the deployment configuration or application catalog on a running database. (Note: use of application catalogs is deprecated and updating the catalog is only possible if the database was started with the schema="catalog" option in the deployment file.) There are limitations on what changes can be made on a live update. See the description of the @UpdateApplicationCatalog stored procedure for details.

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