gcp.sql.backup.restore

Restore a Cloud SQL backup run into a target instance; overwrites the target in place.

Restore a Cloud SQL backup run into a target instance (destructive).

wait_for_completion is NOT redundant with gcp.sql.operation.wait — do not delete it as a duplicate. In a forward DAG layer you should keep the default (false) and chain gcp.sql.operation.wait on operation_name, because forward layers with a data dependency run sequentially.

Saga COMPENSATION is different: the engine starts every step of a compensation block in PARALLEL, against a single context snapshot taken before any of them run (ltinteg_workflow/core/dag.py: "compensate: Optional list of Step objects to run (in parallel) if this layer or any later layer fails", plus the for step in next_layer.effective_compensate(new_data) loop in core/dag_workflow.py, which builds one comp_ctx up front and starts every step against it). A compensation block of [backup.restore, operation.wait] therefore cannot work: the waiter's operation_name mapping resolves against a snapshot that does not yet contain the restore's output.

Because a restore is destructive, takes the instance offline, and a merely SUBMITTED restore is not a completed recovery, the restore step itself has to be able to block. That is what this flag is for.

Overview

Property	Value
Workflow type	Linear
Library	Base-gcp
Version	1.0

Input Schema

Field	Type	Required	Default	Description
connection_uuid	uuid	Yes	—	GCP CloudConnection UUID.
project_id	string	No	—	GCP project override.
region	string	No	—	Cloud SQL region used for credential scoping.
instance_id	string	Yes	—	Target Cloud SQL instance restored into (overwritten).
backup_run_id	string	Yes	—	Backup run id to restore.
source_instance_id	string	No	—	Instance the backup was taken from; defaults to instance_id.
source_project_id	string	No	—	Project of the source instance; defaults to the target project.
wait_for_completion	boolean	No	—	Block until the restore operation reaches DONE. Defaults to false (submit only). Required in saga compensation, where a separate waiter step cannot be chained.
poll_interval_seconds	integer	No	—	Poll interval when wait_for_completion is true.
timeout_seconds	integer	No	—	Maximum wait time when wait_for_completion is true.

Output Schema

Field	Type	Required	Default	Description
connection_uuid	uuid	No	—	Echoed connection UUID.
project_id	string	No	—	Effective project.
region	string	No	—	Cloud SQL region used for credential scoping.
instance_id	string	No	—	Target Cloud SQL instance restored into.
backup_run_id	string	No	—	Backup run id restored.
source_instance_id	string	No	—	Instance the backup was taken from.
source_project_id	string	No	—	Project of the source instance.
wait_for_completion	boolean	No	—	Whether the run was asked to block until the restore finished.
poll_interval_seconds	integer	No	—	Poll interval used while waiting.
timeout_seconds	integer	No	—	Maximum wait time used while waiting.
operation_name	string	No	—	Cloud SQL restore operation id; feed to gcp.sql.operation.wait when not waiting inline.
waited_for_completion	boolean	No	—	True when this run polled the operation to a terminal status.
status	string	No	—	Operation status: terminal (DONE) when waited, submit-time status otherwise.
operation_type	string	No	—	Operation type (RESTORE_VOLUME).
operation_end_time	string	No	—	Provider operation endTime; present once the restore reached DONE.
operation	json	No	—	Sanitized operation response (terminal payload when waited).
failure_reason	string	No	—	Human-readable failure reason.
failed_step	string	No	—	Failed logical step.
failed_layer	json	No	—	Engine failed layer.
failed_at_state	string	No	—	State where failure occurred.
error	string	No	—	Error message.
error_type	string	No	—	Error class.

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	—
restoring	No	No	—	complete	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	execute	restoring	—
restoring	complete	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "gcp.sql.backup.restore",
  "initial_data": {
    "connection_uuid": "value",
    "instance_id": "value",
    "backup_run_id": "value"
  }
}