plan
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.
-
-json | -json-v1
Displays the plan output as json or json-v1. The
-json
flag can be used to output in the new json format. The-json-v1
flag can be used to output in the json-v1 format. If you have an existing script that relies on an older version of JSON output, you may want to consider using-json-v1
flag so that your existing scripts continue to function.
The subcommands are as described below.
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.
-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. This plan changes the parameters for all services that are running at the time of plan creation. If more services are added after plan creation, perhaps via a topology plan, then it is not guaranteed the new services will receive the new parameters.
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.
- Run a change-policy command to set the parameter values to be used when creating Replication Nodes in the future.
- Run the command
plan change-parameters -all-rns
to change the parameter values for existing Replication Nodes.
Note:
Theplan 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.
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-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
Specifying-arbiters
, you can allocate Arbiter Nodes on the Storage Node in the zone. You can specify this flag only on a primary zone.-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
Specifying-master-affinity
indicates that this zone can host a master.-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 7-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 7-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 7-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.
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 isrg1-rn3
, and the ping output shows thatrg1-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.
- any replication nodes must first be removed using the
topology change-replication-factor
andplan 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 thestart-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, executingplan 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]
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 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 It is disabled by default. |
-index
|
Verifies indexes. Using the 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.
plan verify-data
has two parts for verifications:
- Log record integrity on disk
- B-tree integrity
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"
}
}