> ## 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 JavaScript: 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 api.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:

* `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](#limites)).

Os exemplos usam o cliente `api` de [Criando o cliente](/pt-br/sdks/js/client#criando-o-cliente). `appId` é o id de uma das suas aplicações: [`api.account.me()`](/pt-br/sdks/js/client#conta) lista todas.

## Listando snapshots

```typescript theme={"system"}
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.

```typescript theme={"system"}
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
}
```

<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(id, name, versionId)` recebe o `name` e o `version_id` de um snapshot listado.

```typescript theme={"system"}
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`).

```typescript theme={"system"}
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`).

```typescript theme={"system"}
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

<CardGroup cols={3}>
  <Card title="Bancos de dados" icon="database" href="/pt-br/sdks/js/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.