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.

You can also create a plan, but defer its execution using the optional -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

The system automatically prunes plans that should be removed. Plans are removed from the Admin Store if they match both of these conditions:

  • Are in a terminal state (SUCCEEDED or CANCELLED)

  • Have a Plan ID number that is 1000 less than the most recent Plan ID
For example, if the most recent Plan ID is 2000, the system prunes all plans with ID numbers 1000 or less that are in a terminal state . The system does not remove plans in a non-terminal state.
While pruning plans occurs automatically, you can detect that pruning has occurred in these situations:

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