Instance Lifecycle

Every ReflexDB database instance has a status that reflects where it is in its lifecycle. Some actions are only available in certain statuses, and some are queued to execute automatically when the instance reaches a stable state.

Statuses

Stable statuses

Status	Description
`registered`	Created but never provisioned. No infrastructure running.
`running`	Instance is serving queries.
`paused`	Instance is scaled to zero. Data is preserved; queries are not served.
`failed`	The last build or deploy failed. May have partial infrastructure.
`stopped`	Instance was cleanly shut down (e.g. after termination rolled back).
`terminated`	Infrastructure destroyed. Record is retained for audit.

Transitional statuses

Status	Description
`testing_connection`	Verifying connectivity to the source database before building.
`queued`	Build job is queued and waiting for capacity.
`building`	Compiling the query engine from your schema.
`deploying`	Rolling out the compiled binary to a dedicated instance.
`pausing`	Scaling the instance to zero.
`resuming`	Scaling the instance back up.
`terminating`	Destroying infrastructure. Irreversible once started.

Action availability matrix

The table below shows which actions are available for each instance status.

Legend:

Y = available immediately
Q = queued (executes when the instance reaches a stable state)
img = requires a prior successful build
— = not available

Status	Provision	Rebuild	Reconfigure	Redeploy	Resize	Pause	Resume	Terminate	Delete	Reload	Pause sync	Resume sync
`registered`	Y	—	—	—	Y	—	—	—	Y	—	—	—
`testing_connection`	—	—	—	—	—	—	—	—	—	—	—	—
`queued`	—	—	—	—	—	Q	—	Q	—	—	—	—
`building`	—	—	—	—	—	Q	—	Q	—	—	—	—
`deploying`	—	—	—	—	Y	Q	—	Q	—	—	—	—
`running`	—	Y	Y	img	Y	Y	—	Y	—	Y	Y	Y
`pausing`	—	—	—	—	—	—	Q	Q	—	—	—	—
`paused`	—	Y	—	img	Y	—	Y	Y	—	—	—	—
`resuming`	—	—	—	—	—	Q	—	Q	—	—	—	—
`failed`	Y	img	—	img	img	—	—	Y	—	—	—	—
`stopped`	Y	—	—	—	Y	—	—	—	—	—	—	—
`terminating`	—	—	—	—	—	—	—	—	—	—	—	—
`terminated`	—	—	—	—	—	—	—	—	—	—	—	—

Notes

img means the action requires a prior successful build to exist. If the instance has never been successfully built, use Provision instead.
Resize from registered, paused, or stopped only updates the stored size — no deploy happens. The new size takes effect on the next provision or resume. Resize from deploying is allowed to recover from out-of-memory deploy failures.
Queued actions respect the current goal. For example, you cannot queue both Pause and Resume at the same time. Use Cancel Goal to withdraw a queued action before setting a new one.
Cancel Goal is available whenever the instance has an active desired state (a queued action waiting to execute).

Queued actions

When an instance is in a transitional state (building, deploying, pausing, resuming), you can queue certain actions:

Pause can be queued during queued, building, deploying, or resuming.
Resume can be queued during pausing.
Terminate can be queued from any transitional state.

Queued actions are shown in the dashboard with a dashed border and an “after” label (e.g. “Pause after”). The desired-state pill shows what the system is working toward.

To cancel a queued action, click Cancel next to the desired-state pill, or use the DELETE /databases/:id/desired-state API endpoint.

API response

The GET /databases/:id/instance endpoint includes an allowedActions field that returns the full action availability matrix for the current instance state. The dashboard uses this to show and hide action buttons — you can use it to build custom integrations without reimplementing the state logic.

{
  "database": { "status": "running", "desiredState": null, ... },
  "allowedActions": {
    "provision":          { "allowed": false },
    "rebuild":            { "allowed": true, "mode": "immediate" },
    "reconfigure":        { "allowed": true, "mode": "immediate" },
    "redeploy":           { "allowed": true, "mode": "immediate" },
    "resize":             { "allowed": true, "mode": "immediate" },
    "pause":              { "allowed": true, "mode": "immediate" },
    "resume":             { "allowed": false },
    "terminate":          { "allowed": true, "mode": "immediate" },
    "delete":             { "allowed": false },
    "reload":             { "allowed": true, "mode": "immediate" },
    "pause-replication":  { "allowed": true, "mode": "immediate" },
    "resume-replication": { "allowed": true, "mode": "immediate" },
    "cancel-goal":        { "allowed": false }
  }
}

Each action includes:

allowed — whether the action can be performed right now.
mode — "immediate" (executes now) or "queued" (sets desired state, executes when the instance is idle). Only present when allowed is true.
reason — why the action is blocked. Only present when allowed is false.