plan

plan add-index

plan add-index -name <name> -table <name> [-field <name>]*
    [-desc <description>]
    [-plan-name <name>] [-wait] [-noexecute] [-force]

Adds an index to a table in the store.

where:

-name

Specifies the name of the index to add to a table.
-table

Specifies the table name where the index will be added. The table name is a dot-separated name with the format tableName[.childTableName]*.
-field

Specifies the field values of the primary key.

plan add-table

plan add-table -name <name>
    [-plan-name <name>] [-wait] [-noexecute] [-force]

Adds a new table to the store. The table name is a dot-separated name with the format tableName[.childTableName]*.

Before adding a table, first use the table create command to create the named table. The following example defines a table (creates a table by name, adds fields and other table metadata).

## Enter into table creation mode
table create -name user -desc "A sample user table"
user->
user-> help
Usage: add-array-field |
add-field |
add-map-field |
add-record-field |
cancel |
exit |
primary-key |
remove-field |
set-description |
shard-key |
show
## Now add the fields
user-> help add-field
Usage: add-field -type <type> [-name <field-name> ] [-not-required]
[-nullable] [-default <value>] [-max <value>] [-min <value>]
[-max-exclusive] [-min-exclusive] [-desc <description>]
[-size <size>] [-enum-values <value[,value[,...]]
<type>: INTEGER, LONG, DOUBLE, FLOAT, STRING, BOOLEAN, DATE, BINARY, FIX
ED_BINARY, ENUM
## Adds a field. Ranges are inclusive with the exception of String,
## which will be set to exclusive.
user-> add-field -type Integer -name id
user-> add-field -type String -name firstName
user-> add-field -type String -name lastName
user-> help primary-key
Usage: primary-key -field <field-name> [-field <field-name>]*
## Sets primary key.
user-> primary-key -field id
## Exit table creation mode
user-> exit
## Table User built.

Use table list -create to see the list of tables that can be added. The following example lists and displays tables that are ready for deployment.

kv-> table list
## Tables to be added:
## User -- A sample user table
kv-> table list -name user
## Add table User:
{
  "type" : "table",
  "name" : "User",
  "id" : "User",
  "description" : "A sample user table",
  "shardKey" : [ "id" ],
  "primaryKey" : [ "id" ],
  "fields" : [ {
    "name" : "id",
    "type" : "INTEGER"
  }, {
    "name" : "firstName",
    "type" : "STRING"
  }, {
    "name" : "lastName",
    "type" : "STRING"
  } ]
}

The following example adds the table to the store.

## Add the table to the store.
kv-> help plan add-table
kv-> plan add-table -name user -wait
Executed plan 5, waiting for completion...
Plan 5 ended successfully
kv-> show tables -name user
{
  "type" : "table",
  "name" : "User",
  "id" : "r",
  "description" : "A sample user table",
  "shardKey" : [ "id" ],
  "primaryKey" : [ "id" ],
  "fields" : [ {
    "name" : "id",
    "type" : "INTEGER"
  }, {
    "name" : "firstName",
    "type" : "STRING"
  }, {
    "name" : "lastName",
    "type" : "STRING"
  } ]
  }

For more information and examples on table design, see Table Management in the SQL Reference Guide.

plan cancel

plan cancel -id <plan id> | -last - json

Cancels a plan that is not running. A running plan must be interrupted before it can be canceled.

Use show plans to list all plans that have been created along with their corresponding plan IDs and status.

Use the -last option to reference the most recently created plan.

kv-> plan cancel -id 23 -json
{
"operation" : "plan cancel|interrupt",
"returnCode" : 5000,
"description" : "Plan 23 was canceled",
"returnValue" : null
}

plan change-parameters

plan change-parameters -security | -service <id> |
    -all-rns [-zn <id> | -znname <name>] | -all-ans [-zn <id> |
    -znname <name>] | -all-admins [-zn <id> | -znname <name>]
    [-dry-run] [-plan-name <name>]
    [-json] [-wait] [-noexecute] [-force] -params [name=value]*

Changes parameters for either the specified service, or for all service instances of the same type that are deployed to the specified zone or all zones.

The -security flag allows changing store-wide global security parameters, and should never be used with other flags.

The -service flag allows a single instance to be affected; and should never be used with either the -zn or -znname flag.

The -all-* flags can be used to change all instances 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".

One of the -all-* flags can be combined with the -zn or -znname flag to change all instances of the service type deployed to the specified zone; leaving unchanged, any instances of the specified type deployed to other zones. If one of the -all-* flags is used without also specifying the zone, then the desired parameter change will be applied to all instances of the specified type within the store, regardless of zone.

If -dry-run is specified, the new parameters are returned without changing them. Use the command show parameters to see what parameters can be modified. For more information, see show parameters.

For more information on changing parameters in the store, see Setting Store Parameters.

Note:

The plan change-parameters updates the store metadata database even if the component is not available. The component's configuration will be made consistent when the KVStore system detects an inconsistency.

kv-> plan change-parameters -service rg1-rn2 -json -wait -params
loggingConfigProps="oracle.kv.level=DEBUG"
{
	"operation" : "Change RepNode Params",
	"returnCode" : 5000,
	"description" : "Operation ends successfully",
	"returnValue" : {
		"id" : 20,
		"owner" : "root(id:u1)",
		"name" : "Change RepNode Params",
		"isDone" : true,
		"state" : "SUCCEEDED",
		"start" : "2017-09-28 05:31:05 UTC",
		"interrupted" : null,
		"end" : "2017-09-28 05:31:10 UTC",
		"error" : null,
		"executionDetails" : {
			"taskCounts" : {
				"total" : 4,
				"successful" : 4,
				"failed" : 0,
				"interrupted" : 0,
				"incomplete" : 0,
				"notStarted" : 0
			},
		"finished" : [ {
			"taskNum" : 1,
			"name" : "Plan 20 [Change RepNode Params] task [WriteNewParams rg1-rn2]",
			"state" : "SUCCEEDED",
			"start" : "2017-09-28 05:31:05 UTC",
			"end" : "2017-09-28 05:31:06 UTC"
		}, {
			"taskNum" : 2,
			"name" : "Plan 20 [Change RepNode Params] task [StopNode rg1-rn2]",
			"state" : "SUCCEEDED",
			"start" : "2017-09-28 05:31:06 UTC",
			"end" : "2017-09-28 05:31:07 UTC"
		}, {
			"taskNum" : 3,
			"name" : "Plan 20 [Change RepNode Params] task [StartNode]",
			"state" : "SUCCEEDED",
			"start" : "2017-09-28 05:31:07 UTC",
			"end" : "2017-09-28 05:31:07 UTC"
		}, {
			"taskNum" : 4,
			"name" : "Plan 20 [Change RepNode Params] task [WaitForNodeState rg1-rn2 to reach RUNNING]",
			"state" : "SUCCEEDED",
			"start" : "2017-09-28 05:31:07 UTC",
			"end" : "2017-09-28 05:31:10 UTC"
		} ],
		"running" : [ ],
		"pending" : [ ]
		}
	}
}

plan change-storagedir

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

Adds or removes a storage directory on a Storage Node, for storing a Replication Node.

where:

-sn

Specifies the Storage Node where the storage directory is added or removed.
-storagedir

Specifies the path to the storage directory on a Storage Node for storing a Replication Node.
-add | -remove

Specifies to add (-add) the storage dir.

Specifies to remove (-remove) the storage dir.

-storagedirsize

Specifies the size of the directory specified in -storagedir. This parameter is optional; however, it is an error to specify this parameter for some, but not all, storage directories.

Use of this parameter is recommended for heterogeneous installation environments where some hardware has more storage capacity than other hardware. If this parameter is specified for all storage directories, then the store's topology will place more data on the shards that offer more storage space. If this parameter is not used, then data is spread evenly across all shards.

The value specified for this parameter must be a long, optionally followed by a unit string. Accepted unit strings are: KB, MB, GB, and TB, corresponding to 1024, 1024^2, 1024^3, 1024^4 respectively. Acceptable strings are case insensitive. Valid delimiters between the long value and the unit string are " ", "-", or "_".

-storagedirsize 200 MB
-storagedirsize 4_tb
-storagedirsize 5000-Mb

kv-> plan change-storagedir -sn sn2 -storagedir /tmp/kvroot -add -json -wait
{
"operation" : "Change Storage Node Params",
"returnCode" : 5000,
"description" : "Operation ends successfully",
"returnValue" : {
	"id" : 21,
	"owner" : "root(id:u1)",
	"name" : "Change Storage Node Params",
	"isDone" : true,
	"state" : "SUCCEEDED",
	"start" : "2017-09-28 05:33:14 UTC",
	"interrupted" : null,
	"end" : "2017-09-28 05:33:14 UTC",
	"error" : null,
	"executionDetails" : {
		"taskCounts" : {
		"total" : 1,
		"successful" : 1,
		"failed" : 0,
		"interrupted" : 0,
		"incomplete" : 0,
		"notStarted" : 0
	},
	"finished" : [ {
		"taskNum" : 1,
		"name" : "Plan 21 [Change Storage Node Params] task [WriteNewSNParams sn2]",
		"state" : "SUCCEEDED",
		"start" : "2017-09-28 05:33:14 UTC",
		"end" : "2017-09-28 05:33:14 UTC"
	} ],
"running" : [ ],
"pending" : [ ]
		}
	}
}

plan change-user

plan change-user -name <user name>
    [-disable | -enable] [-set-password [-password <new password>]
    [-retain-current-password]] [-clear-retained-password]
    [-plan-name <name>] [-wait] [-noexecute] [-force]

Change a user with the specified name in the store. The -retain-current-password argument option causes the current password to be remembered during the -set-password operation as a valid alternate password for configured retention time or until cleared using -clear-retained-password. If a retained password has already been set for the user, setting password again will cause an error to be reported.

This command is deprecated. For more information see User Modification in the Security Guide.

plan create-user

plan create-user -name <user name>
    [-admin] [-disable] [-password <new password>]
    [-plan-name <name>] [-wait] [-noexecute] [-force]

Create a user with the specified name in the store. The -admin argument indicates that the created user has full administrative privileges.

This command is deprecated. For more information, see User Creation in the Security Guide.

plan deploy-admin

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

Deploys an Admin to the specified Storage Node. The admin type (PRIMARY/SECONDARY) is the same type as the zone the Storage Node is in.

For more information on deploying an admin, see Create an Administration Process on a Specific Host.

kv-> plan deploy-admin -sn sn1 -json -wait
"operation" : "plan deploy-admin -sn 1",
"returnCode" : 5000,
"description" : "Operation ends successfully",
"returnValue" : {
	"id" : 22,
	"owner" : "root(id:u1)",
	"name" : "Deploy Admin Service",
	"isDone" : true,
	"state" : "SUCCEEDED",
	"start" : "2017-09-28 05:34:26 UTC",
	"interrupted" : null,
	"end" : "2017-09-28 05:34:27 UTC",
	"error" : null,
	"executionDetails" : {
		"taskCounts" : {
			"total" : 4,
			"successful" : 4,
			"failed" : 0,
			"interrupted" : 0,
			"incomplete" : 0,
			"notStarted" : 0
		},
	"finished" : [ {
			"taskNum" : 1,
			"name" : "Plan 22 [Deploy Admin Service] task [DeployAdmin admin1 on sn1]",
			"state" : "SUCCEEDED",
			"start" : "2017-09-28 05:34:26 UTC",
			"end" : "2017-09-28 05:34:27 UTC"
		}, {
			"taskNum" : 2,
			"name" : "Plan 22 [Deploy Admin Service] task [WaitForAdminState admin1 to reach RUNNING]",
			"state" : "SUCCEEDED",
			"start" : "2017-09-28 05:34:27 UTC",
			"end" : "2017-09-28 05:34:27 UTC"
		}, {
			"taskNum" : 3,
			"name" : "Plan 22 [Deploy Admin Service] task [UpdateAdminHelperHost admin1]",
			"state" : "SUCCEEDED",
			"start" : "2017-09-28 05:34:27 UTC",
			"end" : "2017-09-28 05:34:27 UTC"
		}, {
			"taskNum" : 4,
			"name" : "Plan 22 [Deploy Admin Service] task [NewAdminParameters refresh admin1 parameter state
			without restarting]",
			"state" : "SUCCEEDED",
			"start" : "2017-09-28 05:34:27 UTC",
			"end" : "2017-09-28 05:34:27 UTC"
		} ],
	"running" : [ ],
	"pending" : [ ]
	},
	"planId" : 22,
	"resourceId" : "admin1",
	"snId" : "sn1"
	}
}

