Skip to content

Start restore run

StartRestoreRun

StartRestoreRun

Description: Starts a restore flow from a validated backup run.

The current implementation validates the source backup first, then calls restore callbacks registered by backup participants. The source backup must have status completed. If a future participant does not implement restore yet, the run fails with restore callback is not registered.

Access Control

SESSION_ADMIN, SESSION_MANAGER

Request Parameters

Field Type Required Description
run_id string Yes Source backup run identifier
dry_run bool No Validate and execute participant restore callbacks in dry-run mode when supported
participants array No Optional participant names for module-scoped restore, for example ["staff"]
force bool No Bypass maintenance/update mode guard for an actual restore

Request Example

{
  "command": "StartRestoreRun",
  "extID": "1",
  "data": {
    "run_id": "20260629-121045-000001",
    "dry_run": true,
    "participants": ["staff"],
    "force": false
  }
}

Response Example

{
  "restore_id": "20260629-122000-000002",
  "source_run_id": "20260629-121045-000001",
  "dry_run": true,
  "force": false,
  "pre_restore_path": "backups/pre-restore/20260629-122000-000002",
  "status": "completed",
  "started_at": 1782728400,
  "finished_at": 1782728401,
  "error_summary": "",
  "participants": [
    {
      "name": "staff",
      "critical": true,
      "ok": true,
      "status": "completed",
      "started_at": 1782728400,
      "finished_at": 1782728401,
      "error": "",
      "safety_snapshot_path": "",
      "artifacts": [
        {
          "logical_name": "staff.db",
          "path": "backups/completed/20260629-121045-000001/staff.db",
          "size_bytes": 327680,
          "sha256": "f2a1...",
          "integrity_ok": true,
          "integrity_error": "",
          "validation_ok": true,
          "validation_error": ""
        }
      ],
      "safety_artifacts": []
    }
  ]
}

Notes

  • Only one backup or restore operation can run at a time.
  • Restore must be implemented by each participant module. BackupManager must not directly replace module storage.
  • If participants is omitted, the server attempts a full restore for all registered participants.
  • The source backup must have status completed; partial, failed, running, cancelled, and timeout runs are not restorable.
  • dry_run is allowed in any server mode.
  • Actual restore requires maintenance/update mode (liveupdate_mode != 0) unless force is set to true.
  • Before actual restore, the server creates a validated safety snapshot in backups/pre-restore/<restore_id>.
  • If a selected critical participant fails safety snapshot creation, restore does not start.
  • force should be used only for controlled maintenance operations.
  • This command returns HTTP 409 when restore is blocked by the safety guard, validation fails, or a participant fails.