SDK de Go: snapshots y copias de seguridad

Los snapshots son copias de seguridad del almacenamiento de una aplicación o de una base de datos. Las aplicaciones y las bases de datos comparten los mismos tres 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)

La cantidad de snapshots que puedes crear por día depende de tu plan (consulta Límites). Cada fragmento de abajo se ejecuta por sí solo dentro de este programa: pega uno a la vez en main y ejecuta goimports (consulta Ejecutar los ejemplos).

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

Listar 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	Descripción
`Name` (`name`)	El id del snapshot que recibe `Restore`
`VersionID` (`version_id`)	La versión que recibe `Restore`
`Size` (`size`)	Tamaño en bytes (`int64`)
`Modified` (`modified`)	Cuándo se tomó (`time.Time`)
`URL` (`url`)	URL de descarga firmada, válida durante 30 días
`Key` (`key`)	Query string firmada de la URL
`Runtime` (`runtime`)	Motor de base de datos o lenguaje de la aplicación (`*string`, `nil` en snapshots antiguos)
`Origin` (`origin`)	`"automatic"`, `"manual"` o `nil` (`*string`)

Crear un snapshot

Create espera al snapshot (sin un deadline en ctx, al menos 2 minutos antes de agotar el tiempo). Es posible que un snapshot grande no termine a tiempo: en ese caso la API responde 202 y el SDK devuelve un SnapshotCreated con Pending en true y un error nil. El snapshot se sigue generando y aparece por sí solo en List, normalmente en menos de 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 vuelvas a llamar a Create para comprobar un snapshot pendiente: eso inicia uno nuevo y cuenta para la cuota diaria de snapshots del plan. Consulta List periódicamente en su lugar.

Restaurar un snapshot

Restore(ctx, id, name, versionID) recibe el Name y el VersionID de un snapshot del 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)
}

Estado	Código	Cuándo
400	`MISSING_PARAMETERS`	Falta `name` o `versionID`
400	`INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID`	No es un `Name`/`VersionID` del listado
400	`SNAPSHOT_DATABASE_MISMATCH`	El motor del snapshot no coincide con el tipo de la base de datos (solo bases de datos)
404	`SNAPSHOT_NOT_FOUND`	No hay ningún snapshot con ese nombre y esa versión
404	`SNAPSHOT_RESTORE_FAILED`	No se pudo lanzar la restauración (el fallo habitual)
413	`PAYLOAD_TOO_LARGE`	El snapshot es demasiado grande para restaurarlo

Descargar un snapshot

c.DownloadSnapshot(ctx, url, w) transmite un archivo de snapshot desde su url firmada (de List o Create) a cualquier io.Writer. No llama a la API: la clave de API nunca se envía al host de almacenamiento, y la URL nunca aparece en el error devuelto. No se almacena nada en memoria, y no hay deadline por defecto (limítalo o cancélalo con ctx). Un error de red antes de la respuesta se reintenta como cualquier 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)
}

Una URL caducada o no válida devuelve un *APIError con el estado HTTP del host de almacenamiento y UNKNOWN_ERROR. Una URL que no se puede analizar y un error de tu io.Writer se devuelven como errores simples.

Snapshots de la cuenta

c.Account.Snapshots(ctx, scope) lista todos los snapshots de la cuenta. Pasa "" para todos, o squarecloud.SnapshotScopeApplications o squarecloud.SnapshotScopeDatabases. Necesita un plan activo y comparte el límite de tasa de los endpoints de red (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")

Estado	Código	Cuándo
400	`INVALID_SCOPE`	`scope` no es `applications` ni `databases`
402	`UPGRADE_REQUIRED`	La cuenta no tiene un plan activo
429	`RATE_LIMITED`	Se alcanzó el límite de tasa

Límites

Create está limitado a una llamada cada 180 segundos y a una cuota diaria que depende del plan: superar la cuota da 429 DAILY_SNAPSHOTS_LIMIT_REACHED.
Mientras se ejecuta una restauración, eliminar la aplicación o iniciar la base de datos da 403 RESTORE_IN_PROGRESS.

Próximos pasos

Bases de datos

Crea y gestiona bases de datos.

Referencia de la API de snapshots

Los endpoints REST detrás de estos métodos.

Snapshots desde la CLI

Las mismas acciones desde la terminal.

CLI

VS Code

SDKs

SDK de Go: snapshots y copias de seguridad

Listar snapshots

Crear un snapshot

Restaurar un snapshot

Descargar un snapshot

Snapshots de la cuenta

Límites

Próximos pasos

Bases de datos

Referencia de la API de snapshots

Snapshots desde la CLI

​Listar snapshots

​Crear un snapshot

​Restaurar un snapshot

​Descargar un snapshot

​Snapshots de la cuenta

​Límites

​Próximos pasos

Bases de datos

Referencia de la API de snapshots

Snapshots desde la CLI

Listar snapshots

Crear un snapshot

Restaurar un snapshot

Descargar un snapshot

Snapshots de la cuenta

Límites

Próximos pasos