plan deploy-datacenter

Deprecated. See plan deploy-zone instead.

plan deploy-sn

plan deploy-sn -zn <id> | -znname <name> -host <host> -port <port>
    [-plan-name <name>] [-json] [-wait] [-noexecute] [-force]

Deploys the Storage Node at the specified host and port into the specified zone.

where:

-sn

Specifies the Storage Node to deploy.
-zn <id> | -znname <name>

Specifies the Zone where the Storage Node is going to be deployed.
-host

Specifies the host name where the Storage Node is going to be deployed.
-port

Specifies the port number of the host.

For more information on deploying your Storage Nodes, see Create the Remainder of your Storage Nodes.

kv-> plan deploy-sn -zn 1 -json -host localhost -port 10000 -wait
{
"operation" : "plan deploy-sn -zn 1 -host localhost -port 10000",
"returnCode" : 5000,
"description" : "Operation ends successfully",
"returnValue" : {
	"id" : 25,
	"owner" : "root(id:u1)",
	"name" : "Deploy Storage Node",
	"isDone" : true,
	"state" : "SUCCEEDED",
	"start" : "2017-09-28 05:40:50 UTC",
	"interrupted" : null,
	"end" : "2017-09-28 05:40:51 UTC",
	"error" : null,
	"executionDetails" : {
		"taskCounts" : {
			"total" : 1,
			"successful" : 1,
			"failed" : 0,
			"interrupted" : 0,
			"incomplete" : 0,
			"notStarted" : 0
		},
	"finished" : [ {
		"taskNum" : 1,
		"name" : "Plan 25 [Deploy Storage Node] task [DeploySN sn4(localhost:10000)]",
		"state" : "SUCCEEDED",
		"start" : "2017-09-28 05:40:50 UTC",
		"end" : "2017-09-28 05:40:51 UTC"
		} ],
	"running" : [ ],
	"pending" : [ ]
	},
	"planId" : 25,
	"resourceId" : "sn4",
	"zoneId" : "zn1",
	"host" : "localhost",
	"port" : 10000
	}
}

