> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Go SDK: snapshots and backups
> List, create and restore snapshots of applications and databases, list every snapshot of the account, and download a snapshot file with c.DownloadSnapshot.
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](#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](/en/sdks/go/client#running-the-examples)).
```go theme={"system"}
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
```go theme={"system"}
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.
```go theme={"system"}
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.
```go theme={"system"}
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`.
```go theme={"system"}
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`).
```go theme={"system"}
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
Create and manage databases.
The REST endpoints behind these methods.
The same actions from the terminal.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.