Deploys pequenos em PHP sem agravar incidentes

Uma estratégia de deploy com rollback em PHP não consiste em manter um botão para voltar à versão anterior. É um projeto operacional que permite retirar código sem deixar dados incompatíveis, jobs assíncronos duplicados ou processos em andamento executando regras já descartadas. O rollback deve ser uma opção preparada antes da publicação, não uma reação improvisada durante um incidente.

Deploys pequenos reduzem o raio de impacto: introduzem menos variáveis, facilitam a identificação da alteração causadora e encurtam a recuperação. No entanto, uma alteração reduzida pode afetar pagamentos, autenticação, permissões, inventário ou comunicações. Por isso, o tamanho da alteração não substitui controles técnicos nem critérios explícitos para interromper uma publicação.

O rollback é projetado antes de existir um incidente

Reverter código é simples apenas quando a alteração não modificou o estado compartilhado. Em produção, uma versão pode ter gravado dados, enviado mensagens a uma fila, ativado uma tarefa agendada ou chamado um serviço externo. Voltar a um commit anterior sem revisar esses efeitos pode ocultar o erro inicial e criar outro mais difícil de diagnosticar.

Antes de aprovar um deploy, a equipe deve conseguir responder a quatro perguntas:

• Qual artefato será publicado: versão identificável, construída uma única vez e disponível para restauração.
• Qual estado é alterado: esquema do banco de dados, cache, arquivos, índices de busca, filas, provedores externos e configuração.
• Qual versão pode ler e gravar esse estado: código novo, código anterior ou ambos durante uma janela temporária.
• Qual sinal obriga a agir: limite de erros, falha de uma rota crítica, atraso na fila, degradação de latência ou impacto funcional confirmado.

A unidade de reversão deve estar definida. Pode ser toda a aplicação, um serviço, um consumidor de fila ou uma funcionalidade ativada por configuração. Não convém confundir deploy, que instala software, com release, que disponibiliza um comportamento. Separá-los permite fazer deploy de código inativo e expô-lo depois de validar as condições técnicas.

Classificar as alterações conforme sua capacidade de reversão

Nem todas as alterações admitem o mesmo tratamento. Um ajuste de apresentação ou uma correção interna sem mudanças de estado geralmente pode ser revertido mediante a restauração do artefato anterior. Em contrapartida, uma migração destrutiva, uma alteração de contrato de API ou uma nova regra de negócio que já produziu efeitos externos exige uma estratégia adicional.

Alterações normalmente reversíveis

• Correções de lógica que preservam os contratos de entrada e saída.
• Alterações de templates, desde que não dependam de campos removidos.
• Novas rotas ou endpoints que não modificam recursos existentes.
• Otimizações internas sem alterações de esquema nem de semântica.

Alterações que exigem compatibilidade temporária

• Renomeação ou substituição de colunas, campos JSON e eventos.
• Alterações de formato em mensagens de fila ou webhooks.
• Novas restrições de validação sobre dados já existentes.
• Modificações de autenticação, permissões ou regras de cálculo.
• Integrações que criam cobranças, pedidos, notificações ou modificações em sistemas externos.

Para dados compartilhados, o padrão mais seguro geralmente é expandir, migrar, contrair. Primeiro, adiciona-se uma estrutura compatível; depois, o código oferece suporte temporariamente ao formato antigo e ao novo, os dados necessários são migrados ou preenchidos e, somente após a retirada definitiva da versão antiga, o que está obsoleto é removido. Por exemplo, adicionar uma coluna nullable e gravar ambos os campos durante uma transição é recuperável; renomear ou remover diretamente uma coluna usada pela versão anterior não é.

As migrações devem ser tratadas como entregáveis independentes do código. Uma migração somente para frente pode estar correta, mas então o plano deve declarar que o rollback da aplicação não implica reverter o esquema. Evite uma migração automática de downgrade se ela puder apagar dados gerados após a alteração ou se seu resultado depender do estado real de produção.

Preparar artefatos, configuração e pré-condições

O mesmo artefato deve avançar entre ambientes. Compilar dependências ou modificar código diretamente em cada servidor impede saber qual versão está sendo executada e dificulta restaurar uma versão conhecida. Em uma aplicação PHP, o artefato pode incluir o código versionado e as dependências resolvidas; a configuração sensível e específica do ambiente deve ser injetada por mecanismos externos, não ficar incorporada ao pacote.

Registre, no mínimo, o identificador da versão, a data de publicação, a configuração funcional relevante e o responsável pela decisão. Isso acelera tanto a investigação quanto o retorno a uma versão específica.

Antes do deploy, verifique de forma automatizada e visível:

• Testes unitários, de integração e de contrato proporcionais à alteração.
• Resolução de dependências e compatibilidade com a versão do PHP, extensões e serviços exigidos.
• Estado das migrações, plano de expansão dos dados e tempo estimado de execução.
• Saúde das dependências: banco de dados, cache, armazenamento, APIs internas e provedores críticos.
• Capacidade e comportamento de workers, filas e tarefas agendadas.
• Disponibilidade do artefato anterior e procedimento testado para restaurá-lo.

