Skip to content

CONCEPT Cited by 2 sources

Query buffering cutover

Definition

Query buffering cutover is the technique of briefly holding ("buffering") incoming client queries at a proxy layer while the backend behind the proxy is swapped from one database to another. The client never sees an error or a dropped connection; once the swap is complete (typically sub-second), the buffered queries are released against the new backend and normal service resumes. It is the last-mile primitive that converts a carefully-prepared database migration into a literally zero-downtime one from the application's perspective.

Contrast with:

  • Connection-draining cutover — existing connections finish naturally, new connections go to the new system. Doesn't work for long-lived pooled connections, makes in-flight queries visible to the migration.
  • Error-retry cutover — cut over abruptly, rely on client-side retry. Visible error spikes, retry-sensitive workloads suffer.
  • Query buffering cutover — queries pause at the proxy, the proxy dispatches them against the new backend once routing flips. Client sees a very brief latency spike instead of errors.

Architectural shape

Requires a proxy layer in front of the database that:

  1. Terminates the client connection protocol (MySQL wire, Postgres wire, HTTP, etc).
  2. Can hold inbound queries in a queue per logical keyspace / table / route with bounded memory and a bounded time budget.
  3. Can be told atomically to re-route queries from route A to route B.
  4. Releases the buffered queries against the new route once the cutover completes.

The proxy usually has its own health-and-timeout guarantees — if the cutover takes too long, buffered queries are either released against the old backend (abort cutover) or timed out cleanly with an error (explicit abort).

Canonical wiki instances

  • Vitess / VTGate — VTGate Buffering is the canonical implementation. Used during MoveTables SwitchTraffic cutover: writes on source keyspace are stopped, queries buffer in VTGate, replication catches up fully, routing rules flip, buffered queries execute against the new keyspace. "The query buffering done here is the last part that allows the entire migration to be done without any downtime." (Source: sources/2026-02-16-planetscale-zero-downtime-migrations-at-petabyte-scale.) Also used during planned primary failover inside a Vitess keyspace — a connection-bearing reparent. Typical cutover takes "less than 1 second."

  • PlanetScale for Postgres proxy layer — PlanetScale's proprietary Postgres proxy provides "automatic failovers, query buffering, and connection pooling via our proprietary proxy layer, which includes PgBouncer for connection pooling." (Source: sources/2025-07-01-planetscale-planetscale-for-postgres.) Same shape as VTGate buffering, different engine — the proxy layer buffers queries during automatic failovers so clients don't see errors even when the primary is being swapped.

Seen in

Last updated · 319 distilled / 1,201 read