plan deploy-topology

plan deploy-topology -name <topology name> [-plan-name <name>]
    [-json] [-wait] [-noexecute] [-force]

Deploys the specified topology to the store. The KVStore size determines how long the command takes to deploy replication and arbiter nodes to become fully functional shard members. The plan deploy-topology command does not wait for this command to finish.

After running the plan deploy-topology command, use the verify configuration command to check the running state of the components in the topology. See Deploy the Topology Candidate.

kv-> plan deploy-topology -name MyStoreLayout -json -wait
{
"operation" : "plan deploy-topology -name MyStoreLayout",
"returnCode" : 5000,
"description" : "Operation ends successfully",
"returnValue" : {
	"id" : 26,
	"owner" : "root(id:u1)",
	"name" : "Deploy Topo",
	"isDone" : true,
	"state" : "SUCCEEDED",
	"start" : "2017-09-28 05:56:25 UTC",
	"interrupted" : null,
	"end" : "2017-09-28 05:56:26 UTC",
	"error" : null,
	"executionDetails" : {
	"taskCounts" : {
	"total" : 6,
	"successful" : 6,
	"failed" : 0,
	"interrupted" : 0,
	"incomplete" : 0,
	"notStarted" : 0
	},
"finished" : [ {
	"taskNum" : 1,
	"name" : "Plan 26 [Deploy Topo] task [UpdateDatacenterV2 zone=zn1]",
	"state" : "SUCCEEDED",
	"start" : "2017-09-28 05:56:25 UTC",
	"end" : "2017-09-28 05:56:25 UTC"
	}, {
	"taskNum" : 2,
	"name" : "Plan 26 [Deploy Topo] task [UpdateDatacenterV2 zone=zn2]",
	"state" : "SUCCEEDED",
	"start" : "2017-09-28 05:56:25 UTC",
	"end" : "2017-09-28 05:56:25 UTC"
	}, {
	"taskNum" : 3,
	"name" : "Plan 26 [Deploy Topo] task [UpdateDatacenterV2 zone=zn3]",
	"state" : "SUCCEEDED",
	"start" : "2017-09-28 05:56:25 UTC",
	"end" : "2017-09-28 05:56:25 UTC"
	}, {
	"taskNum" : 4,
	"name" : "Plan 26 [Deploy Topo] task [BroadcastTopo]",
	"state" : "SUCCEEDED",
	"start" : "2017-09-28 05:56:25 UTC",
	"end" : "2017-09-28 05:56:26 UTC"
	}, {
	"taskNum" : 5,
	"name" : "Plan 26 [Deploy Topo] task [BroadcastMetadata]",
	"state" : "SUCCEEDED",
	"start" : "2017-09-28 05:56:26 UTC",
	"end" : "2017-09-28 05:56:26 UTC"
	}, {
	"taskNum" : 6,
	"name" : "Plan 26 [Deploy Topo] task [BroadcastTopo]",
	"state" : "SUCCEEDED",
	"start" : "2017-09-28 05:56:26 UTC",
	"end" : "2017-09-28 05:56:26 UTC"
	} ],
	"running" : [ ],
	"pending" : [ ]
	},
	"planId" : 26,
	"topoName" : "MyStoreLayout"
	}
}