As verificações não devem se limitar a confirmar que o processo PHP responde. Uma rota de health check pode confirmar que o PHP-FPM está ativo e, ainda assim, não detectar um erro de autorização, uma consulta lenta ou um consumidor bloqueado. Defina pequenas rotas sintéticas que representem operações críticas sem executar ações irreversíveis.

Publicar gradualmente com responsáveis e limites claros

A exposição gradual reduz o alcance de uma falha, mas só funciona se o tráfego ou as instâncias puderem ser separados de forma real. É possível atualizar uma fração das instâncias, ativar uma capacidade para um segmento controlado ou direcionar parte das requisições para a nova versão. A escolha depende da arquitetura e do tipo de estado compartilhado.

Atribua funções explícitas durante a janela de publicação:

• Uma pessoa executa e registra as etapas.
• Outra observa métricas, logs e traces relevantes.
• Um responsável tem autoridade para interromper ou reverter sem aguardar aprovações ambíguas.
• A equipe de negócio ou suporte conhece os efeitos esperados se a alteração afetar uma operação sensível.

Estabeleça também uma janela de observação. Não basta publicar, ver uma resposta HTTP correta e passar para a próxima alteração. Alguns defeitos surgem quando uma fila é processada, um cache expira, uma tarefa agendada é executada ou um usuário conclui um fluxo mais longo.

Verificar depois: serviço, dados e efeitos de negócio

A verificação posterior deve combinar sinais técnicos e funcionais. As métricas gerais são úteis, mas uma média de latência estável pode ocultar a falha de uma operação minoritária e crítica.

• Rotas críticas: autenticação, leitura e escrita principais, pagamentos, criação de pedidos ou ações sujeitas a permissões.
• Erros: exceções PHP, respostas 5xx, aumentos inesperados de 4xx, erros de validação e falhas de dependências.
• Desempenho: latência por endpoint, saturação de workers, conexões de banco de dados e consumo de recursos.
• Processamento assíncrono: tamanho e idade da fila, tentativas, mensagens com falha e idempotência.
• Efeitos de negócio: transações incompletas, duplicadas, mudanças de estado inválidas ou quedas em conversões que a equipe possa verificar.

Os critérios de decisão devem ser verificáveis. Continue se as rotas definidas funcionarem, não houver aumento sustentado de erros e as filas permanecerem dentro do atraso aceitável. Interrompa a expansão se surgir uma anomalia que ainda exija diagnóstico. Reverta se o artefato anterior for compatível com o estado atual e a restauração reduzir claramente o impacto. Corrija para frente se reverter quebraria a compatibilidade, não desfaria efeitos externos ou demoraria mais do que aplicar uma correção isolada e validada.

Gerenciar filas e processos iniciados por uma versão retirada

Os workers são uma fonte comum de rollbacks incompletos. O código web pode ser retirado enquanto permanecem mensagens criadas pela nova versão ou processos de longa duração que continuam executando lógica antiga. O plano deve indicar como drenar, pausar, reiniciar ou isolar consumidores sem perder rastreabilidade.

Considere um fluxo hipotético: uma aplicação PHP publica uma mensagem para confirmar um pedido. A nova versão adiciona um campo à mensagem e modifica o estado do pedido antes de enviá-la. Se for necessário retirá-la, o consumidor anterior deve ignorar com segurança o campo adicional ou a mensagem deve conter uma versão que permita roteá-la para um consumidor compatível. Além disso, a confirmação deve usar uma chave idempotente para que uma nova tentativa não produza duas ações externas.

{
  "event": "order.confirmation_requested",
  "schema_version": 2,
  "idempotency_key": "operacion-unica",
  "order_id": "identificador"
}

Antes de reverter, pause a entrada de novos jobs se necessário, identifique as mensagens em trânsito e confirme quais consumidores podem processá-las. Depois, revise as falhas e as tentativas de forma controlada. Não apague uma fila para recuperar rapidez: isso pode eliminar evidências necessárias ou deixar operações de negócio parcialmente concluídas.

Transformar o plano em uma prática repetível

Uma estratégia madura não depende da memória individual. Mantenha um runbook breve por serviço com os comandos aprovados, localização dos logs, painéis de observação, responsáveis, condições de parada e limites conhecidos de reversão. Teste o procedimento em um ambiente representativo, especialmente após alterações de infraestrutura, filas, migrações ou integrações.

Após cada incidente ou rollback, revise se houve falha na detecção, na compatibilidade, na automação ou na decisão. O objetivo não é evitar todo rollback; é poder escolher entre reverter e corrigir para frente com informação suficiente, sem transformar um incidente localizado em perda de dados ou em uma interrupção maior.