Using Plans
You use plans to configure your data store. A plan consists of administrative operations. Plans can modify the state managed by the Admin service, and issue requests to data store components such as Storage Nodes and replication nodes. Some plans consist of simple state-changing operations, while others perform a set of tasks that affect every Storage Node and replication nodes in the data store. For example, you use a plan to create a zone or Storage Node, or to reconfigure parameters on a replication node.
You use the plan
command, available from the administrative command line interface, to both create and execute plans, as well as to perform many other tasks. For more about using the plan
command, see CLI Command Reference.
By default, running a plan
command executes asynchronously in the background. The command line prompt returns as soon as the background process begins. You can check the progress of a running plan using the show plan id
command.
You can run a plan
command synchronously in two ways:
plan action_to_complete —wait
plan wait -id plan_id
Using either the –wait
flag or the plan wait
command, causes the command line prompt to return only after the command completes.
The -wait
flag and the plan wait
command are useful when executing plans from scripts, which typically expect each command to finish before processing the next command.
-noexecute
flag, as follows:
plan action –name plan-name -noexecute
Later,
you can execute the plan on demand as follows:
plan execute -id id_num
Tracking Plan Progress
There are several ways to track the progress of a plan.
-
The
show plan -id
command provides information about the progress of a running plan. Use the optional-verbose
flag to get more details. -
The CLI
verify
command gives service status information as the plan is executing and services start.Note:
The
verify
command is of interest for only topology-related plans. If the plan is modifying parameters, such changes may not be visible using the verify command. -
The CLI's
logtail
command lets you follow the store-wide log.
Plan States
Plans can be in any of the following states. A plan can be in only one state at a time. These are the possible states:
Name | Description |
---|---|
APPROVED | The plan exists with correct operations, but is not running. |
CANCELED | A plan that is manually INTERRUPTED or that experiences an ERROR can be terminated. Use the cancel command to terminate a plan.
|
ERROR | If a plan in the RUNNING state encounters a problem, it
transitions to this state and ends processing without successfully
completing. Storage Nodes and replication nodes can encounter an error
before the plan processes the error and transitions to an
ERROR state.
|
INTERRUPTED | A RUNNING plan transitions to this state after the interrupt command in the CLI.
|
INTERRUPT REQUESTED | When a running plan receives an interrupt request, the plan may have to cleanup or reverse previous steps taken during its execution. If the plan transitions to this state, it is to make sure that the data store remains in a consistent state. |
RUNNING | The plan is currently executing its commands. |
SUCCEEDED | The plan has completed successfully. |
You can use the plan execute
command whenever a plan enters the INTERRUPTED
, INTERRUPT REQUESTED
or ERROR
state. Retrying is appropriate if the underlying problem was transient or has been rectified. When you retry a Plan, it processes the steps again. Each step is idempotent, and can be safely repeated.
Reviewing Plans
You can use the CLI show plans
command to
review the execution history of plans. The command also lists the plan ID numbers,
plan names, and the state of each plan. With the plan ID, use the show plan
-id <plan number>
command to see more details about a specific plan.
The next
example shows the output of both the show plans
command and then
the show plan -id <plan number>
command. The show plan
command returns
the plan name, the number of attempts, the start and end date and times, the total
number of tasks the plan completed, and the whether the plan completed successfully.
kv-> show plans
Output:1 Deploy KVLite SUCCEEDED
2 Deploy Storage Node SUCCEEDED
3 Deploy Admin Service SUCCEEDED
4 Deploy KVStore SUCCEEDED
kv-> show plan -id 3
Output:Plan Deploy Admin Service (3)
Owner: null
State: SUCCEEDED
Attempt number: 1
Started: 2024-04-05 22:05:31 UTC
Ended: 2024-04-05 22:05:31 UTC
Total tasks: 1
Successful: 1
Plan Ownership
In a secure Oracle NoSQL Database deployment, each plan command is associated with
its creator as the owner. Only the plan owner can see and operate it. If a plan is
created in an earlier version of Oracle NoSQL Database, or in an non secure data store,
the owner is null
.
Note:
The SYSOPER privilege allows a user to perform cancel, execute, interrupt, and wait on any plan. Users with the SYSVIEW
privilege can see plans owned by other users, plans with a null
owner, and plans whose owners have been removed from the Oracle NoSQL Database.
For more information about user privileges and on configuring Oracle NoSQL Database securely, see the Security Guide.
Pruning Plans
-
Are in a terminal state (
SUCCEEDED
orCANCELLED
)
- Have a Plan ID number that is 1000 less than the most recent Plan ID
-
Attempting to show a plan with a specific ID that has been pruned.
- Specifying a range of plans that contains one or more removed plans.