Snapshots e restaurações em segundo plano
Criar e restaurar um snapshot não precisa mais caber em uma única requisição. Aplicações e bancos grandes agora funcionam, e você acompanha cada operação até o fim.- Restauração. Restaurar um snapshot responde
202na hora com umjob_id, e a restauração roda em segundo plano. Uma aplicação é reconstruída e reiniciada quando ela termina. Enquanto uma restauração roda, escritas no recurso respondem409 RESTORE_IN_PROGRESS; ler e excluir o recurso continuam permitidos. Um banco que não consegue carregar os dados mantém os que tinha. - Criar um snapshot. Responde
201com o snapshot quando ele fica pronto em até 90 segundos, ou202com umjob_idquando demora mais. O snapshot aparece na lista quando fica pronto. - Criar uma aplicação ou um banco a partir de um snapshot. Responde
202(antes,201) com umrestore_job_id, sem limite de tamanho além do armazenamento do novo recurso (antes, 100 MB para uma aplicação). Se a restauração falhar, uma aplicação criada a partir de código é excluída, enquanto um banco e uma aplicação que roda uma imagem Docker própria são mantidos como estão, para que nada do que você gravou se perca. - Espaço insuficiente. Um snapshot que não cabe no armazenamento do destino é recusado antes de qualquer alteração com
SNAPSHOT_EXCEEDS_STORAGE, e em um banco a resposta diz o menor tamanho de memória que o comporta. - Um snapshot que não confere com o que foi registrado quando foi feito é recusado com
SNAPSHOT_CORRUPTED, e nada muda. - Enquanto uma aplicação recebe um snapshot, deploys, rollbacks, reinícios, inícios, paradas, mudanças de variáveis de ambiente, restaurações e as escritas do gerenciador de arquivos esperam: respondem
409 OPERATION_IN_PROGRESS, e você pode tentar de novo em instantes.
API
- Listar jobs de snapshot (
GET /v1/users/{id}/snapshots/jobs) e Obter job de snapshot (GET /v1/users/{id}/snapshots/jobs/{job_id}) acompanham um snapshot ou uma restauração até ostatusserready,skippedoufailed, com oreasonquando falha. Os dois usam o escoposnapshots:read. A lista aceitalimitde 1 a 50 (padrão 10; um valor fora desse intervalo responde400 VALIDATION_ERROR), e oscopeé opcional ao ler um job só. - Restaurar snapshot responde
202comresponse.job_id. Amessageda resposta antiga deixou de existir. - Criar snapshot da stack também responde
202, com oiddo snapshot da stack e um job de snapshot por membro (response.jobs), bancos primeiro; antes, esperava todos os membros e podia ser cortado numa stack grande. Cada membro é um snapshot manual comum, e a cota e as conferências de todos acontecem antes do202. Listar snapshots da stack mostra o snapshot da stack comopendinge depoisready(status), comsnapshot_id: nulle ojob_idde cada membro enquanto estápending; um snapshot da stack com membro que falhou não é listado, e os que deram certo continuam como snapshots comuns. Um snapshot da stackpendingnão pode ser restaurado (409 OPERATION_IN_PROGRESS), e um segundo não começa enquanto um está rodando. - Restaurar snapshot da stack também responde
202agora, com um job por membro (response.jobs, cada um comresource_id,resource_type,job_ide, quando se aplica,warning). Os membros são restaurados em ordem, bancos primeiro; acompanhe cada job em Obter job de snapshot. Se um membro falha, os seguintes não são restaurados e os jobs deles falham comSTACK_RESTORE_MEMBER_FAILED. A resposta antiga, que esperava todos os membros, deixou de existir. - Os snapshots da lista agora trazem
origin(manualouautomatic). Os jobs de snapshot trazem o mesmoorigin, ausente nos jobs de restauração.skippedé o status de um job que não fez nada porque o recurso deixou de existir ou, em um banco, está parado. restore_job_id(sempre presente,nullquando não há restore) no status de aplicações e bancos de dados (Status da aplicação, Status de todas as aplicações, Status do banco de dados e Status de todos os bancos de dados): vem preenchido enquanto um restore do recurso está na fila ou rodando, e você o acompanha em Obter job de snapshot. Enquanto estiver preenchido, o status da aplicação não trazinstalling.daily_backupsnos recursos do plano eauthor_idno snapshot foram removidos (author_idera semprenull). Usedaily_app_backupsedaily_database_backupspara o plano, eoriginpara saber o que tirou um snapshot.- Um job de snapshot que falhou agora traz os
detailsdo seureason(por exemplo, o espaço necessário e o disponível emSNAPSHOT_EXCEEDS_STORAGE), um job de restauração traz osnapshot_idque ele restaura, e um jobsnapshotque estáreadysempre tem osnapshot_idque produziu. - Um recurso que não é encontrado agora responde
404(APP_NOT_FOUND,DATABASE_NOT_FOUNDouIMAGE_NOT_FOUND) em vez de403 ACCESS_DENIED.ACCESS_DENIEDcontinua para o membro de workspace sem a permissão da ação. Baixar um snapshot que não foi encontrado responde404 SNAPSHOT_NOT_FOUND(o403fica só para o membro de workspace sem permissão), e os jobs de snapshot de um recurso que não existe voltam como lista vazia. Workspaces seguem a mesma regra: um workspace que não é encontrado responde404 WORKSPACE_NOT_FOUNDem vez de403 WORKSPACE_PERMISSION_DENIED, que agora só indica um membro cujo papel não tem a permissão. WORKSPACE_INVITES_DISABLEDfoi removido dos códigos de erro e não é mais retornado. Convidar por e-mail uma conta que desligouworkspace_invites_enabledagora responde como qualquer outro convite: ele fica pendente e nenhum e-mail é enviado, então a resposta não revela se o e-mail tem conta. A opção só controla se a conta recebe o e-mail de convite.- Novos códigos de erro:
STACK_RESTORE_MEMBER_FAILED,RESTORE_IN_PROGRESS,SNAPSHOT_EXCEEDS_STORAGE,SNAPSHOT_CORRUPTED,SNAPSHOT_TIMEOUTeDATABASE_NOT_READY. Veja os códigos de erro. - Em uma atualização de template, as etapas
snapshoterollbackdo job de deploy trazemjobs(resource_id,resource_type,job_id) com o job de snapshot ou de restauração de cada recurso, para você acompanhar o progresso em Obter job de snapshot.
Clientes atualizados
Os SDKs, a CLI, o servidor MCP e a extensão do VS Code acompanham o novo comportamento.- SDKs (JavaScript, Python e Go).
restoreresponde com ojob_idda restauração, e cada SDK consegue acompanhar um job até o fim (snapshotJobs.wait,snapshot_jobs.waiteSnapshotJobs.Wait), e há helpers que fazem os dois passos (snapshots.createAndWait,stacks.snapshots.createAndWaiterestoreAndWait, com os mesmos nomes em snake_case no Python e no estilo Go no Go).apps.downloadfaz um snapshot manual, espera ele ficar pronto e baixa, e exigesnapshots:writeesnapshots:read. Um snapshot que demora mais é acompanhado até o fim, e criar uma aplicação ou um banco a partir de um snapshot devolve orestore_job_id. Os downloads também podem ir em fluxo direto para um arquivo, com memória constante, qualquer que seja o tamanho:snapshots.downloadToFile,snapshots.downloadStream,apps.downloadToFileeapps.downloadStreamem JavaScript,download_to_fileedownload_streamem Python, eSnapshots.DownloadToFileeApps.DownloadToFileem Go. - CLI.
vertra snapshot restoreagora espera a restauração terminar por padrão (use--no-waitpara receber ojob_idna hora). O novovertra snapshot jobmostra um job de snapshot ou de restauração evertra snapshot jobslista os jobs.vertra app downloadmantém o nome: faz um snapshot manual, espera ele ficar pronto e baixa o ZIP (conta na cota de snapshots manuais e exigesnapshots:writeesnapshots:read). Os downloads são gravados no arquivo conforme os bytes chegam. - MCP.
restore_snapshotresponde com umjob_id, ecreate_snapshotresponde{ status: "accepted", job_id }quando demora mais. A nova ferramentalist_snapshot_jobslista os jobs de um recurso, eget_snapshot_jobacompanha um job (exige ojob_id).download_appmantém o nome: faz um snapshot manual, espera ele ficar pronto e baixa.create_appecreate_databaseaceitam umsnapshot_id.download_appedownload_snapshottambém gravam o arquivo conforme ele chega. - Extensão do VS Code. Restaurar mostra o progresso enquanto espera o job começar e rodar.
Baixe um projeto de qualquer tamanho
Um projeto de qualquer tamanho pode ser baixado, sem o limite de 300 MB: você faz um snapshot manual e o baixa. O snapshot aparece na sua lista, usa a cota de snapshots manuais e é mantido por 30 dias.- Criar snapshot (
POST /v1/users/{id}/snapshots?scope=applications) responde201com o snapshot, ou202com umjob_id. - Depois de um
202, acompanhe o job em Obter job de snapshot até ostatusserready; ele traz osnapshot_id. - Baixar snapshot (
GET /v1/users/{id}/snapshots/{snapshot_id}/download?scope=applications) devolve o ZIP.
DOWNLOAD_TOO_LARGEdeixou de ser devolvido ao baixar uma aplicação. Para um arquivo só, o gerenciador de arquivos continua lendo (GET /v1/apps/{id}/files/content).- Uma conta sem plano ativo não consegue fazer snapshots novos, mas ainda lista e baixa os que tem, inclusive o que a plataforma guardou antes de remover um projeto.
Mudanças que podem quebrar a sua integração
GET /v1/apps/{id}/downloadfoi removida. Agora responde404. Use os três passos acima. Uma chave que só temapps:filesnão baixa mais o projeto: precisa desnapshots:writepara criar o snapshot e desnapshots:readpara baixá-lo (403 API_KEY_SCOPE_DENIED, comdetails.requiredigual asnapshots:read). Odownload_idda resposta antiga saiu junto. Versões de SDKs, CLI, MCP e extensão que chamam a rota antiga precisam ser atualizadas.- Redefinir banco de dados responde
{ "response": { "status": "success" } }(antes, a string"success"). - Criar uma aplicação ou um banco a partir de um snapshot responde
202(antes,201), com o mesmo corpo e orestore_job_id. warningpassou para cada item da restauração de stack. Em Restaurar snapshot da stack,IMAGE_VERSION_NOT_FOUNDagora vem emresponse.jobs[].warning, na aplicação a que se aplica; owarningno nível de cima deixou de existir.RESTORE_COOLDOWNtrazdetails.retry_after, também no rollback. Toda resposta comdetails.retry_aftertambém envia o headerRetry-Aftercom o mesmo número de segundos.- Redefinir banco de dados agora exige o escopo
databases:deletena chave de API (antes,databases:write) e, em um workspace, a permissãodatabases:delete(antes,databases:manage). Uma chave comdatabases:writee semdatabases:deleteresponde403 API_KEY_SCOPE_DENIED.
Novos limites de snapshot
Os snapshots manuais passam a ser medidos nas últimas 24 horas em vez do dia de calendário, e o limite cresce com o seu plano.- Cota da conta: 8 snapshots manuais por GB de RAM do plano em qualquer janela de 24 horas, no mínimo 2, sem teto: 8 no Starter 1, 16 no Starter 2, 32 a 64 no Pro, 96 a 192 no Business e 256 a 4.096 no Enterprise. Uma vaga volta 24 horas depois de usada, não à meia-noite. Antes, eram de 5 a 64 por dia.
- Por recurso: um snapshot a cada 3 minutos (antes, um a cada 5 minutos e até 5 por dia). Não há mais limite diário por recurso.
- Por usuário: uma requisição a cada 5 segundos.
- Restauração: 60 segundos entre duas restaurações da mesma aplicação; em um banco, 60 segundos para quem pede e 120 segundos por banco (antes, 30 segundos). Criar uma aplicação ou um banco a partir de um snapshot também espera 60 segundos por usuário (
429 RESTORE_COOLDOWN). SNAPSHOT_RATE_LIMITEDagora trazdetails.scoperesourceouaccount;accounttambém trazresets_at. O escoporesource_dailydeixou de existir, e pedir de novo dentro dos 5 segundos responde o429 RATE_LIMIT_EXCEEDEDgenérico, comretry_after.- Os snapshots não são mais limitados a 4 GB: o limite é o armazenamento do recurso.
Backups diários por plano
Os backups diários agora seguem o plano: aplicações a partir do Business e bancos a partir do Pro. Os planos Starter não têm backup diário, só snapshots manuais. Um banco que está parado não entra no backup diário.- Retenção: todo snapshot é mantido por 30 dias. Entre os backups diários, o mais recente de cada recurso fica 30 dias e os anteriores ficam 7.
- Os backups diários não usam a cota de snapshots manuais.
- Listar planos traz os novos recursos
daily_app_backupsedaily_database_backups.
Gerenciador de arquivos
O gerenciador de arquivos lê e salva arquivos de até 10 MiB. Um arquivo maior responde413 FILE_TOO_LARGE com details.max_bytes; use o envio de arquivos para arquivos maiores e o download de um snapshot para o projeto inteiro.Veja Faça backup e restaure com snapshots e Planos e limites.