SYSTEM

PlanetScale HTTP API¶

What it is¶

PlanetScale HTTP API is a publicly-accessible gRPC-compatible HTTP interface in front of PlanetScale's MySQL-protocol database, built so that clients which cannot speak the MySQL binary wire protocol — principally serverless / FaaS runtimes and browser contexts — can still run queries. Implemented server-side on connect-go (a gRPC-compatible RPC framework); clients can use HTTP/2 or HTTP/3 as the transport (Source: ).

Why it exists¶

Serverless runtimes cannot open raw TCP sockets to databases. "In serverless compute contexts, your code is fundamentally not able to open up a TCP socket and speak the MySQL binary protocol to us. The platforms require communication through HTTP(S), so this ended up being a nice fit." The HTTP API was built to serve this constraint; benchmark results (see source) show it also wins on cold-start cost in all network shapes and on large payloads over unreliable networks.

Public consumers¶

PlanetScale Serverless driver for JavaScript — the first production consumer; targets Vercel Edge / Cloudflare Workers / AWS Lambda class runtimes.
PlanetScale Connect — the ELT/CDC feature uses the HTTP API as one of its integration surfaces.
PlanetScale web console — the in-product UI speaks the HTTP API transparently; connections use HTTP/3 when the browser supports it.
Experimental Go database/sql driver — the benchmark proof-of-concept from the 2023-01-04 post; not shipped as a public driver.

Wire format¶

RPC framework: connect-go (gRPC- compatible).
Encoding: protobuf.
Compression: Snappy (client-side; the wire is pre-compressed before being sent).
Transports: HTTP/2 (stdlib clients) or HTTP/3 (via quic-go or equivalent QUIC library).

Architectural properties¶

Multiplexes many logical MySQL sessions over one HTTP connection — removing per-session connection-pool pressure in serverless runtimes that can't afford to maintain a pool.
TLS 1.3 required (HTTP/3 mandatory; HTTP/2 practical) — [[concepts/tls-1-3-zero-rtt-handshake|0-RTT handshake resumption]] saves a full round trip on every new connection vs TLS 1.2.
Client-side query compression possible — unlike the MySQL binary protocol, where the server must decompress what the client sends; Snappy-on-the-wire lets INSERT-heavy workloads save bandwidth before the bytes hit the PlanetScale fabric.

Status¶

Experimental / not publicly documented for direct use at the time of the 2023-01-04 post: "This API is not documented for public consumption just yet (it will be, I promise), but it is gRPC compatible." Consumer access is through the published JavaScript driver + Connect + web console — not by hand-rolled gRPC clients.
Production runtime is deployed; the benchmark post measures this running system, not a staging build.

Why it shows up on this wiki¶

First canonical wiki example of a production database vendor shipping an HTTP API alongside the native binary protocol, explicitly positioned for serverless / browser consumers. Sister shape to CDN-fronted object stores and BigQuery-class SQL-over-HTTP endpoints, but the first wiki instance in the OLTP-database family.

Seen in¶

— the first public announcement that an HTTP API exists behind PlanetScale. Launch-post framing: "Backing our new driver is a new HTTP API and global routing infrastructure to support it. Note: The HTTP API is currently not documented, but we plan on documenting it when we're ready to officially release it." The serverless driver is shipped as the sole supported consumer at this point. Names the four structural advantages: TLS 1.3, HTTP/2 multiplexing, gzip/brotli/snappy compression, global routing.
— canonical disclosure. Benchmark of Go client against this API over HTTP/2 + HTTP/3 vs direct MySQL binary protocol. Production-deployed behind the PlanetScale web console + JS driver + Connect; experimental for public consumption.