Backups

A schedule backs up one target (an app or a database) to one destination on a cron. Every execution is a run; a successful run leaves an artifact at the destination. Restoring overwrites the live target and needs restore_backups.

Downloading an artifact and restoring from an uploaded file are byte streams, so they are REST: see REST endpoints.

Schedules

backups

Any signed-in principal. Returns [Backup!].

All backup schedules in the active team, newest first.

query {
  backups {
    id
    name
    schedule
    enabled
    lastStatus
  }
}

createBackup

Needs manage_backups. Returns Boolean.

Create a backup schedule. Returns true.

mutation {
  createBackup(
    input: { name: "orders nightly", databaseId: "db_9f1c2ab7d3e4f5a6", destinationId: "dst_9f1c2ab7d3e4f5a6", schedule: "0 3 * * *", retentionCount: 7 }
  )
}

updateBackup

Needs manage_backups. Returns Boolean.

Edit a backup schedule's name, destination, cron and retention. The target it backs up is fixed at creation and cannot be changed. Returns true.

mutation {
  updateBackup(
    id: "brun_9f1c2ab7d3e4f5a6"
    input: { name: "orders nightly", destinationId: "dst_9f1c2ab7d3e4f5a6", schedule: "0 4 * * *", retentionCount: 14 }
  )
}

toggleBackup

Needs manage_backups. Returns Boolean.

Enable or disable a backup schedule. Returns true.

mutation {
  toggleBackup(enabled: true, id: "brun_9f1c2ab7d3e4f5a6")
}

deleteBackup

Needs manage_backups. Returns Boolean.

Delete a backup schedule. Returns true.

mutation {
  deleteBackup(id: "brun_9f1c2ab7d3e4f5a6")
}

Runs and artifacts

backupRuns

Any signed-in principal. Returns [BackupRun!].

Recorded backup runs for one target (an app OR a database), newest first. Pass exactly one of appId / databaseId.

query {
  backupRuns(databaseId: "db_9f1c2ab7d3e4f5a6") {
    id
    status
    startedAt
    sizeBytes
    verified
  }
}

backupArtifactCount

Any signed-in principal. Returns Int.

How many stored backup artifacts (successful runs) one target has. Deleting the target removes them, so this is what that delete takes with it.

query {
  backupArtifactCount(targetId: "prj_9f1c2ab7d3e4f5a6", targetKind: app)
}

runBackup

Needs manage_backups. Returns Boolean.

Run a backup schedule manually now. Returns true.

mutation {
  runBackup(id: "brun_9f1c2ab7d3e4f5a6")
}

runAppBackup

Needs manage_backups. Returns Boolean.

Run an ad-hoc backup of an app now (no owning schedule). Returns true.

mutation {
  runAppBackup(
    appId: "prj_9f1c2ab7d3e4f5a6"
    destinationId: "dst_9f1c2ab7d3e4f5a6"
  )
}

runDatabaseBackup

Needs manage_backups. Returns Boolean.

Run an ad-hoc backup of a database now (no owning schedule). Returns true.

mutation {
  runDatabaseBackup(
    databaseId: "db_9f1c2ab7d3e4f5a6"
    destinationId: "dst_9f1c2ab7d3e4f5a6"
  )
}

cancelBackupRun

Needs manage_backups. Returns Boolean.

Stop a backup that is running: the record settles as canceled and the dump is aborted on the host it runs on. Returns false when it had already finished.

mutation {
  cancelBackupRun(runId: "brun_9f1c2ab7d3e4f5a6")
}

restoreBackup

Needs restore_backups. Returns Boolean.

Restore a backup run in place (overwrites the live target). Returns true.

mutation {
  restoreBackup(runId: "brun_9f1c2ab7d3e4f5a6")
}

deleteBackupRun

Needs delete_backups. Returns Boolean.

Permanently delete ONE backup: the artifact at its destination and the run record together. Not the schedule (see deleteBackup) and not the target's whole history (see deleteBackupArtifacts). Returns true.

