> ## 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.

# SDK Go: snapshots e backups

> Liste, crie e restaure snapshots de aplicações e bancos de dados, liste todos os snapshots da conta e baixe um arquivo de snapshot com c.DownloadSnapshot.

Snapshots são backups do armazenamento de uma aplicação ou de um banco de dados. Aplicações e bancos de dados compartilham os mesmos três métodos:

* `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)`

Quantos snapshots você pode criar por dia depende do seu plano (veja [Limites](#limites)).

Cada trecho abaixo roda sozinho dentro deste programa: cole um de cada vez em `main` e execute o `goimports` (veja [Executando os exemplos](/pt-br/sdks/go/client#executando-os-exemplos)).

```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.
}
```

## Listando 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)
}
```

| Campo | Descrição |
| - | - |
| `Name` (`name`) | O id do snapshot que `Restore` recebe |
| `VersionID` (`version_id`) | A versão que `Restore` recebe |
| `Size` (`size`) | Tamanho em bytes (`int64`) |
| `Modified` (`modified`) | Quando foi criado (`time.Time`) |
| `URL` (`url`) | URL de download assinada, **válida por 30 dias** |
| `Key` (`key`) | Query string assinada da URL |
| `Runtime` (`runtime`) | Engine do banco de dados ou linguagem da aplicação (`*string`, `nil` em snapshots antigos) |
| `Origin` (`origin`) | `"automatic"`, `"manual"` ou `nil` (`*string`) |

## Criando um snapshot

`Create` aguarda o snapshot (sem um prazo no `ctx`, pelo menos 2 minutos antes de expirar). Um snapshot grande pode não terminar a tempo: a API então responde 202 e o SDK retorna um `SnapshotCreated` com `Pending` definido como `true` e um erro `nil`. O snapshot continua sendo gerado e aparece em `List` sozinho, geralmente em até 2 minutos.

```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
}
```

<Warning>
  Nunca chame `Create` novamente para verificar um snapshot pendente: isso inicia um novo e conta para a cota diária de snapshots do plano. Consulte `List` em vez disso.
</Warning>

## Restaurando um snapshot

`Restore(ctx, id, name, versionID)` recebe o `Name` e o `VersionID` de um snapshot listado.

```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 | Código | Quando |
| - | - | - |
| 400 | `MISSING_PARAMETERS` | `name` ou `versionID` está ausente |
| 400 | `INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID` | Não é um `Name`/`VersionID` da listagem |
| 400 | `SNAPSHOT_DATABASE_MISMATCH` | A engine do snapshot não corresponde ao tipo do banco de dados (apenas bancos de dados) |
| 404 | `SNAPSHOT_NOT_FOUND` | Nenhum snapshot com esse nome e versão |
| 404 | `SNAPSHOT_RESTORE_FAILED` | A restauração não pôde ser despachada (a falha mais comum) |
| 413 | `PAYLOAD_TOO_LARGE` | O snapshot é grande demais para ser restaurado |

## Baixando um snapshot

`c.DownloadSnapshot(ctx, url, w)` transmite um arquivo de snapshot a partir da sua `url` assinada (de `List` ou `Create`) para qualquer `io.Writer`. Ele **não** chama a API: a chave de API nunca é enviada ao host de armazenamento, e a URL nunca aparece no erro retornado. Nada é armazenado em memória, e não há prazo padrão (limite-o ou cancele-o com o `ctx`). Um erro de rede antes da resposta é tentado novamente como qualquer `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)
}
```

Uma URL expirada ou inválida retorna um `*APIError` com o status HTTP do host de armazenamento e `UNKNOWN_ERROR`. Uma URL que não pode ser interpretada e um erro do seu `io.Writer` são retornados como erros simples.

## Snapshots da conta

`c.Account.Snapshots(ctx, scope)` lista todos os snapshots da conta. Passe `""` para todos eles, ou `squarecloud.SnapshotScopeApplications` ou `squarecloud.SnapshotScopeDatabases`. Requer um plano ativo e compartilha o rate limit dos endpoints de rede (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 | Código | Quando |
| - | - | - |
| 400 | `INVALID_SCOPE` | `scope` não é `applications` nem `databases` |
| 402 | `UPGRADE_REQUIRED` | A conta não tem um plano ativo |
| 429 | `RATE_LIMITED` | Rate limit atingido |

## Limites

* `Create` é limitado a uma chamada a cada 180 segundos e a uma cota diária que depende do plano: ultrapassar a cota resulta em 429 `DAILY_SNAPSHOTS_LIMIT_REACHED`.
* Enquanto uma restauração está em andamento, excluir a aplicação ou iniciar o banco de dados resulta em 403 `RESTORE_IN_PROGRESS`.

## Próximos passos

<CardGroup cols={3}>
  <Card title="Bancos de dados" icon="database" href="/pt-br/sdks/go/databases">
    Crie e gerencie bancos de dados.
  </Card>

  <Card title="Referência da API de snapshots" icon="code" href="/pt-br/api-reference/endpoint/apps/snapshots/list">
    Os endpoints REST por trás destes métodos.
  </Card>

  <Card title="Snapshots pela CLI" icon="terminal" href="/pt-br/cli-reference/snapshots">
    As mesmas ações pelo terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.