setup:upgrade travado no Magento 2.4.8: destravar o lock e concluir

O setup:upgrade está parado em “Module Vendor_Modulo: Running schema” faz vinte minutos, ou você deu Ctrl+C e agora toda tentativa morre na mesma linha, com a loja presa na página de manutenção. Antes de qualquer coisa, tire um dump do banco: o que vem abaixo mexe em schema aplicado pela metade.

O processo morreu mesmo?

ps aux | grep '[s]etup:upgrade'
kill 24817
bin/magento maintenance:status
bin/magento maintenance:disable

O setup:upgrade liga o modo de manutenção no começo e desliga no fim. Interrompido no meio, ele deixa o var/.maintenance.flag pra trás, e a loja segue fora do ar mesmo sem nenhum processo rodando. Use o kill normal antes do kill -9: com -9 o PHP não fecha a conexão, o ALTER continua vivo do lado do MySQL segurando o metadata lock, e a próxima tentativa trava no primeiro módulo sem explicar por quê. Um SHOW PROCESSLIST confirma isso em dois segundos.

Limpar o generated e ler o estado do banco

rm -rf var/cache/* var/page_cache/* generated/code generated/metadata

bin/magento setup:db:status
mysql -u magento -p loja -e "SELECT module, schema_version, data_version FROM setup_module WHERE module = 'Vendor_Modulo';"

Código velho em generated apontando pra uma classe que o módulo novo mudou é a causa mais comum do erro de dependência no meio do upgrade. O setup:db:status diz em uma linha se schema e dados estão em dia, e o setup_module conta o resto: schema_version preenchida com data_version atrasada significa que o schema subiu e o patch de dados não.

Se um data patch explodiu no caminho, o Magento não roda ele de novo, porque o nome já foi gravado na tabela patch_list. Apagar aquela linha libera a nova tentativa — mas com o dump já feito e com WHERE no nome do patch, nunca um DELETE solto na tabela. Depois disso, o upgrade normal:

bin/magento setup:upgrade --keep-generated --no-interaction
bin/magento setup:di:compile
bin/magento cache:flush

O –keep-generated impede o setup:upgrade de mexer no generated que você acabou de limpar; quem regenera é o di:compile logo depois. E o –no-interaction evita que o comando fique esperando resposta num deploy automatizado, que é onde ele mais costuma parecer congelado sem estar.

Se travou nisso e precisa de ajuda, me chama aqui.