plan deploy-zone

plan deploy-zone -name <zone name>
    -rf <replication factor>
    [-type [primary | secondary]]
    [-arbiters | -no-arbiters]
    [-json ]
    [–master-affinity | –no-master-affinity]
    [-plan-name <name>] [-wait] [-noexecute] [-force]

Deploys the specified zone to the store and creates a primary zone if you do not specify a -type.

where:

-name

Specifies the name of the zone to deploy.
-rf

Specifies the replication factor of the zone.
-type

Specifies the type of the zone to deploy. It can be a primary or a secondary zone. If -type is not specified, a primary zone is deployed.
-json

Formats the command output in JSON.
-arbiters | -no-arbiters

If you specify -arbiters, you can allocate Arbiter Nodes on the Storage Node in the zone. You can specify this flag only on a primary zone.
Specifying -no-arbiters precludes allocating Arbiter Nodes on the Storage Node in the zone.
The default value is -no-arbiters.
-master—affinity | -no-master-affinity

Specifying -master-affinity indicates that this zone can host a master.
Specifying -no-master-affinity indicates that this zone cannot host a master.
The default value is -no-master-affinity.

For more information on creating a zone, see Create a Zone.

kv-> plan deploy-zone -name zn6 -rf 1 -json -wait
{
	"operation" : "plan deploy-zone -name zn6 -rf 1 -type PRIMARY -no-arbiters -no-master-affinity",
	"returnCode" : 5000,
	"description" : "Operation ends successfully",
	"returnValue" : {
		"id" : 27,
		"owner" : "root(id:u1)",
		"name" : "Deploy Zone",
		"isDone" : true,
		"state" : "SUCCEEDED",
		"start" : "2017-09-28 05:57:29 UTC",
		"interrupted" : null,
		"end" : "2017-09-28 05:57:29 UTC",
		"error" : null,
		"executionDetails" : {
			"taskCounts" : {
			"total" : 1,
			"successful" : 1,
			"failed" : 0,
			"interrupted" : 0,
			"incomplete" : 0,
			"notStarted" : 0
		},
	"finished" : [ {
		"taskNum" : 1,
		"name" : "Plan 27 [Deploy Zone] task [DeployDatacenter zone=zn6]",
		"state" : "SUCCEEDED",
		"start" : "2017-09-28 05:57:29 UTC",
		"end" : "2017-09-28 05:57:29 UTC"
		} ],
		"running" : [ ],
		"pending" : [ ]
		},
	"planId" : 27,
	"zoneName" : "zn6",
	"zoneId" : "zn4",
	"type" : "PRIMARY",
	"rf" : 1,
	"allowArbiters" : false,
	"masterAffinity" : false
	}
}

plan deregister-es

plan deregister-es

Deregisters the Elasticsearch cluster from the Oracle NoSQL Database store, using the deregister-es plan command. This is allowed only if all full text indexes are first removed using the plan remove-index command, see plan remove-index.

For example:

kv-> plan deregister-es
Cannot deregister ES because these text indexes exist:
mytestIndex
JokeIndex

For more information, see Integration with Elastic Search for Full Text Search in the Integrations Guide.

plan drop-user

plan drop-user -name <user name>
    [-plan-name <name>] [-wait] [-noexecute] [-force]

Drop a user with the specified name in the store. A logged-in user may not drop itself.

This command is deprecated. For more information, see User Removal in the Security Guide.

plan enable-requests

This command will change the type of user requests supported by a set of shards or the entire store.

plan enable-requests 
    -request-type {all|readonly|none} 
    {-shards <shardId[,shardId]*> | -store} 
    [-plan-name <name>] [-wait] 
    [-noexecute] [-force] 
    [-json|-json-v1]

Limit the type of requests enabled for specific shards or the whole store.

The -request-type flag configures the read and write requests. The following request types can be configured by this command.

all means the store or shards can process both read and write requests;
readonly makes the store or shards only respond to read requests;
none means no read or write requests will be processed by the store or shards.

The -shards flag specifies the list of shards that should be configured, if you want the configuration to be done on one or more shards. You can get details about the shardid by executing the show topology command. The rgXX portion in the show topology output denotes the shardid. See show topology.

The -store flag specifies that the configuration to be done on the entire store.

You should specify either the -shard flag or the -store flag.

Example B-1 plan enable-requests

For example, If you want to put the shard rg1 in readonly mode, you would specify rg1 as the shardid and readonly as the request-type.

kv-> plan enable-requests 
    -request-type readonly -shards rg1
Started plan 25. Use show plan -id 25 to check status.
    To wait for completion, use plan wait -id 25

Example B-2 plan enable-requests

For example, If you want to put the whole store in readonly mode and to get the output in json format, you would specify the store attribute, request-type attribute as readonly and json attribute.

kv-> plan enable-requests 
    -request-type readonly -store -json
{
  "operation" : "plan enable-requests",
  "returnCode" : 5000,
  "description" : "Operation ends successfully",
  "returnValue" : {
    "planId" : 26
  }
}

Example B-3 plan enable-requests

For example, If you want to put the whole store in readonly mode and to get the output in json v1 format, you would specify the store attribute, request-type attribute as readonly and json-v1 attribute.

kv-> plan enable-requests 
    -request-type readonly -store -json-v1
{
  "operation" : "plan enable-requests",
  "return_code" : 5000,
  "description" : "Operation ends successfully",
  "return_value" : {
    "plan_id" : 27
  }
}

