Read-only maintenance mode: serving reads while writes are paused

What it is

A read-only maintenance mode is a deliberate service state in which reads succeed and every write path returns a temporary, well-labelled refusal. It is enforced at two layers: the application checks a flag before any write and shows a banner, and the database rejects writes as a backstop. The PostgreSQL documentation describes default_transaction_read_only, which controls the default read-only status of each new transaction, and states that a read-only SQL transaction cannot alter non-temporary tables. For HTTP, RFC 9110 defines 503 (Service Unavailable) for a server temporarily unable to handle requests, including scheduled maintenance, and states that Retry-After sent with a 503 indicates how long the service is expected to be unavailable to the client.

Why it matters

Most maintenance touches writes: moving storage, promoting a replica, running a long migration. Reads are often fine throughout. A full outage page for a two-hour storage move throws away availability that was available, while an unlabelled failure ("something went wrong") during the same move produces support load and blind retries.

How to apply

• Add one switch (configuration flag, feature toggle or environment variable) that the application reads at the top of every write path. The switch is the authority; the database setting is the safety net.
• Return a consistent refusal: HTTP 503 with Retry-After and a machine-readable body that names maintenance, plus a visible banner in the interface. Well-behaved clients then wait; queued jobs should pause rather than fail.
• Set default_transaction_read_only = on, or point the application at a read replica, for the window, so a forgotten write path fails at the database instead of corrupting the migration.
• Pause background writers explicitly: schedulers, queue consumers, webhook receivers that persist.
• Rehearse in staging: flip the switch, run the write tests and expect 503s, flip it back and expect success. Time both flips.
• Announce the window on the status page with the expected effect ("you can browse but not save").

Pitfalls

Writes hidden inside reads (last-seen timestamps, view counters, session refreshes) that fail and break page rendering. Caches that stored the mode's error responses. Forgetting to revert the database setting after the window, which is why the switch lives in one place and the checklist ends with "verify writes".

Keeping the window out of health checks and error budgets

A 503 on write paths is correct for clients and misleading for everything that watches the service. Before the first rehearsal, make three changes with the switch: health endpoints used by load balancers and orchestrators must not exercise a write path, or must treat the read-only state as healthy, so instances stay in rotation; maintenance refusals carry a marker (a response header or a distinct problem-type body) that the error-rate SLO and the alerting rules exclude and dashboards show as their own series; and Retry-After is set to the expected remaining window rather than a few seconds, so retrying clients wait instead of polling. Verify all three in staging by watching the load balancer's target state and the error-rate panel during the rehearsal, not only the HTTP responses.