Previous Next JavaScript must be enabled to correctly display this content

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