plan evolve-table

plan evolve-table -name <name>
    [-plan-name <name>] [-wait] [-noexecute] [-force]

Evolves a table in the store. The table name is a dot-separate with the format tableName[.childTableName]*.

Use the table evolve command to evolve the named table. The following example evolves a table.

## Enter into table evolution mode
kv-> table evolve -name User
kv-> show
{
  "type" : "table",
  "name" : "User",
  "id" : "r",
  "description" : "A sample user table",
  "shardKey" : [ "id" ],
  "primaryKey" : [ "id" ],
  "fields" : [ {
    "name" : "id",
    "type" : "INTEGER"
  }, {
    "name" : "firstName",
    "type" : "STRING"
  }, {
    "name" : "lastName",
    "type" : "STRING"
  } ]
}
## Add a field
kv-> add-field -type String -name address
## Exit table creation mode
kv-> exit
## Table User built.
kv-> plan evolve-table -name User -wait
## Executed plan 6, waiting for completion...
## Plan 6 ended successfully
kv-> show tables -name User
{
  "type" : "table",
  "name" : "User",
  "id" : "r",
  "description" : "A sample user table",
  "shardKey" : [ "id" ],
  "primaryKey" : [ "id" ],
  "fields" : [ {
    "name" : "id",
    "type" : "INTEGER"
  }, {
    "name" : "firstName",
    "type" : "STRING"
  }, {
    "name" : "lastName",
    "type" : "STRING"
  }, {
    "name" : "address",
    "type" : "STRING"
  } ]
}

Use table list -evolve to see the list of tables that can be evolved. For more information, see plan add-table .

plan execute

plan execute -id <id> | -last
    [-plan-name <name>] [-json] [-wait] [-noexecute] [-force]

Executes an existing plan that has not yet been executed. The plan must have been previously created using the -noexecute flag .

Use the -last option to reference the most recently created plan.

kv-> plan execute -id 19 -json -wait
{
	"operation" : "plan deploy-zone -name zn6 -rf 1 -type PRIMARY -no-arbiters -no-master-affinity",
	"returnCode" : 5000,
	"description" : "Operation ends successfully",
	"returnValue" : {
		"id" : 19,
		"name" : "Deploy Zone",
		"isDone" : true,
		"state" : "SUCCEEDED",
		"start" : "2017-09-28 09:35:31 UTC",
		"interrupted" : null,
		"end" : "2017-09-28 09:35:31 UTC",
		"error" : null,
		"executionDetails" : {
			"taskCounts" : {
			"total" : 1,
			"successful" : 1,
			"failed" : 0,
			"interrupted" : 0,
			"incomplete" : 0,
			"notStarted" : 0
		},
	"finished" : [ {
		"taskNum" : 1,
		"name" : "Plan 19 [Deploy Zone] task [DeployDatacenter zone=zn6]",
		"state" : "SUCCEEDED",
		"start" : "2017-09-28 09:35:31 UTC",
		"end" : "2017-09-28 09:35:31 UTC"
} ],
"running" : [ ],
"pending" : [ ]
},
"planId" : 19,
"zoneName" : "zn6",
"zoneId" : "zn4",
"type" : "PRIMARY",
"rf" : 1,
"allowArbiters" : false,
"masterAffinity" : false
}
}

plan failover

plan failover  { [-zn <zone-id> | -znname <zone-name>]
    -type [primary | offline-secondary] }...
    [-plan-name <name>] [-wait] [-noexecute] [-force]

where:

-zn <zone-id> | -znname <zone-name>

Specifies a zone either by zone ID or by name.
-type [primary | offline-secondary]

Specifies the new type for the associated zone.

Changes zone types to failover to either Primary or Secondary zones, whenever a primary zone failure results in a loss of quorum. Arbiters will not be created or removed from the topology. This command can introduce violations if a zone that contains Arbiters is specified as secondary-offline. Use the force flag if arbiter violations are introduced.

Zones whose new type is primary are taking over from failed primary zones to reestablish quorum. For these zones, a quorum of storage nodes in each shard in the zone must be available and responding to requests.

Zones whose new type is offline-secondary represent primary zones that are currently offline, resulting in the current loss of quorum. For these zones, all of the storage nodes in the zones must currently be unavailable. No zone type changes can be performed if these requirements are not met when the command starts.

Note:

Arbiter nodes are not currently supported during failover and switchover operations.

To correct any violations after the topology components are repaired, the plan failover command executes a rebalance command. To successfully deploy the new topology after a rebalance, the Storage Nodes hosting topology components must be running. If a Storage Node in a zone that failed over to a Secondary zone that contained an Arbiter, when the SN restarts, the Arbiter rejoins the shard.

You cannot execute this command when other plans are in progress for the data store. Before executing this plan, cancel or interrupt any other plans.

plan grant

plan grant [-role <role name>]* -user <user_name>

Allows granting roles to users.

where:

-role <role name>

Specifies the roles that will be granted. The role names should be the system-defined roles (except public) listed in the Security Guide.
-user <user_name>

Specifies the user who the role will be granted from.

This command is deprecated. For more information see Grant Roles or Privileges in the Security Guide.

plan interrupt

plan interrupt -id <plan id> | -last [-json]

Interrupts a running plan. An interrupted plan can only be re-executed or canceled. Use -last to reference the most recently created plan.

kv-> plan interrupt -id 20 -json
{
"operation" : "plan cancel|interrupt",
"returnCode" : 5000,
"description" : "Plan 20 was interrupted",
"returnValue" : null
}

plan migrate-sn

plan migrate-sn -from <id> -to <id> 
    [-plan-name <name>] [-wait] [-noexecute] [-force]

Migrates the services from one Storage Node to another. The old node must not be running.

where:

-from

Specifies the Storage Node (old) that you are migrating from.
-to

Specifies the Storage Node (new) that you are migrating to.

