Migrações

A plataforma não executa migrations por você: o seu app (ou uma ferramenta de migrations da sua linguagem) as aplica usando a DATABASE_URL entregue (Conexão e referências).

Regras

• Toda migration tem down e foi testada (suba e desça em ambiente local antes do deploy).
• Mudanças destrutivas em dois passos (expand-contract): adicione o novo, migre o código, só depois remova o antigo. Nunca DROP ou renomeação destrutiva num passo só.
• Faça um backup sob demanda antes de uma migration arriscada.
• Migrations usam SQL parametrizado e a mesma conexão TLS (sslmode=verify-full, ssl=true ou LIBSQL_URL).
• Cota: um banco acima de quota_mb fica read_only; migration que cresce dados pode falhar por isso.

Onde rodar

Rode as migrations na inicialização do serviço, antes de aceitar tráfego, de forma idempotente (a ferramenta guarda a versão aplicada). Com mais de uma instância subindo, use o lock da própria ferramenta de migrations. Se a migration falha, o app deve sair com erro: o deploy não fica ready e o rollback (Rollback) volta ao deploy anterior.

Atenção: o rollback do deploy não desfaz o schema. Se o código antigo for incompatível com a migration já aplicada, rode a down ou restaure um backup.

Se algo falhar

Sintoma	O que fazer
deploy não chega a ready por erro de migration	Leia o log de build/runtime (Logs), corrija a migration e faça novo deploy.
read_only / erro de escrita	Cota estourada: libere espaço; volta ao normal ao baixar do limite.
503 unavailable ao conectar	Repita com backoff; o app não deve derrubar o deploy por indisponibilidade transitória do banco além do tempo de retry.