You can access KVStore commands either through the Command Line Interface(CLI)
or through "java -jar <kvhome>/lib/kvstore.jar <command>".
The following sections
will describe both the CLI commands and the utility commands accessed through
"java -jar".
The Command Line Interface (CLI) is run interactively or used to run single commands. The general usage to start the CLI is:
java -jar KVHOME/lib/kvstore.jar runadmin -host <hostname> -port <port> [single command and arguments]
If you want to run a script file, you can use the "load" command on the command line:
java -jar KVHOME/lib/kvstore.jar runadmin -host <hostname> -port <port> load -file <path-to-script>
If none of the optional arguments are passed, it starts interactively. If additional arguments are passed they are interpreted as a single command to run, then return. The interactive prompt for the CLI is:
"kv-> "
Upon successful completion of the command, the CLI's process exit code is zero. If there is an error, the exit code will be non-zero.
The CLI comprises a number of commands, some of which have subcommands. Complex commands are grouped by general function, such as "show" for displaying information or "ddl" for manipulating schema. All commands accept the following flags:
-help
Displays online help for the command or subcommand.
?
Synonymous with -help. Displays online help for the command or subcommand.
-verbose
Enables verbose output for the command.
CLI commands have the following general format:
All commands are structured like this:
"kv-> command [sub-command] [arguments]
All arguments are specified using flags which start with "-"
Commands and subcommands are case-insensitive and match on partial strings(prefixes) if possible. The arguments, however, are case-sensitive.
This appendix contains the following information on the commands and subcommands:
configure -name <storename>
Configures a new store. This call must be made before any other administration can be performed.
connect -host <hostname> -port <registry port>
Connects to the specified host and registry port to perform administrative functions. An Admin service must be active on the target host. This command can be used if the initial connection information is lost or incorrect.
Encapsulates operations that manipulate schemas in the store. The subcommands are as follows:
For details on managing schema in the store, see Managing Avro Schema.
ddl add-schema <-file <file> | -string <schema string>> [-evolve] [-force]
Use this subcommand to add a new schema or change (<evolve>) an existing schema with the same name. Use the -evolve flag to indicate that the schema is changing. Use the -force flag to add the schema in spite of the evolution warnings.
ddl enable-schema -name <name>.<ID>
Use this subcommand to enable an existing, previously disabled schema.
help [command [sub-command]]
Prints help messages. With no arguments the top-level shell commands are listed. With additional commands and subcommands, additional detail is provided.
Toggles visibility and setting of parameters that are normally hidden. Use these parameters only if advised to do so by Oracle Support.
history [-last <n>] [-from <n>] [-to <n>]
Displays command history. By default all history is displayed. Optional flags are used to choose ranges for display.
load -file <path to file>
Loads the named file and interpret its contents as a script of commands to be executed. If any of the commands in the script fail, execution will stop at that point.
Encapsulates operations, or jobs that modify store state. All subcommands with the exception of interrupt and wait change persistent state. Plans are asynchronous jobs so they return immediately unless -wait is used. Plan status can be checked using "show plans". The optional arguments for all plans include:
-wait
Wait for the plan to complete before returning.
-plan-name
The name for a plan. These are not unique.
-noexecute
Do not execute the plan. If specified, the plan can be run later using "plan execute".
-force
Used to force plan execution and plan retry.
The subcommands are as follows:
plan change-storagedir -sn <id> -storagedir <path> -add | -remove
[-plan-name <name>] [-wait] [-noexecute]
[-force]
Adds or removes a mount point on a Storage Node.
plan change-parameters -service <id> | -all-rns | -all-admins
[-dry-run] [-plan-name <name>] [-wait]
[-noexecute] [-force] -params [name=value]
Changes parameters for the specified service or all service instances of the same type. The -service flag allows a single instance to be affected. The -all-* flags can be used to change all instance of the service type. The parameters to change follow the -params flag and are separated by spaces. The parameter values with embedded spaces must be quoted; for example, name="value with spaces". If -dry-run is specified, the new parameters are returned without changing them.
plan deploy-admin -sn <id> -port <http port> [-plan-name <name>]
[-wait] [-noexecute] [-force]
Deploys an Admin to the specified Storage Node. Its graphical interface listens on the specified port.
Usage:
plan deploy-datacenter -name <datacenter name>
-rf <replication factor> [-plan-name <name>]
[-wait] [-noexecute] [-force]
Deploys the specified datacenter to the store.
A store can currently have only one Data Center.
plan deploy-sn -dc <id> | -dcname <name> -host <host> -port <port>
[-plan-name <name>] [-wait] [-noexecute] [-force]
Deploys the Storage Node at the specified host and port into the specified datacenter.
plan execute -id <id> | -last [-wait] [-force]
Executes a created but not yet executed plan. The plan must have been previously created using the -noexecute flag . Use -last to reference the most recently created plan.
plan interrupt -id <plan id> | -last
Interrupts a running plan. An interrupted plan can only be re-executed or canceled. Use -last to reference the most recently created plan.
plan cancel -id <plan id> | -last
Cancels a plan that is not running. A running plan must be interrupted before it can be canceled. Use -last to reference the most recently created plan.
plan migrate-sn -from <id> -to <id> [-admin-port <admin port>]
[-plan-name <name>] [-wait] [-noexecute] [-force]
Migrates the services from one Storage Node to another. The old node must not be running. If the old node hosted an admin service, the -admin-port argument is required.
plan remove-admin -admin <id> [-plan-name <name>]
[-wait] [-noexecute] [-force]
Removes the specified Admin replica.
You cannot remove the sole Admin if only one Admin
instance is configured. Also, if you try to remove an
Admin when the removal would result in there being
fewer than three deployed Admins, the command will fail
unless you give the -force flag.
If you try to remove the Admin that is currently the
master, mastership will transfer to another Admin. The
plan will be interrupted , and subsequently can be
re-executed on the new master Admin, by using the
plan execute command.
plan remove-sn -sn <id> [-plan-name <name>]
[-wait] [-noexecute] [-force]
Removes the specified Storage Node from the topology.
plan start-service -service <id> | -all-rns [-plan-name <name>]
[-wait] [-noexecute] [-force]
Starts the specified service(s).
plan deploy-topology -name <topology name> [-plan-name <name>]
[-wait] [-noexecute] [-force]
Deploys the specified topology to the store. This operation can take a while, depending on the size and state of the store.
change-policy [-dry-run] -params [name=value]*
Modifies store-wide policy parameters that apply to not yet deployed services. The parameters to change follow the -params flag and are separated by spaces.
Parameter values with embedded spaces must be quoted, for example, name="value with spaces". If -dry-run is specified, the new parameters are returned without changing them.
Encapsulates commands that manipulates Storage Node pools, which are used for resource allocations. The subcommands are as follows:
pool create -name <name>
Creates a new Storage Node pool to be used for resource distribution when creating or modifying a store.
Encapsulates commands that display the state of the store and its components. The subcommands are as follows:
show parameters -policy | -service <name>
Displays service parameters and state for the specified service. The service may be a RepNode, StorageNode, or Admin service, as identified by any valid string, for example rg1-rn1, sn1, admin2, etc. Use the -policy flag to show global policy parameters.
show events [-id <id>] | [-from <date>] [-to <date> ]
[-type <stat | log | perf>]
Displays event details or list of store events. The status events indicate changes in service status.
Log events are noted if they require attention.
Performance events are not usually critical but must be investigated. Events marked SEVERE must always be investigated.
The following date/time formats are accepted. They are interpreted in the local time zone.
| MM-dd-yy HH:mm:ss:SS |
| MM-dd-yy HH:mm:ss |
| MM-dd-yy HH:mm |
| MM-dd-yy |
| HH:mm:ss:SS |
| HH:mm:ss |
| HH:mm |
show faults [-last] [-command <command index>]
Displays faulting commands. By default all available faulting commands are displayed. Individual fault details can be displayed using the -last and -command flags.
show plans [-id <id> | -last]
Shows details of the specified plan or list all plans that have been created along with their corresponding plan IDs and status. Use -last to show details of the most recent created plan.
show schemas [-disabled] | [-name <name>]
Displays schema details of the named schema or a list of schemas registered with the store. The -disabled flag enables listing of disabled schemas.
show snapshots [-sn <id>]
Lists snapshots on the specified Storage Node. If no Storage Node is specified, one is chosen from the store. You can use this command to view the existing snapshots.
Encapsulates commands that create and delete snapshots, which are used for backup and restore. The subcommands are as follows:
snapshot create -name <name>
Creates a new snapshot using the specified name as the prefix.
Encapsulates commands that manipulate store topologies. Examples are redistribution/rebalancing of nodes or changing replication factor. Topologies are created and modified using this command. They are then deployed by using the "plan deploy-topology" command.The subcommands are as follows:
topology change-repfactor -name <name> -pool <pool name>
-dc <id> | -dcname <name>
-rf <replication factor>
Modifies the topology to change the replication factor of the specified datacenter to a new value. The replication factor may not be decreased at this time.
topology clone -from <from topology> -name <to topology>
or
topology clone -current -name <to topology>
Clones an existing topology to a new candidate topology to be used for topology change operations.
topology create -name <candidate name> - pool <pool name>
-partitions <num>
Creates a new topology with the specified number of partitions using the specified storage pool.
topology move-repnode -name <name> -rn <id>
Modifies the topology to move the specified RepNode to an available Storage Node chosen by the system.
topology preview -name <name> [-start <from topology>]
Previews the changes that would be made for the named topology relative to a starting topology. If -start is not specified, the current topology is used. This command should be used before deploying a new topology.
topology rebalance -name <name> -pool <pool name>
[-dc <id> | -dcname <name>]
Modifies the named topology to create a balanced topology. If the optional -dc flag is used, only Storage Nodes from the specified datacenter are used for the operation.
topology redistribute -name <name> -pool <pool name>
Modifies the named topology to redistribute resources to more efficiently use those available.
topology validate [-name <name>]
Validates the specified topology. If no topology is specified, the current topology is validated. Validation generates violations and notes.
Violations are issues that can cause problems and should be investigated.
Notes are informational and highlight configuration oddities that may be potential issues, but may be expected.
Used to toggle the global verbosity setting. This property can also be set per-command basis using the -verbose flag.