SDK JavaScript: 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:

api.apps.snapshots: list(appId), create(appId), restore(appId, name, versionId)
api.databases.snapshots: list(databaseId), create(databaseId), restore(databaseId, name, versionId)

Quantos snapshots você pode criar por dia depende do seu plano (veja Limites). Os exemplos usam o cliente api de Criando o cliente. appId é o id de uma das suas aplicações: api.account.me() lista todas.

Listando snapshots

for (const snapshot of await api.apps.snapshots.list(appId)) {
    console.log(snapshot.name, snapshot.version_id, snapshot.size, snapshot.modified);
}

Campo	Descrição
`name`	O id do snapshot que `restore` recebe
`version_id`	A versão que `restore` recebe
`size`	Tamanho em bytes
`modified`	Quando foi criado
`url`	URL de download assinada, válida por 30 dias
`key`	Query string assinada da URL
`runtime`	Engine do banco de dados ou linguagem da aplicação (`null` em snapshots antigos)
`origin`	`"automatic"`, `"manual"` ou `null`

Criando um snapshot

create() aguarda o snapshot (pelo menos 120 s antes de expirar). Um snapshot grande pode não terminar a tempo: a API então responde 202 e o SDK retorna { pending: true }. O snapshot continua sendo gerado e aparece em list() sozinho, geralmente em até 2 minutos.

const result = await api.apps.snapshots.create(appId);

if (result.pending) {
    // Poll list() later. Do not call create() again: that starts a new snapshot.
} else {
    console.log(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(id, name, versionId) recebe o name e o version_id de um snapshot listado.

const [latest] = await api.apps.snapshots.list(appId);

await api.apps.snapshots.restore(appId, latest.name, latest.version_id);

Status	Código	Quando
400	`MISSING_PARAMETERS`	`name` ou `versionId` está ausente
400	`INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID`	Não é um `name`/`version_id` 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

api.downloadSnapshot(url, { signal }) transmite um arquivo de snapshot a partir da sua url assinada (de list() ou create()). Ele não chama a API: a chave de API nunca é enviada ao host de armazenamento. Retorna um ReadableStream<Uint8Array>, sem nada armazenado em memória, e não tem timeout (passe um signal).

import { createWriteStream } from "node:fs";
import { Writable } from "node:stream";

const [latest] = await api.apps.snapshots.list(appId);
const stream = await api.downloadSnapshot(latest.url);

await stream.pipeTo(Writable.toWeb(createWriteStream("backup.zip")));

Uma URL expirada ou inválida lança um SquareCloudAPIError com o status HTTP do host de armazenamento e UNKNOWN_ERROR.

Snapshots da conta

api.account.snapshots({ scope }) lista todos os snapshots da conta, opcionalmente apenas "applications" ou "databases". Requer um plano ativo e compartilha o rate limit dos endpoints de rede (429 RATE_LIMITED).

const all = await api.account.snapshots();
const databases = await api.account.snapshots({ scope: "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 JavaScript: 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