For example, assuming that you are migrating from Storage Node 25 to 26, you would use:

kv-> plan migrate-sn -from sn25 -to sn26

Before executing the plan migrate-sn command, you can stop any running old Storage Node by using -java -Xmx64m -Xms64m -jar KVHOME/lib/kvstore.jar stop -root KVROOT.

plan network-restore

plan network-restore -from <id> -to <id> -retain-logs 
    [-plan-name <name>] [-wait] [-noexecute] [-force] [-json|-json-v1]

The plan network-restore command restores a replication node (RN) with updates that the RN missed after losing networking connectivity. Use this only if the RN cannot be restored through the automatic procedures described here.

When a replication node becomes disconnected for any reason, it misses updates that occur while it was not connected. Oracle NoSQL Database uses two ways to update the recovered RN after it comes back online.

One way occurs within the RN's replication group. When the recovered RN returns, the replication group's master node streams all missed updates from the time the time the RN became disconnected, to the time it resumed operations.

Another way to restore a reconnected RN is over a network connection. Performing a network restore copies a complete set of data log files (*.jdb) from a peer, supplying the recovered RN with a comprehensive data set. The content contains many intermediate changes that are not reflected in the current store contents. This is because the data log files (*.jdb), which the recipient RN ingests, contain all changes, including any intermediate ones.

Do not confuse the data *.jdb log files, which contain data store activities, with the debug log files (*.log), which are used for debugging purposes.

If neither of the automatic Oracle NoSQL Database RN repopulation attempts succeed, it can be due to unforeseen circumstances, or a catastrophic situation that destroys data on multiple hosts. In this case, you can execute plan network-restore manually from the Admin CLI. However, doing so requires you to specify the RN that will supply the updated data.

You can attempt a network restore using the plan network-restore command from the admin CLI:

kv-> plan network-restore -help 
Usage: plan network-restore -from <id> -to <id> [-retain-logs] \
[-plan-name <name>] [-wait] [-noexecute] [-force] [-json | json-v1] 
Network restore a RepNode from another one in their replication group.

where:

-from flag – Specifies the Replication Node ID from the same replication group (matching rgX). The -from node must be fully up to date, and able to supply the *.dbd log files to the destination RN. For example, if the -to recipient RN ID is rg1-rn3, and the ping output shows that rg1-rn2 is the master, then that ID (rg1-rn2) is a good choice for the -from value.
-to flag – Specifies the ID (rgX-rnY) of the recipient RN.
-retain-logs flag – Retains obsolete log files on the lagging replica. The system renames the files, rather than deleting them. It is generally unnecessary to use this flag, unless you suspect that log files are corrupted on the recovering RN.

plan register-es

plan register-es -clustername <name> -host <host>
    -port <transport port> [-force]

Registers the Elasticsearch cluster with the Oracle NoSQL Database store, using the register-es plan command. It is only necessary to register one node of the cluster, as the other nodes in the cluster will be found automatically.

where:

-clustername

Specifies the name of the Elasticsearch cluster.
-host

Specifies the host name of a node in the cluster.
-port

Specifies the transport port of a node in the cluster.

For more information, see Integration with Elastic Search for Full Text Searchin the Integrations Guide.

plan remove-admin

plan remove-admin -admin <id> | -zn <id> | -znname <name>
    [-plan-name <name>] [-wait] [-noexecute] [-force]

Removes the desired Admin instances; either the single specified instance, or all instances deployed to the specified zone.

If you use the -admin flag and there are 3 or fewer Admins running in the store, or if you use the -zn or -znname flag and the removal of all Admins from the specified zone would result in only one or two Admins in the store, then the desired Admins will be removed only if you specify the -force flag.

Also, if you use the -admin flag and there is only one Admin in the store, or if you use the -zn or -znname flag and the removal of all Admins from the specified zone would result in the removal of all Admins from the store, then the desired Admins will not be removed.

plan remove-datacenter

plan remove-datacenter

This command is deprecated. See plan remove-zone instead.

plan remove-index

plan remove-index -name <name> -table <name>
    [-plan-name <name>] [-wait] [-noexecute] [-force]

Removes an index from a table.

where:

-name

Specifies the name of the index to remove.
-table

Specifies the table name to remove the index from. The table name is a dot-separated name with the format tableName[.childTableName]*.

plan remove-sn

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

Removes the specified Storage Node from the topology. The Storage Node is automatically stopped before removal.

This command is useful when removing unused, old Storage Nodes from the store. To do this, see Replacing a Failed Storage Node.

If the Storage Node is being removed as part of removing a secondary zone then,

any replication nodes must first be removed using the topology change-replication-factor and plan deploy-topology commands, and
any Admin Nodes must first be removed using plan remove-admin command.

plan remove-table

plan remove-table -name <name> [-keep-data]
    [-plan-name <name>] [-wait] [-noexecute] [-force]

Removes a table from the store. The named table must exist and must not have any child tables. Indexes on the table are automatically removed. By default data stored in this table is also removed. Table data may be optionally saved by specifying the -keep-data flag. Depending on the indexes and amount of data stored in the table this may be a long-running plan.

The following example removes a table.

## Remove a table.
kv-> plan remove-table -name User
## Started plan 7. Use show plan -id 7 to check status.
## To wait for completion, use plan wait -id 7.
kv-> show tables
## No table found.

plan remove-zone

plan remove-zone -zn <id> | -znname <name>
    [-plan-name <name>] [-wait] [-noexecute] [-force]

Removes the specified zone from the store.

Before running this command, all Storage Nodes that belong to the specified zone must first be removed using the plan remove-sn command.

plan repair-topology

plan repair-topology
    [-plan-name <name>] [-wait] [-json] [-noexecute] [-force]

Inspects the store's deployed, current topology for inconsistencies in location metadata that may have arisen from the interruption or cancellation of previous deploy-topology or migrate-sn plans. Where possible, inconsistencies are repaired. This operation can take a while, depending on the size and state of the store.

