Appendix A.  KVStore Command Reference

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

CLI Commands and Subcommands

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:

  1. All commands are structured like this:

    "kv-> command [sub-command] [arguments] 
  2. All arguments are specified using flags which start with "-"

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

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

ddl enable-schema -name <name>.<ID> 

Use this subcommand to enable an existing, previously disabled schema.

ddl disable-schema

ddl disable-schema -name <name>.<ID> 

Use this subcommand to disable an existing schema.


exit | quit 

Exits the interactive command shell.


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.


Monitors the store-wide log file until interrupted by an "enter" key press.


Displays the status of runtime components of the store, excluding administrative services.


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

plan change-storagedir -sn <id> -storagedir <path> -add | -remove
                       [-plan-name <name>] [-wait] [-noexecute]

Adds or removes a mount point on a Storage Node.

plan change-parameters

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

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.

plan deploy-datacenter


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

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

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

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

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

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

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

plan remove-sn -sn <id> [-plan-name <name>]
               [-wait] [-noexecute] [-force] 

Removes the specified Storage Node from the topology.

plan start-service

plan start-service -service <id> | -all-rns [-plan-name <name>]
               [-wait] [-noexecute] [-force]

Starts the specified service(s).

plan stop-service

plan stop-service -service <id> | -all-rns 

Stops the specified service(s).

plan deploy-topology

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.

plan wait

plan wait -id <id> | -last [-seconds <timeout in seconds>]

Waits for the specified plan to complete. If the optional timeout is specified, wait that long, otherwise wait indefinitely. Use -last to reference the most recently created plan.


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

pool create -name <name> 

Creates a new Storage Node pool to be used for resource distribution when creating or modifying a store.

pool remove

pool remove -name <name> 

Removes a Storage Node pool.

pool join

pool join -name <name> [-service] <snX>* 

Adds Storage Nodes to an existing storage node pool.


Encapsulates commands that display the state of the store and its components. The subcommands are as follows:

show parameters

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 admins

show admins 

Displays basic information about Admin services.

show events

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

show faults

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 perf

show perf 

Displays recent performance information for each RepNode.

show plans

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 pools

show pools 

Lists Storage Node pools.

show schemas

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

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.

show topology

show topology [-dc] [-rn] [-sn] [-store] [-status] [-perf] 

Displays the store topology. By default it shows the entire topology. The optional flags restrict the display to one or more of Datacenters, RepNodes, StorageNodes and Storename, or specify service status or performance.


Encapsulates commands that create and delete snapshots, which are used for backup and restore. The subcommands are as follows:

snapshot create

snapshot create -name <name> 

Creates a new snapshot using the specified name as the prefix.

snapshot remove

snapshot remove -name <name> | -all 

Removes the named snapshot. If -all is specified, remove all snapshots.


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

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

topology clone -from <from topology> -name <to topology>


topology clone -current -name <to topology> 

Clones an existing topology to a new candidate topology to be used for topology change operations.

topology create

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 delete

topology delete -name <name> 

Deletes a topology.

topology list

topology list 

Lists explaining the topologies.

topology move-repnode

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

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

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

topology redistribute -name <name> -pool <pool name> 

Modifies the named topology to redistribute resources to more efficiently use those available.

topology validate

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.

topology view

topology view -name <name> 

Views details of the specified topology.


Used to toggle the global verbosity setting. This property can also be set per-command basis using the -verbose flag.


verify [-silent] 

Verifies the store configuration by iterating the components and checking their state against that expected in the Admin database. This call may take a while on a large store.