Modo de manutenção somente leitura: continuar a atender leituras com as escritas em pausa

O que é

Um modo de manutenção somente leitura é um estado deliberado do serviço em que as leituras funcionam e todo caminho de escrita devolve uma recusa temporária e bem identificada. Ele é aplicado em duas camadas: a aplicação verifica uma flag antes de qualquer escrita e exibe um banner, e o banco de dados rejeita escritas como rede de segurança. A documentação do PostgreSQL descreve o default_transaction_read_only, que controla o estado somente leitura padrão de cada nova transação, e afirma que uma transação SQL somente leitura não pode alterar tabelas não temporárias. No HTTP, a RFC 9110 define o código 503 (Service Unavailable) para um servidor temporariamente incapaz de tratar requisições, inclusive por manutenção programada, e afirma que o Retry-After enviado com um 503 indica por quanto tempo o serviço deve ficar indisponível para o cliente.

Por que importa

A maior parte das manutenções afeta as escritas: mover o armazenamento, promover uma réplica, executar uma migração longa. As leituras muitas vezes continuam funcionando sem problema durante todo o processo. Uma página de indisponibilidade total para uma migração de armazenamento de duas horas joga fora uma disponibilidade que existia, enquanto uma falha sem explicação ("something went wrong") durante a mesma operação gera carga no suporte e novas tentativas às cegas.

Como aplicar

• Adicione um único interruptor (flag de configuração, feature toggle ou variável de ambiente) que a aplicação leia no início de cada caminho de escrita. O interruptor é a autoridade; a configuração do banco é a rede de segurança.
• Devolva uma recusa consistente: HTTP 503 com Retry-After e um corpo legível por máquina que indique manutenção, além de um banner visível na interface. Assim, clientes bem comportados esperam; os jobs na fila devem ser pausados em vez de falhar.
• Defina default_transaction_read_only = on, ou aponte a aplicação para uma réplica de leitura, durante a janela, de modo que um caminho de escrita esquecido falhe no banco em vez de corromper a migração.
• Pause explicitamente os processos que escrevem em segundo plano: agendadores, consumidores de fila e receptores de webhook que persistem dados.
• Ensaie em staging: ative o interruptor, execute os testes de escrita e espere 503; desative-o e espere sucesso. Cronometre as duas trocas.
• Anuncie a janela na página de status com o efeito esperado ("você pode navegar, mas não salvar").

Armadilhas

Escritas escondidas dentro de leituras (timestamps de último acesso, contadores de visualização, renovações de sessão) que falham e quebram a renderização da página. Caches que armazenaram as respostas de erro do modo. Esquecer de reverter a configuração do banco depois da janela, e por isso o interruptor fica em um só lugar e a checklist termina com "verificar escritas".

Mantendo a janela fora dos health checks e dos orçamentos de erro

Um 503 nos caminhos de escrita é correto para os clientes, mas enganoso para tudo o que monitora o serviço. Antes do primeiro ensaio, faça três mudanças junto com o interruptor: os endpoints de saúde usados por balanceadores de carga e orquestradores não devem exercitar um caminho de escrita, ou devem tratar o estado somente leitura como saudável, para que as instâncias continuem em rotação; as recusas de manutenção levam um marcador (um cabeçalho de resposta ou um corpo com um tipo de problema próprio) que o SLO de taxa de erros e as regras de alerta excluem e que os dashboards mostram como uma série separada; e o Retry-After é definido com o tempo restante esperado da janela, e não com alguns segundos, para que os clientes que tentam de novo esperem em vez de fazer polling. Verifique os três pontos em staging observando o estado dos alvos no balanceador de carga e o painel de taxa de erros durante o ensaio, e não apenas as respostas HTTP.