kv-> plan repair-topology -json -wait
{
"operation" : "Repair Topology",
"returnCode" : 5000,
"description" : "Operation ends successfully",
"returnValue" : {
	"id" : 25,
	"name" : "Repair Topology",
	"isDone" : true,
	"state" : "SUCCEEDED",
	"start" : "2017-09-28 09:43:06 UTC",
	"interrupted" : null,
	"end" : "2017-09-28 09:43:06 UTC",
	"error" : null,
	"executionDetails" : {
		"taskCounts" : {
		"total" : 1,
		"successful" : 1,
		"failed" : 0,
		"interrupted" : 0,
		"incomplete" : 0,
		"notStarted" : 0
		},
	"finished" : [ {
		"taskNum" : 1,
		"name" : "Plan 25 [Repair Topology] task [VerifyAndRepair]",
		"state" : "SUCCEEDED",
		"start" : "2017-09-28 09:43:06 UTC",
		"end" : "2017-09-28 09:43:06 UTC"
	} ],
	"running" : [ ],
	"pending" : [ ]
	}
	}
}

plan revoke

plan revoke [-role <role name>]* -user <user_name>

Allows revoking roles to users.

where:

-role <role name>

Specifies the roles that will be revoked. The role names should be the system-defined roles (except public) listed in the Security Guide.
-user <user_name>

Specifies the user who the role will be revoked from.

This command is deprecated. For more information see Revoke Roles or Privileges in the Security Guide.

plan start-service

plan start-service {-service <id> | -all-rns [-zn <id> |
    -znname <name>] | -all-ans [-zn <id> | -znname <name>] |
    -zn <id> | -znname <name> } [-plan-name <name>]
    [-json] [-wait] [-noexecute] [-force]

Starts the specified service(s). The service may be a Replication Node, an Arbiter Node, or Admin service, as identified by any valid string.

For example, to identify a Replication Node, use -service shardId-nodeId, where shardId-nodeId must be given as a single argument with one embedded hyphen and no spaces. The shardId identifier is represented by rgX, where X refers to the shard number.

where:

-service

Specifies the name of the service to start.
-all-rns

If specified, starts the services of all Replication Nodes in a store.
-all-ans

If specified, starts all the Arbiter Nodes in the specified zone.

Note:

This plan cannot be used to start a Storage Node. Further, you cannot restart the Storage Node's services without first starting the Storage Node itself. To start the Storage Node, go to the Storage Node host and enter the following command:

nohup java -Xmx64m -Xms64m \
-jar <KVHOME>/lib/kvstore.jar start -root <KVROOT> & 

kv-> plan start-service -service rg1-rn3 -json -wait
{
	"operation" : "Start Services",
	"returnCode" : 5000,
	"description" : "Operation ends successfully",
	"returnValue" : {
		"id" : 21,
		"name" : "Start Services",
		"isDone" : true,
		"state" : "SUCCEEDED",
		"start" : "2017-09-28 09:50:54 UTC",
		"interrupted" : null,
		"end" : "2017-09-28 09:50:57 UTC",
		"error" : null,"executionDetails" : {
		"taskCounts" : {
			"total" : 2,
			"successful" : 2,
			"failed" : 0,
			"interrupted" : 0,
			"incomplete" : 0,
			"notStarted" : 0
		},
	"finished" : [ {
		"taskNum" : 1,
		"name" : "Plan 21 [Start Services] task [StartNode]",
		"state" : "SUCCEEDED",
		"start" : "2017-09-28 09:50:54 UTC",
		"end" : "2017-09-28 09:50:55 UTC"
		}, {
	"taskNum" : 2,
	"name" : "Plan 21 [Start Services] task [WaitForNodeState rg1-rn3 to reach RUNNING]",
	"state" : "SUCCEEDED",
	"start" : "2017-09-28 09:50:55 UTC",
	"end" : "2017-09-28 09:50:57 UTC"
		} ],
	"running" : [ ],
	"pending" : [ ]
		}
	}
}

plan stop-service

plan stop-service {-service <id> |
    -all-rns [-zn <id> | -znname <name>] | -all-ans [-zn <id> |
    -znname <name>] | -zn <id> | -znname <name> }
    [-plan-name <name>] [-json] [-wait] [-noexecute] [-force]

Stops the specified service(s). The service may be a Replication Node, an Arbiter Node, or Admin service as identified by any valid string.

For example, to identify a Replication Node, use -service shardId-nodeId, where shardId-nodeId must be a single string with an embedded hyphen (-) and no spaces. The shardId identifier is represented as rgX, where X represents the shard number.

Other options to specify after -service include:

-all-rns

Stops the services of all Replication Nodes in a store.
-all-ans

Stops the services of all Arbiter Nodes in the specified zone.

Use this command to stop any affected services so that any attempts by the system to communicate with the services are no longer accepted. Stopping communication to one or more services reduces the amount of error output about a failure you are already aware of.

Whenever you execute the plan stop-service command, the system automatically initiates a health check. The health check determines if stopping an indicated service will result in losing quorum. There are no further checks performed, only whether quorum will be lost if you stop the service. To avoid losing quorum, the plan stop-service fails to execute if the health check fails, and outputs detailed health check information such as the following:

One of the groups is not healthy enough for the operation:
[rg1] Only 1 primary nodes are running such that a simple 
majority cannot be formed which requires 2 primary nodes. 
The shard is vulnerable and will not be able to elect a new master. 
Nodes not running: [rg1-rn1]. Nodes to stop: {rg1=[rg1-rn2]}
...

If you cannot stop a service because it will result in lost quorum, you should determine what problem is occurring before trying to stop the service.

If, on the other hand, you understand that stopping a service will result in losing quorum, but such an event is necessary to make some important change, you can force the plan stop-service command to execute by appending the -force flag.

