SDK Go: snapshots e backups

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). Cada trecho abaixo roda sozinho dentro deste programa: cole um de cada vez em main e execute o goimports (veja Executando os exemplos).

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

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.

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
}

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.

Restaurando um snapshot

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

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.

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

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

Bancos de dados

Crie e gerencie bancos de dados.

Referência da API de snapshots

Os endpoints REST por trás destes métodos.

Snapshots pela CLI

As mesmas ações pelo terminal.

CLI

VS Code

SDKs

SDK Go: snapshots e backups

Listando snapshots

Criando um snapshot

Restaurando um snapshot

Baixando um snapshot

Snapshots da conta

Limites

Próximos passos

Bancos de dados

Referência da API de snapshots

Snapshots pela CLI

​Listando snapshots

​Criando um snapshot

​Restaurando um snapshot

​Baixando um snapshot

​Snapshots da conta

​Limites

​Próximos passos

Bancos de dados

Referência da API de snapshots

Snapshots pela CLI

Listando snapshots

Criando um snapshot

Restaurando um snapshot

Baixando um snapshot

Snapshots da conta

Limites

Próximos passos