Go SDK: snapshots and backups

Snapshots are backups of an app’s or database’s storage. Apps and databases share the same three methods:

c.Apps.Snapshots: List(ctx, appID), Create(ctx, appID), Restore(ctx, appID, name, versionID)
c.Databases.Snapshots: List(ctx, databaseID), Create(ctx, databaseID), Restore(ctx, databaseID, name, versionID)

How many snapshots you can create per day depends on your plan (see Limits). Each snippet below runs on its own inside this program: paste one at a time into main and run goimports (see Running the examples).

package main

import (
	"context"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

var (
	ctx   = context.Background()
	c     = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))
	appID = "abc123def456abc123def456"
)

func main() {
	// Paste one snippet here, then run goimports.
}

Listing snapshots

snapshots, err := c.Apps.Snapshots.List(ctx, appID)
if err != nil {
	log.Fatal(err)
}
for _, s := range snapshots {
	fmt.Println(s.Name, s.VersionID, s.Size, s.Modified)
}

Field	Description
`Name` (`name`)	The snapshot id that `Restore` takes
`VersionID` (`version_id`)	The version that `Restore` takes
`Size` (`size`)	Size in bytes (`int64`)
`Modified` (`modified`)	When it was taken (`time.Time`)
`URL` (`url`)	Signed download URL, valid for 30 days
`Key` (`key`)	Signed query string of the URL
`Runtime` (`runtime`)	Database engine or app language (`*string`, `nil` on old snapshots)
`Origin` (`origin`)	`"automatic"`, `"manual"` or `nil` (`*string`)

Creating a snapshot

Create waits for the snapshot (without a ctx deadline, at least 2 minutes before timing out). A large snapshot may not finish in time: the API then answers 202 and the SDK returns a SnapshotCreated with Pending set to true and a nil error. The snapshot keeps generating and shows up in List on its own, usually within 2 minutes.

result, err := c.Apps.Snapshots.Create(ctx, appID)
if err != nil {
	log.Fatal(err)
}

if result.Pending {
	// Poll List later. Do not call Create again: that starts a new snapshot.
} else {
	fmt.Println(result.URL) // signed download URL, valid 30 days
}

Never call Create again to check on a pending snapshot: it starts a new one and counts against the plan’s daily snapshot quota. Poll List instead.

Restoring a snapshot

Restore(ctx, id, name, versionID) takes the Name and VersionID of a listed snapshot.

snapshots, err := c.Apps.Snapshots.List(ctx, appID)
if err != nil {
	log.Fatal(err)
}
if len(snapshots) == 0 {
	log.Fatal("no snapshots")
}

latest := snapshots[0]
if err := c.Apps.Snapshots.Restore(ctx, appID, latest.Name, latest.VersionID); err != nil {
	log.Fatal(err)
}

Status	Code	When
400	`MISSING_PARAMETERS`	`name` or `versionID` is missing
400	`INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID`	Not a `Name`/`VersionID` from the listing
400	`SNAPSHOT_DATABASE_MISMATCH`	The snapshot’s engine does not match the database’s type (databases only)
404	`SNAPSHOT_NOT_FOUND`	No snapshot with that name and version
404	`SNAPSHOT_RESTORE_FAILED`	The restore could not be dispatched (the usual failure)
413	`PAYLOAD_TOO_LARGE`	The snapshot is too large to restore

Downloading a snapshot

c.DownloadSnapshot(ctx, url, w) streams a snapshot file from its signed url (from List or Create) into any io.Writer. It does not call the API: the API key is never sent to the storage host, and the URL never appears in the returned error. Nothing is buffered in memory, and there is no default deadline (bound or cancel it with ctx). A network error before the response is retried like any GET.

snapshots, err := c.Apps.Snapshots.List(ctx, appID)
if err != nil {
	log.Fatal(err)
}
if len(snapshots) == 0 {
	log.Fatal("no snapshots")
}

out, err := os.Create("backup.zip")
if err != nil {
	log.Fatal(err)
}
defer out.Close()

if err := c.DownloadSnapshot(ctx, snapshots[0].URL, out); err != nil {
	log.Fatal(err)
}

An expired or invalid URL returns an *APIError with the storage host’s HTTP status and UNKNOWN_ERROR. A URL that cannot be parsed, and an error of your io.Writer, are returned as plain errors.

Account snapshots

c.Account.Snapshots(ctx, scope) lists every snapshot of the account. Pass "" for all of them, or squarecloud.SnapshotScopeApplications or squarecloud.SnapshotScopeDatabases. It needs an active plan and shares the network endpoints’ rate limit (429 RATE_LIMITED).

all, err := c.Account.Snapshots(ctx, "")
if err != nil {
	log.Fatal(err)
}

databases, err := c.Account.Snapshots(ctx, squarecloud.SnapshotScopeDatabases)
if err != nil {
	log.Fatal(err)
}

fmt.Println(len(all), "snapshots,", len(databases), "of databases")

Status	Code	When
400	`INVALID_SCOPE`	`scope` is not `applications` or `databases`
402	`UPGRADE_REQUIRED`	The account has no active plan
429	`RATE_LIMITED`	Rate limit reached

Limits

Create is limited to one call per 180 seconds and to a daily quota that depends on the plan: going over the quota is 429 DAILY_SNAPSHOTS_LIMIT_REACHED.
While a restore runs, deleting the app or starting the database is 403 RESTORE_IN_PROGRESS.

Next steps

Databases

Create and manage databases.

Snapshot API reference

The REST endpoints behind these methods.

Snapshots from the CLI

The same actions from the terminal.

CLI

VS Code

SDKs

Go SDK: snapshots and backups

Listing snapshots

Creating a snapshot

Restoring a snapshot

Downloading a snapshot

Account snapshots

Limits

Next steps

Databases

Snapshot API reference

Snapshots from the CLI

​Listing snapshots

​Creating a snapshot

​Restoring a snapshot

​Downloading a snapshot

​Account snapshots

​Limits

​Next steps

Databases

Snapshot API reference

Snapshots from the CLI

Listing snapshots

Creating a snapshot

Restoring a snapshot

Downloading a snapshot

Account snapshots

Limits

Next steps