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.
Specifies a file that lists the username and password of the account to use when connecting to a database with
security enabled. This is useful when writing shell scripts because it avoids having to hardcode the password as plain
text in the script. The credentials file is interpreted as a Java properties file defining the properties
username and password. For example:
username: johndoe password: 4tUn8
Because it is a Java properties file, you must escape certain special characters in the username or password, including the colon or equals sign.
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.
Resets any blocked export queues, resuming export at the next available export record.
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.
Begins the resize process for reducing the size of a K-safe cluster. See Section 9.3.2, “Removing Nodes with Elastic Scaling” for more information on resizing clusters. The following qualifiers affect what actions are taken. Without qualifiers, the command tests to ensure a resize is possible, reports which nodes will be removed, and prompts before starting the resize process.
Ignores any pending data for export targets that are disabled when performing the resize process. Normally, resize waits for all export queues to drain before starting the resize process, even if the target is currently disabled in the database configuration.
Restarts the resize process after an unexpected failure.
Tests to see if the cluster has enough nodes to perform a resize operation while retaining its K-safety factor. If so, it reports which nodes would be removed during resizing.
Skips the prompt when starting the resize process. This qualifier is useful when including the voltadmin resize command in scripts where you are sure you want to start the process and do not want interactive prompts.
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.
The following arguments let you selectively include or exclude data from certain tables during the restore operation.
Data for the specified tables is not restored. All other tables are restored. Separate multiple table names with commas.
Only data for the specified tables is restored. Data for all other tables is ignored. Separate multiple table names with commas.
Note that if the database is empty (that is, has no existing schema), the full schema from the snapshot is always loaded even if you choose not to load the data for certain tables. Also, you can specify either --skiptables or --tables but not both on the same command.
Displays information about the cluster's current license.
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:
| Flush interval |
| 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.
By default, the stop command waits for all partition and export leadership on the specified node to be redistributed to other nodes in the cluster in an orderly fashion before stopping the node. You can use the --force argument to stop the node immediately. However, if you force the node to stop, the remainder of the cluster must negotiate leadership after the node stops, which can have several negative effects. The advantages of using the default, orderly stop command are:
In-flight transactions queued to the stopped node are completed and returned to the client. A forced stop interrupts these transactions resulting in lost connection and other errors being returned to the clients.
Stopping the node has reduced impact on the ongoing transactions and workload for the database. A forced stop disrupts ongoing transactions while the cluster negotiates the migration of partition leadership.
Export queues are transitioned correctly, avoiding gaps and potentially lost export data that can result if nodes are interrupted and restarted in quick succession.
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.
Cancels a pending shutdown. The shutdown --save command can be blocked if the targets for pending DR or export are currently unavailable. If this happens, you can do a CTRL-C to interrupt the shutdown --save command, but that does not cancel the shutdown itself and your database is not operational. The shutdown --cancel command cancels the shutdown operation and returns the database to an operational state.
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:
Do a shutdown --cancel to cancel the shutdown, correct the problem, then reissue the shutdown command
Do a shutdown --cancel to cancel the shutdown and resume normal database operations
Do a shutdown --force to initiate an immediate shutdown
Note that if you do a shutdown --force after a shutdown --save command, 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
V9.x Documentation