Note:

If you forcefully stop the Admin service and Admin quorum is lost, you cannot use the start-service plan to bring up the Admin services anymore. All plan operations will also fail thereafter.

The plan stop-service command is also useful during disk replacement process. Use the command to stop the affected service prior removing the failed disk. For more information, see Replacing a Failed Disk.

Note:

This plan cannot be used to stop a Storage Node. To stop a Storage Node, first stop all services running on it. Then, find the ID of the Storage Node process by going to the Storage Node host and issuing this command:
```
ps -af | grep -e "kvstore.jar.*start.*<KVROOT>"
```
Kill the process using:
```
kill <storage node id>
```
Also, because the plan stop-service -all-rns command always results in losing quorum, executing plan stop-service with this option skips running a health check. Further, you do not need to use the -force flag is when using the -all-rns option.

plan verify-data


plan verify-data 
    [-verify-log <enable|disable> [-log-read-delay <milliseconds>]]
    [-verify-btree <enable|disable> [-btree-batch-delay <milliseconds>]
        [-index <enable|disable>] [-datarecord <enable|disable>]]
    [-valid-time <time>]
    [-show-corrupt-files <enable|disable>]
    -service <id> | -all-services [-zn <id> | -znname <name>] |
    -all-rns [-zn <id> | -znname <name>] |
    -all-admins [-zn <id> | -znname <name>]
    [-plan-name <name>] [-wait] [-noexecute] [-force] [-json|-json-v1]

Verifies and controls certain elements (such as log files and indexes), as presented in this section. Here is a description for each of the verify-data parameters and options:

Option	Description
`-verify-log`	Verifies the checksum of each data record in the JE log file of JE. The Berkeley DB Java Edition (JE) is the data storage engine of Oracle NoSQL Database. It is enabled by default.
`-log-read-delay`	Configures the delay time between file reads. The default value is 100 milliseconds.
`-verify-btree`	Verifies that the B-tree of the database in memory contains a valid reference to each data record on disk. You can combine `-verify-btree` with `-datarecord` and `-index`. It is enabled by default.
`-btree-batch-delay`	Configures the delay time, in milliseconds, between batches. The default delay value is 10 milliseconds.
`-datarecord`	Reads and verifies data records from disk, if the data record is not in cache. The `-datarecord` option takes longer than verifying records only in cache, and results in more read I/O. It is disabled by default.
`-index`	Verifies indexes. Using the `-index` option alone verifies only the reference from the index to the primary table, not the reference from the primary table to index. To verify both references from index to primary table, and primary table to index, specify the `-datarecord` and `-index` options. It is enabled by default.
`-valid-time`	Specifies the amount of time for which an existing verification will be considered valid and not be rerun. The format is 'number unit' where the unit can be minutes or seconds. The unit is case insensitive and can be separated from the number by a space, "-" or "_". The default is '10 minutes'.
`-show-corrupt-files`	Specifies whether to show corrupt files, including missing files and reserved files that are referenced. It is disabled by default.
`-service id`	Runs verification on the specified service (id)
`-all-services [-zn id \| -znname name]`	Runs verification on all services, both RNs and Admins, in the specified zone, or in all zones if none is specified.
`\| -all-rns [-zn id \| -znname name]`	Runs verification on all RNs in the specified zone, or in all zones if none is specified.
`\| -all-admins [-zn id \| -znname name]`	Runs verification on all Admins in the specified zone, or in all zones if none is specified.
`[-plan-name name]`	Runs the named plan that you have saved to execute `plan verify-data` and its available options.
`[-wait]`	Runs a plan synchronously, so that the command line prompt returns after the command completes.
`[-noexecute]`	Lets you create a plan but delay its execution. Conversely, use the `plan execute` command to run the plan.
`[-force]`	Runs the plan as you enter it on the CLI, without validating the flags.
`[-json\|-json-v1]`	Displays the plan output as json or json-v1.

Executing verify-data

The plan verify-data command is available to verify both primary table and secondary indexes. The command lets you verify either a checksum of data records, or the B-tree of the database.

Note:

Since Oracle NoSQL Database uses Oracle Berkeley DB Java Edition (JE) as its underlying storage engine, verifying data using plan verify-data depends on several low-level JE features that are neither described here, nor visible. Throughout this section, terms or concepts related to Oracle Berkeley DB Java Edition (JE) are indicated by the term Berkeley, indicating their origination. For more information about Oracle Berkeley DB Java Edition, start here: Oracle Berkeley DB Java Edition.

The plan verify-data has two parts for verifications:

Log record integrity on disk
B-tree integrity

To verify the integrity of log records on disk, verify-data accesses and verifies each record's checksum. Since this procedure includes disk reads, it consumes I/O resources and is relatively time consuming. To reduce the performance effects of verification, you can configure a longer delay time between reading each batch of log files. While increasing the delay time increases operation time overall, it consumes fewer I/O activities. If that choice is preferable for your requirements, use -btree-batch-delay to increase the delay between log file integrity checks during peak I/O operations.

When verifying B-tree integrity, the plan verify-data process verifies in-memory integrity. The basic verification checks only if the LSN (Berkeley) for each data record in primary tables is valid. You can configure the verification to include data records on disk, as well as secondary index integrity.

If you do not enable data record verification, the secondary index verification checks only the reference from secondary index to primary table, but not from primary table to index. Since basic verification checks only in-memory data structures, it is significantly faster and less resource intensive than verification involving disk reads.

plan wait

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

Waits indefinitely for the specified plan to complete, unless the optional timeout is specified.

Use the -seconds option to specify the time to wait for the plan to complete.

The -last option references the most recently created plan.

kv-> plan wait -id 26 -json
{
	"operation" : "plan wait",
	"returnCode" : 5000,
	"description" : "Operation ends successfully",
	"returnValue" : {
		"planId" : 26,
		"state" : "CANCELED"
	}
}