> ## 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 Python: snapshots e backups

> Liste, crie e restaure snapshots de aplicações e bancos de dados, veja todos os snapshots da conta e baixe um snapshot com client.download_snapshot().

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:

* `client.apps.snapshots`: `list(app_id)`, `create(app_id)`, `restore(app_id, name, version_id)`
* `client.databases.snapshots`: `list(database_id)`, `create(database_id)`, `restore(database_id, name, version_id)`

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

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

## Listando snapshots

```python theme={"system"}
for snapshot in client.apps.snapshots.list(app_id):
    print(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 (`None` em snapshots antigos) |
| `origin` | `"automatic"`, `"manual"` ou `None` |

## 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. Caso contrário, retorna `{'pending': False, 'url': ..., 'key': ...}`.

```python theme={"system"}
result = client.apps.snapshots.create(app_id)

if result["pending"]:
    # Poll list() later. Do not call create() again: that starts a new snapshot.
    pass
else:
    print(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, version_id)` recebe o `name` e o `version_id` de um snapshot listado.

```python theme={"system"}
latest = client.apps.snapshots.list(app_id)[0]

client.apps.snapshots.restore(app_id, latest["name"], latest["version_id"])
```

| Status | Código | Quando |
| - | - | - |
| 400 | `MISSING_PARAMETERS` | `name` ou `version_id` 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

`client.download_snapshot(url, dest)` transmite um arquivo de snapshot a partir da sua `url` assinada (de `list()` ou `create()`) para o disco e retorna o caminho em que escreveu. Ele **não** chama a API: a chave de API nunca é enviada ao host de armazenamento. Nada é armazenado em memória.

* `dest` é um caminho de arquivo, ou um diretório para manter o nome do arquivo remoto. Um caminho terminado em `/` é criado como diretório.
* Os dados vão para um arquivo `.part` que é renomeado quando termina, então um download que falhe nunca sobrescreve um arquivo anterior.
* Não há timeout para o download inteiro: `timeout` limita cada leitura.

```python theme={"system"}
latest = client.apps.snapshots.list(app_id)[0]

path = client.download_snapshot(latest["url"], "backup.zip")
print("saved to", path)

# Or into a directory, keeping the remote name
client.download_snapshot(latest["url"], "backups/")
```

Com o `AsyncSquareCloud`, é `await client.download_snapshot(url, dest)`.

Uma URL expirada ou inválida lança um `SquareCloudAPIError` com o status HTTP do host de armazenamento e `UNKNOWN_ERROR`. Um destino em que não é possível escrever lança um `OSError`.

## Snapshots da conta

`client.account.snapshots(scope=None)` lista todos os snapshots da conta, opcionalmente apenas `"applications"` ou `"databases"` (keyword-only). Requer um plano ativo e compartilha o rate limit dos endpoints de rede (429 `RATE_LIMITED`).

```python theme={"system"}
everything = client.account.snapshots()
databases = client.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/py/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.