Archive
Archive
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.
Displays information about how to use a command. The --help flag and the help command perform the same function.
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.
Specifies the use of Kerberos authentication when connecting to the database. You must login to your Kerberos account using kinit before issuing the voltadmin with this argument.
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.
Specifies the use of TLS encryption when communicating with the server. Only necessary if the cluster is configured to use TLS encryption for the external ports. See Section D, “Using CLI Commands with TLS/SSL” for more information.
Specifies the username to use for authenticating to the database. The username is required if the database has security enabled.
Displays additional information about the specific commands being executed.
The following are the administrative functions that you can invoke using voltadmin.
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.
Removes the current cluster from an XDCR environment. Performing a drop breaks existing DR connections, deletes pending binary logs and stops the queuing of DR data on the current cluster. It also tells all other clusters in the XDCR relationship to drop their connection to the current cluster and remove any associated binary logs for that cluster.
This command will wait until all other clusters respond before returning to the shell prompt. If one (or more) of the clusters are unreachable, the command will periodically report which clusters it is waiting for. Be aware that if you CTRL-C out of the command before it returns to the shell prompt, one or more of the remote clusters will not have received the appropriate message and will not have cleared their logs for the targeted cluster. In that case, you need to clear that cluster's queues manually after it comes back online using the dr reset --cluster command.
The dr drop command lets you effectively remove a single cluster — the cluster on which the the command is executed — from a multi-cluster XDCR environment in a single command.
Resets the database replication (DR) connection(s) for the database. Performing a reset breaks existing DR connections, deletes pending binary logs and stops the queuing of DR data on the current cluster.
This command is useful in passive DR 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. Similarly, if there are two clusters in an XDCR environment, you can use dr reset for one cluster to drop the connection to the other cluster.
If you are using multiple XDCR clusters, the dr drop command is the recommended way to remove a running cluster from the environment. Otherwise, if you use the dr reset command you must choose between removing the connections to all other clusters or just one cluster using the following options. You must issue the appropriate command on all applicable clusters:
Resets DR connections and queues to all other clusters on the current cluster. Choose this option if you want the current cluster to survive and then restart DR from scratch on the other remaining clusters.
Drops the connection to just one cluster. Specify the ID of the remote cluster you wish to drop from the XDCR environment as an argument to the --cluster option. For example, if one cluster has stopped and you want to remove it from the XDCR environment, you can reset the connections to that cluster by issuing the dr reset --cluster={id} command on all the remaining clusters. You must also specify --force when you specify --cluster.
Verifies that you want to drop one cluster from a multi-cluster XDCR environment. There is a risk, when a cluster fails, that it has not sent the same binary logs to all other clusters. In this situation, if you drop the one cluster from the XDCR environment, the remaining clusters can diverge. Which is why you must confirm that you really want to drop just one cluster.
Stopping the remote cluster with an orderly shutdown (voltadmin shutdown) ensures that all binary logs are delivered. So it is then safe to do a dr reset with --cluster and --force. Otherwise, the recommended approach is to choose one cluster as the source, stop all DR connections from that cluster, then restart DR from scratch on the remaining clusters. However, you can, if you choose, use --force to drop the one cluster if you are sure no divergence has occurred.
The --all and --cluster options are mutually exclusive.
Updates the logging configuration. You specify the new configuration as a Log4j XML configuration file.
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.
Since it is possible that lost connections to external systems or other abnormal conditions can cause queues to hang, the pause --wait command waits for up to two minutes if transactions are pending but not being cleared. After two minutes of inactivity, the command times out and stops waiting, leaving the database in a paused state. You can change the timeout period by using the --timeout (or -t) flag and specifying a different timeout period in seconds.
If the pause --wait command times out, review any error messages to determine the cause of the delay. Once you correct the problem, you can either reissue the pause --wait command or check the @Statistics system procedure results to make sure all pending transactions and queues are clear.
Promotes a replica database, stopping replication and enabling read/write queries on the client port.
Resumes normal database operation after a pause.
Creates a snapshot containing the current database contents. Snapshot files are saved to each server in the cluster. If you use save without any arguments, the snapshot is saved into the database's snapshots directory where it can automatically be restored the next time the database starts. If you specify an alternate directory and ID, the snapshot files are saved to the specified path using the unique ID as a file prefix.
When saving into the default snapshots directory, VoltDB automatically performs a full snapshot in native mode. The following are additional arguments you can specify when saving to a specific location and unique ID. (Only the --blocking argument is allowed when saving to the default snapshots directory.)
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.
Specifies one or more tables to leave out of the snapshot. Separate multiple table names with commas.
Specifies what table(s) to include in the snapshot. Only the specified tables will be included. Separate multiple table names with commas.
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.
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.
Displays information on the state of the cluster, such as the number of nodes and uptime. You can use the following options to customize the content and presentation of the status information:
Adds information about the current status of data replication to the display.
Outputs the information in JSON format.
Specifies that the information be continuously updated until you interrupt the command (with CTRL-C, for example).
Updates the 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, partition detection, or <cluster> attributes (such as K safety or sites per host).
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.
Shuts down the database process on all nodes of the cluster. By default, voltadmin shutdown performs an orderly shutdown, pausing the database, completing all pending transactions and writing any queued export, import, or DR data to disk before shutting down the database. You can also use one of the following arguments to modify the behavior of shutdown:
Stops the database immediately. If you do not need to save any in-process work, you can use the
--force argument to stop the database immediately.
Specifies that not only will all data be made durable, all pending DR and export data will be sent to the corresponding external systems and a final snapshot will be taken before the cluster is shutdown. The resulting snapshot will be used, in place of command logs, the next time the database is started with the voltdb start command. Using the final snapshot on startup permits changes not normally allowed by command logs, such as upgrading the VoltDB software.
Since it is possible that lost connections to external systems or other abnormal conditions can cause queues to hang, the shutdown command (without the --force flag) waits for up to two minutes if transactions are pending but not being cleared. After two minutes of inactivity, the command times out, leaving the database in a paused state but not shutdown. You can change the timeout period by using the --timeout (or -t) flag and specifying a different timeout period in seconds.
If the shutdown command times out, review any error messages to determine the cause of the delay. You can either correct the problem and reissue the shutdown command or do a shutdown --force to initiate an immediate shutdown. Note, however, if you do a shutdown --force after a shutdown --save command times out, the system will not have created a final snapshot.
The following example performs an orderly shutdown.
$ voltadmin shutdown
The next example uses pause and save to create a snapshot of the database contents as a backup before shutting down.
$ voltadmin pause --wait $ voltadmin save --blocking ./ mydb $ voltadmin shutdown
The last example uses the shutdown --save command to create a snapshot of the database contents, similar to the previous example. However, in this case, the snapshot that is created will be used automatically to restore the database on the next start command.
$ voltadmin shutdown --save
V7.x Documentation