mutation {
  deleteBackupRun(runId: "brun_9f1c2ab7d3e4f5a6")
}

deleteBackupArtifacts

Any signed-in principal. Returns Int.

Delete ALL of a target's backup artifacts (across every destination it ran to) plus their run records. The 'also delete backups' branch of deleting a database or an app. Returns the number removed. Throws if any destination's sweep failed, so the caller can abort the target deletion rather than orphan the files.

mutation {
  deleteBackupArtifacts(targetId: "prj_9f1c2ab7d3e4f5a6", targetKind: app)
}

Destinations

backupDestinations

Any signed-in principal. Returns [BackupDestination!].

All backup destinations in the active team, newest first.

query {
  backupDestinations {
    id
    name
    kind
    status
  }
}

backupDestinationOptions

Any signed-in principal. Returns [BackupDestinationOption!].

The team's backup destinations as a picker needs them, newest first. Unlike backupDestinations this is readable by a member scoped to part of the team: they may hold manage_backups on an app and still need somewhere to send its backups.

query {
  backupDestinationOptions {
    id
    name
    kind
    status
  }
}

createDestination

Needs manage_backup_destinations. Returns BackupDestination.

Add a backup destination: an S3-compatible bucket, or a folder on one of the team's servers. Test it with testDestination before trusting it.

mutation {
  createDestination(
    input: { name: "R2 backups", kind: s3, provider: CLOUDFLARE_R2, bucket: "deplo-backups", endpoint: "https://<account>.r2.cloudflarestorage.com", accessKey: "…", secretKey: "…" }
  ) {
    id
    name
    kind
    status
  }
}

testDestination

Needs manage_backup_destinations. Returns DestinationTestResult.

Probe the destination through its agent - for a bucket, head/write/remove; for a server, resolve the folder, check it is writable and report its free space, and return BOTH the repainted destination and the verdict. A failed probe resolves normally with report.ok = false: check it rather than assuming success, and show report.error verbatim.

mutation {
  testDestination(id: "dst_9f1c2ab7d3e4f5a6") {
    report {
      ok
      error
    }
    destination {
      id
      status
    }
  }
}

testDestinations

Needs manage_backup_destinations. Returns [BackupDestination!].

Re-probe EVERY destination in the active team and return them with their badges repainted, newest first. For pickers that must show live connectivity the moment they open, rather than a status that was true hours ago. A destination whose probe fails comes back as error with lastTestError set - the call itself still resolves.

mutation {
  testDestinations {
    id
    name
    kind
    status
  }
}

destinationTestReport

Needs manage_backup_destinations. Returns S3TestReport.

The STORED result of this destination's last connection test - reading it never re-dials. never is true until the first test.

query {
  destinationTestReport(id: "dst_9f1c2ab7d3e4f5a6") {
    ok
    error
    never
    steps {
      label
      status
    }
  }
}

destinationRemovalImpact

Any signed-in principal. Returns DestinationRemovalImpact.

What deleting this destination would destroy. Read by the confirm dialog, so it can name the schedules and restore points instead of saying backups will 'stop running'.

query {
  destinationRemovalImpact(id: "dst_9f1c2ab7d3e4f5a6") {
    schedules
    runs
    artifacts
  }
}

destinationRecoveryKey

Needs manage_backup_destinations. Returns RecoveryKey.

Fetch a server destination's recovery key, and mark it saved. This hands over the ability to read every artifact at that destination, so it is recorded in Activity. A mutation rather than a field precisely so that reading the destination never carries the key.

mutation {
  destinationRecoveryKey(id: "dst_9f1c2ab7d3e4f5a6") {
    name
    recipient
    where
  }
}

deleteDestination

Needs manage_backup_destinations. Returns Boolean.

Delete the destination, and with it every schedule and run record that points at it. With deleteArtifacts, the stored backup files go too - otherwise they stay where they are, which for a server destination means on that disk with nothing left in Deplo that can name them. Returns true.

mutation {
  deleteDestination(id: "dst_9f1c2ab7d3e4f5a6", deleteArtifacts: false)
}

See also