Upgrades

Fixe a sua versão

Nunca rode :latest em produção. Uma tag não fixada significa que um restart não planejado pode baixar uma nova versão com novas migrations em um momento arbitrário.

O Studio publica imagens no GHCR, com tags por release ao lado de latest:

ghcr.io/seeyuai/studio
ghcr.io/seeyuai/realtime
ghcr.io/seeyuai/migrations

Fixe app, realtime e migrations na mesma tag. Eles compartilham um schema de banco de dados. Um app mais novo que suas migrations roda contra um schema sem colunas que ele espera; um app mais antigo que suas migrations roda contra um schema que ele não entende. Tags divergentes são a falha de upgrade autoinfligida mais comum.

app:
  image:
    tag: "v1.2.3"  # a tag from the releases page
realtime:
  image:
    tag: "v1.2.3"  # a tag from the releases page
migrations:
  image:
    tag: "v1.2.3"  # a tag from the releases page

Quando image.tag não está definido, ele assume o appVersion do chart, que muda quando você atualiza o chart. Definir a tag explicitamente desacopla as duas coisas. Para determinismo máximo, fixe o image.digest:

app:
  image:
    digest: "sha256:..."

Por padrão, as imagens acompanham latest. Para fixar, defina STUDIO_VERSION no .env com uma tag das notas de release que a Seeyu envia com cada bundle:

# .env
STUDIO_VERSION=v1.2.3

Uma única variável controla as três imagens acopladas ao schema, então elas não podem divergir. O serviço cron fica deliberadamente de fora — ele só faz chamadas HTTP e não compartilha schema, então acompanha latest a menos que você fixe STUDIO_CRON_VERSION.

Como as migrations rodam

As migrations são arquivos SQL do Drizzle aplicados por uma imagem dedicada.

  • Kubernetes — um init container no Deployment do app. Todo pod do app espera as migrations terminarem antes de iniciar, então uma migration que falha bloqueia o rollout em vez de iniciar um app contra um schema divergente. O container é idempotente, então é um no-op nos pods que iniciam depois do primeiro.
  • Docker Compose — um serviço migrations de execução única com restart: no, que roda antes do app.

As migrations são somente para frente. Não existem down-migrations, e é por isso que o backup pré-upgrade abaixo não é opcional.

Procedimento de upgrade

Leia as notas de release

Consulte as notas de release que a Seeyu envia com cada bundle em busca de novas variáveis de ambiente obrigatórias e mudanças que quebram compatibilidade. Quando a versão minor do chart muda, leia também as notas de upgrade no README.md dele — upgrades de chart às vezes renomeiam ou removem chaves de values.

Faça um backup

Tire um snapshot do banco de dados imediatamente antes do upgrade. Como as migrations são somente para frente, esse snapshot é o seu único caminho de rollback para mudanças de schema.

# Managed Postgres — take a manual snapshot
aws rds create-db-snapshot --db-instance-identifier studio-db \
  --db-snapshot-identifier "studio-pre-upgrade-$(date +%Y%m%d)"

# Bundled Postgres — the Helm chart's database is named `studio` by default
# (Docker Compose uses `studio`; the cloud example values files override to `studio`)
kubectl exec -n studio statefulset/studio-postgresql -- \
  pg_dump -U postgres -Fc studio > "pre-upgrade-$(date +%F).dump"

Ensaie com dados reais

Surpresas em migrations normalmente vêm da forma dos dados, não do schema, então uma execução em staging contra uma cópia dos dados de produção pega muito mais coisa do que uma execução contra um banco vazio.

Aplique

helm upgrade studio ./helm/studio \
  --namespace studio \
  --values my-values.yaml

Veja um preview primeiro, se a versão do chart mudou:

helm diff upgrade studio ./helm/studio -n studio --values my-values.yaml

Depois acompanhe o rollout:

kubectl rollout status -n studio deploy/studio-app --timeout=10m
kubectl logs -n studio deploy/studio-app -c migrations --tail=100
bun run studio update
docker compose -f docker-compose.prod.yml logs migrations

bun run studio update baixa as versões configuradas por STUDIO_VERSION (ou latest quando ela não está definida), recria os serviços que mudaram e preserva os volumes de dados. É equivalente a rodar docker compose pull seguido de docker compose up -d.

Existe uma janela curta em que o app fica indisponível enquanto os containers reiniciam. O Compose não tem mecanismo de rolling update — planeje uma janela de manutenção, ou use Kubernetes se você precisa de upgrades sem downtime.

Verifique

Rode o checklist de verificação. No mínimo: entre na conta, abra um workflow, execute-o, envie um arquivo e confirme que os jobs em background continuam disparando.

Quando uma migration falha

Os pods do app não vão ficar prontos — isso é intencional.

kubectl logs -n studio deploy/studio-app -c migrations --tail=200
docker compose -f docker-compose.prod.yml logs migrations

Causas comuns:

SintomaCausa
permission denied to create extension "vector"O usuário do banco não tem direitos de superusuário. Crie a extensão pgvector manualmente como admin e rode novamente.
Connection refused / timeoutDATABASE_URL errada, ou o banco não está acessível a partir do pod. Verifique a network policy e as credenciais.
Lock timeout em uma tabela grandeUma query de longa duração está bloqueando o DDL. Drene o tráfego e tente de novo em uma janela tranquila.
Violação de constraintDados pré-existentes conflitam com uma nova constraint. Capture o erro, restaure o backup pré-upgrade e abra um ticket com a mensagem exata.

Não edite manualmente a tabela de migrations para pular uma migration que falhou — o schema e as expectativas do Studio vão divergir de formas que só aparecem muito depois.

Fazendo rollback

Rollback só da aplicação (nenhuma migration rodou, ou as novas migrations são aditivas):

helm rollback studio -n studio
# Docker Compose — set the previous tag and restart
docker compose -f docker-compose.prod.yml up -d

Rollback depois de uma mudança de schema exige restaurar o banco a partir do backup pré-upgrade, porque as migrations são somente para frente:

  1. Reduza o app para zero réplicas.
  2. Restaure o snapshot do banco pré-upgrade.
  3. Reimplante a tag de imagem anterior nas três imagens.
  4. Verifique.

Isso perde tudo que foi gravado depois do snapshot. É por isso que o backup pré-upgrade e um ensaio em staging importam mais aqui do que na maioria dos sistemas.

Common Questions

Você pode fazer rollback da aplicação com helm rollback. Mudanças de schema não podem ser revertidas — as migrations são somente para frente — então reverter uma release que adicionou migrations significa restaurar o backup do banco pré-upgrade e perder tudo que foi gravado desde então.
As migrations são aplicadas em sequência, então saltar várias releases geralmente funciona no plano mecânico. É mais arriscado — essas combinações recebem menos testes, e você absorve mudanças de comportamento de várias releases de uma vez. Faça o upgrade em passos menores quando puder.
No Kubernetes com replicaCount > 1, o rolling update mantém o app disponível, ainda que as migrations rodem antes dos novos pods iniciarem. No Docker Compose existe uma janela de restart — o Compose não tem mecanismo de rolling update.
Escala e Alta DisponibilidadeSolução de problemas