Skip to content

PATTERN Cited by 2 sources

HTTP API alongside binary protocol

Pattern

Ship an HTTP-based version of your database / service protocol next to the native binary protocol, not replacing it. The HTTP API is a first-class citizen — authenticated, multiplexed, versioned, featurefully equivalent for the workloads that need it — so that clients which cannot open raw TCP sockets (serverless / edge runtimes, browsers, restricted networks) can participate. The binary protocol stays the default for long-lived server clients that want its efficiency.

Canonical instance

PlanetScale HTTP API is a gRPC-compatible HTTP interface that sits in front of PlanetScale's MySQL-protocol database, shipped as the transport for:

The native MySQL protocol continues to serve every non-restricted client. Launch framing: "Until today, you could not use PlanetScale in these environments because they require external connections to be made over HTTP and not other networking protocols… Our new driver uses secure HTTP, which allows you to use PlanetScale in these constrained environments." (Source: sources/2026-04-21-planetscale-introducing-the-planetscale-serverless-driver-for-javascript.)

Why ship two protocols instead of migrating to one

  1. Audience segmentation: long-lived server clients have very different needs from per-invocation serverless clients. A binary protocol with session state works for the former; a stateless request/response HTTP API works for the latter. One protocol forced to serve both ends up compromised for each.
  2. Ecosystem inertia: existing customer applications speak the native MySQL / Postgres / Redis protocol through driver-rich ecosystems (ORMs, connection poolers, migration tools). Breaking this is expensive. Adding HTTP leaves the ecosystem intact.
  3. HTTP's structural advantages that the binary protocol can't easily graft on:
  4. Runs in runtimes that don't permit raw TCP (concepts/serverless-tcp-socket-restriction).
  5. Gets stream multiplexing for free from HTTP/2 / HTTP/3.
  6. Gets TLS 1.3 for free from the HTTP ecosystem.
  7. Gets client-side compression that the MySQL wire protocol doesn't natively support.

Adjacent shapes

  • SQL-over-HTTP for analytics (BigQuery, Snowflake REST APIs): same pattern, different workload. Analytics SQL is request/response by nature; the native ODBC/JDBC stacks are already somewhat HTTP-shaped.
  • NoSQL-HTTP-native databases (DynamoDB, Firestore, CosmosDB): skip the binary protocol altogether; HTTP is the only client protocol. They don't face the "alongside" problem because they never built the binary version.
  • Redis REST façades (Upstash): HTTP wrapper maintained by a third party; the canonical Redis client ecosystem stays on RESP/TCP. Demonstrates the pattern can be executed by a vendor other than the database's primary-protocol author.
  • Proxy-based alternative (Cloudflare Hyperdrive): instead of a vendor-side HTTP API, put a proxy in the compute tier that speaks the Worker-side binding and holds the TCP connection itself. Same problem-space, inverted architecture.

Execution details

  • Protocol shape: the PlanetScale HTTP API is gRPC-compatible via connect-go — not hand-rolled REST. Benefits: typed protobuf messages, automatic backward-compatible schema evolution, existing gRPC tooling. The wire is HTTP/2 or HTTP/3 with protobuf bodies and Snappy compression.
  • SQL sanitisation at the client: parameterised queries still work; the driver handles injection prevention — "The driver also handles your SQL sanitization to help prevent security issues like SQL injection" (Source: sources/2026-04-21-planetscale-introducing-the-planetscale-serverless-driver-for-javascript). The HTTP API is a transport, not an injection vector.
  • Undocumented-by-default rollout: PlanetScale kept the HTTP API undocumented at launch, shipping only the first-party driver as the supported consumer. "The HTTP API is currently not documented, but we plan on documenting it when we're ready to officially release it." This lets the protocol evolve behind the driver boundary without locking in a public API contract.

Numeric evidence it's not a perf regression

The 2023-01-04 benchmark post measures HTTP/2 and HTTP/3 clients against the native MySQL binary protocol:

  • Cold-start Connect + SELECT 1 (Reno NV → us-west-2): MySQL 162 ms → HTTP ~35 ms (~4.6× reduction).
  • Cold-start Connect + SELECT 1 (us-west-2 → us-west-2): MySQL 11 ms → HTTP 3–4 ms (~3× reduction).
  • Steady-state parallel SELECT 1: all three protocols statistically indistinguishable.

(Source: sources/2026-04-21-planetscale-faster-mysql-with-http3.)

HTTP is faster on cold start, parity on warm path, and structurally better on serverless — which is the justification for serving it alongside the binary protocol rather than treating it as a second-class fallback.

Seen in

Last updated · 378 distilled / 1,213 read